Product API
Fulfillment guide
Service Options
Direct Delivery Options

List timeslots for direct delivery

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

Lists the available direct delivery service options for the customer's location and cart details. In this context, service options are time slots, such as Today 4pm-6pm 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.

Request

Parameters

FieldTypeDescription
addressObjectThe address of the user.
location_codestringLocation code of the store where the delivery driver picks up the order. Either postal code or location code is required.
cart_total_centsintegerThe total value of all items for the order in cents.
items_countintegerThe number of different types of items in the order.
units_countnumberThe number of all items, including multiples of an item, in the order.
earliest_option_start_atstringThe earliest time that an order can be ready for delivery. Only time slots that start after this time are retrieved.
with_eta_optionsbooleanReturns ETA options instead of immediate options when true. Defaults to false.
with_priority_eta_optionsbooleanReturns Priority ETA options instead of immediate options when true. Defaults to false.
with_handoff_timebooleanIndicator whether the handoff time is calculated when fetching service option. Defaults to false.

Address Object

FieldTypeDescription
address_line_1stringThe first address line.
address_line_2stringThe second address line.
address_typestringThe type of address, e.g., "residential".
postal_codestringThe postal/zip code of the address.

Request example

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/direct, deliveryData, config);
    console.log(response.data);
  } catch (error) {
    console.error(error);
  }
}

Address Object

FieldTypeDescription
service_optionsArrayThe returned service options.

Service_options Object

FieldTypeDescription
idintegerThe ID of the service option.
service_option_referencestringThe reference of the service option.
datestringThe date the service will take place in ISO 8601 format.
handoff_timestringThe ETA for deliverer to arrive at store.
windowObjectThe time window when the service will take place.
availabilityObjectThe availability of this service option.

Availability Object

FieldTypeDescription
availablebooleanIndicates if this service option is available for the user.
reasonsArray(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_codesArray(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

ReasonDescription
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 countyThe city and county of the store and customer must match.
Cannot deliver alcohol to this postal codeStore can’t deliver alcohol to this postal code.
State law doesn't allow delivery of alcohol in this windowStore can’t deliver alcohol in this delivery window because of state law.

Response

200 With unavailability reasons

{
  "service_options": [
    {
      "id": 388,
      "service_option_reference": "ezppZD0-Mzg4LCA6dHlwZT0-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": []
      }
    }
  ]
}

200 Cart service options returned

{
  "service_options": [
    {
      "id": 389,
      "service_option_reference": "ezppZD0-Mzg5LCA6dHlwZT0-IkV0YURlbGl2ZXJ5T3B0aW9uIiwgOndpbmRvdz0-PEluc3RhY2FydDo6RW50ZXJwcmlzZTo6Qm9iYTo6Q29yZTo6VHlwZXM6OlYxOjpTZXJ2aWNlT3B0aW9uU2NoZWR1bGVkV2luZG93OiBkZXNjcmlwdG9yOiAiIiwgZW5kX2F0OiA8R29vZ2xlOjpQcm90b2J1Zjo6VGltZXN0YW1wOiBzZWNvbmRzOiAxNTE5MjY0ODAwLCBuYW5vczogMD4-fQ==",
      "date": "2022-02-22",
      "handoff_time": "2022-02-22T00:30:00Z",
      "window": {
        "start_at": "2022-02-22T00:00:00Z",
        "end_at": "2022-02-22T02:00:00Z",
        "type": "eta",
        "asap": false
      },
      "availability": {
        "available": true,
        "reasons": [],
        "item_codes": []
      }
    }
  ]
}

4XX Errors

CodeCauseError Message
400Handoff time is requested but not configured"Handoff time calculation is not configured for this store."
400Invalid location code"Specified store is not available for direct delivery."
400No stores found"No store location found for given address."
400Cannot deliver to address"Unfortunately, the store cannot deliver to that area."
400Store does not support delivery to address"The store doesn’t support delivery from this address to the selected address."
404Resource not found"Resource not found"