Delivery options

List timeslots for Delivery

GET api.foodin.ai/users/{user_id}/service_options/cart/delivery

Lists the available delivery service options for the customer's location and cart items. In this context, service options are time slots, such as Within 5 hours or Friday 9am-11am. Availability is based on current and anticipated deliverer availability for the relevant store and delivery location.

By default, the time slots returned are immediate and scheduled time slots. If ETA options are enabled in your store configuration, you can retrieve ETA time slots instead of immediate time slots. To get a standard ETA time slot with the scheduled time slots, set the with_eta_options field to true. To also retrieve a priority ETA time slot, set the with_priority_eta_options field to true. For more information, see Retrieve an ETA time slot.

If the customer address is more than 30 minutes away from the selected store, the long_distance_delivery flag is set to true. You can deliver to this address if long distance delivery is enabled for the store. For more information, see Service areas for delivery.

If you’d like more flexibility with your time slots, you can send Foodin your desired windows. Foodin uses your desired windows to map to available service options and returns the available time slots for the desired windows.

Parameters

Field	Type	Description
user_id	string	The ID of the user.

Request

Field	Type	Description
address	Object	The address for the delivery
Items	Array(Items)	The items for delivery.
desired_windows	Array(Desired_windows)	The desired windows for service options.
location_code	string	The location code of the store fulfilling the order.
with_eta_options	boolean	Returns ETA options instead of immediate when true. Defaults to false.
with_priority_eta_options	boolean	Returns Priority ETA options instead of immediate when true. Defaults to false.

Address Object

Field	Type	Description
address_line_1	string	The first address line.
address_line_2	string	The second address line.
address_type	string	The type of address, e.g., "residential".
postal_code	string	The postal/zip code of the address.

Items Object

Field	Type	Description
line_num	String	The item's line number in the order.
count	Integer	The count of the item. Must be a non-negative integer.
weight	number	The weight of the item (defaults to kg in the US). Must be a non-negative number.
special_instructions	string	Any special instructions about the item selection.
replacement_policy	string	One of "no_replacements", "users_choice" (default if replacement_items specified), or "deliverers_choice" (default otherwise).
replacement_items	Array	A list of requested replacement items if the original item could not be found. This field needs to be turned on via configuration.
item	Object	The item's code.

Replacement_items Object

Field	Type	Description
upc	string	The item's universal product code (upc).

Item Object

Field	Type	Description
upc	string	The item's universal product code (upc).

Desired_windows Object

Field	Type	Description
starts_at	string	Start time of the desired window in ISO 8601 format.
ends_at	string	End time of the desired window in ISO 8601 format.

Request examples

const axios = require("axios");
 
async function sendDeliveryRequest(token) {
  const deliveryData = {
    address: {
      address_line_1: "string",
      address_line_2: "string",
      address_type: "string",
      postal_code: "string",
    },
    items: [
      {
        line_num: "string",
        count: 1,
        weight: 1,
        special_instructions: "string",
        replacement_policy: "no_replacements",
        replacement_items: [
          {
            upc: "string",
          },
        ],
        item: {
          upc: "string",
        },
      },
    ],
    desired_windows: [
      {
        starts_at: "string",
        ends_at: "string",
      },
    ],
    location_code: "string",
    with_eta_options: true,
    with_priority_eta_options: true,
  };
 
  const config = {
    headers: {
      Accept: "application/json",
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
  };
 
  try {
    const response = await axios.post(
      "https://api.foodin.ai/ users/{user_id}/service_options/cart/delivery",
      deliveryData,
      config
    );
    console.log(response.data);
  } catch (error) {
    console.error(error);
  }
}

Response

Field	Type	Description
service_options	Array	The item's line number in the order.
warnings	Integer	The count of the item. Must be a non-negative integer.
flags	Object	Additional properties of the address.

Service_options Object

Field	Type	Description
id	integer	The ID of the service option.
service_option_reference	String	The reference of the service option.
date	String	The date the service will take place in ISO 8601 format.
handoff_time	String	The ETA for deliverer to arrive at store.
Window	Object	The time window when the service will take place.
Availability	Object	The availability of this service option.

Availability Object

Field	Type	Description
available	boolean	Indicates if this service option is available for the user.
reasons	Array(string)	The reasons for unavailability of a service option. Currently, the reasons are related to the laws governing the sale of alcohol. For example, restrictions on quantity, delivery time, pickup, and matched city and county of stores and customers. The reasons are subject to change without notice.
item_codes	Array(string)	The item codes which caused the option to be unavailable.

Window Object

Field	Type	Description
start_at	string	The start of the delivery window in ISO 8601 format.
end_at	string	The end of the delivery window in ISO 8601 format.
type	string	The type of service option. One of 'scheduled', 'eta' or 'asap’.
asap	boolean	Indicates if delivery will happen as soon as possible. Only true when type is asap.

Warnings Object

Field	Type	Description
error	Object	Information relevant to the error.
end_at	string	The end of the delivery window in ISO 8601 format.
type	string	The type of service option. One of 'scheduled', 'eta' or 'asap’.
asap	boolean	Indicates if delivery will happen as soon as possible. Only true when type is asap.

Reasons for unavailability of a service option

Reason	Description
State law restricts amount of `{beer/wine/spirits}` to `{#}` fl oz, cart quantity is: `{#}` fl oz.	The quantity of this alcohol type exceeds the country/state law limit..
Error validating alcohol quantities. Please try again.	The quantity of alcohol can’t be validated.
Unmatched city and county	The city and county of the store and customer must match.
Cannot deliver alcohol to this postal code	Partner can’t deliver alcohol to this postal code.
State law doesn't allow delivery of alcohol in this window	Partners can’t deliver alcohol in this delivery window because of state law.

Success 200 With unavailability reasons

{
  "service_options": [
    {
      "id": 13,
      "service_option_reference": "ezppZD0-MTMsIDp0eXBlPT4iU2NoZWR1bGVkRGVsaXZlcnlPcHRpb24iLCA6d2luZG93PT48SW5zdGFjYXJ0OjpFbnRlcnByaXNlOjpCb2JhOjpDb3JlOjpUeXBlczo6VjE6OlNlcnZpY2VPcHRpb25TY2hlZHVsZWRXaW5kb3c6IGRlc2NyaXB0b3I6ICIiLCBzdGFydF9hdDogPEdvb2dsZTo6UHJvdG9idWY6OlRpbWVzdGFtcDogc2Vjb25kczogMTUxOTI1NzYwMCwgbmFub3M6IDA-LCBlbmRfYXQ6IDxHb29nbGU6OlByb3RvYnVmOjpUaW1lc3RhbXA6IHNlY29uZHM6IDE1MTkyNjQ4MDAsIG5hbm9zOiAwPj59",
      "date": "2022-02-22",
      "window": {
        "start_at": "2022-02-22T00:00:00Z",
        "end_at": "2022-02-22T02:00:00Z",
        "type": "scheduled",
        "asap": false
      },
      "availability": {
        "available": false,
        "reasons": [
          "State law doesn't allow delivery of alcohol in this window"
        ],
        "item_codes": ["000000004011"]
      }
    }
  ],
  "warnings": []
}

Success 200 Cart service options returned

{
  "service_options": [
    {
      "id": 198,
      "service_option_reference": "ezppZD0-MTk4LCA6dHlwZT0-IlNjaGVkdWxlZERlbGl2ZXJ5T3B0aW9uIiwgOndpbmRvdz0-PEluc3RhY2FydDo6RW50ZXJwcmlzZTo6Qm9iYTo6Q29yZTo6VHlwZXM6OlYxOjpTZXJ2aWNlT3B0aW9uU2NoZWR1bGVkV2luZG93OiBkZXNjcmlwdG9yOiAiIiwgc3RhcnRfYXQ6IDxHb29nbGU6OlByb3RvYnVmOjpUaW1lc3RhbXA6IHNlY29uZHM6IDE1MTkyNTc2MDAsIG5hbm9zOiAwPiwgZW5kX2F0OiA8R29vZ2xlOjpQcm90b2J1Zjo6VGltZXN0YW1wOiBzZWNvbmRzOiAxNTE5MjY0ODAwLCBuYW5vczogMD4-fQ==",
      "date": "2022-02-22",
      "window": {
        "start_at": "2022-02-22T00:00:00Z",
        "end_at": "2022-02-22T02:00:00Z",
        "type": "scheduled",
        "asap": false
      },
      "availability": {
        "available": true,
        "reasons": [],
        "item_codes": []
      }
    },
    {
      "id": 199,
      "service_option_reference": "ezppZD0-MTk5LCA6dHlwZT0-IkltbWVkaWF0ZURlbGl2ZXJ5T3B0aW9uIiwgOndpbmRvdz0-PEluc3RhY2FydDo6RW50ZXJwcmlzZTo6Qm9iYTo6Q29yZTo6VHlwZXM6OlYxOjpTZXJ2aWNlT3B0aW9uSW1tZWRpYXRlV2luZG93OiBkZXNjcmlwdG9yOiAiIiwgaW1tZWRpYXRlX2hvdXI6IDU-fQ==",
      "date": "2022-02-22",
      "window": {
        "immediate_hour": 5,
        "type": "immediate"
      },
      "availability": {
        "available": true,
        "reasons": [],
        "item_codes": []
      }
    },
}

4XX Errors

Code	Cause	Error Message
400	User Not Found	"User Not Found"
400	Invalid location code	"Could not find specified store."
400	No weight or count provided*	"There were issues with your request"
400	No stores found	"No store location found for given address."
400	Invalid items	"1 item not found."
400	Cannot deliver to address	"Unfortunately, we cannot deliver to that area."
400	Store does not support delivery to address	"We do not currently support delivery from this store to the selected address."
400	Invalid Quantity, expected weight	"One of these items had an invalid quantity amount, 0001234567892 expected weight"
400	Invalid Quantity, expected count	"One of these items had an invalid quantity amount, 0001234567892 expected count"
400	Duplicate items were provided	"Duplicate items provided for this order."
400	Priority ETA options not configured	"Priority ETA options are not configured for this store."
400	ETA options not configured	"ETA options are not configured for this store."
400	Without address	"can't be blank"
403	User Not Active	"User Not Active"
404	Resource not found	"Resource not found"

Compliance Pickup Options