Create a pickup order

POST api.foodin.ai/users/{user_id}/orders/pickup

Creates a delivery order for the reserved time slot. If the reservation has expired, Foodin still attempts to book the time slot. If, however, the time slot capacity is filled, your site needs to prompt the customer to select another time slot.

Some products required age validation in accordance with regional laws, such as alcohol and over-the-counter medication. When a cart contains an age-restricted product, the store site must request the customer’s date of birth and include it in the order sent to Foodin.

Request

Parameters

Field	Type	Description
user_id	string	The ID of the user.

Order parameters

Field	Type	Description
order_id	string	The unique store-generated order ID to use for the order. The ID can be used later for lookup.
service_option_hold_id	integer	The ID of the service option hold.
loyalty_number	string	The loyalty number to use for this transaction.
special_instructions	string	Special instructions about the order to pass on to the deliverer.
location_code	string	The store location code used to look-up cart items.
locale	string	The order's locale in IETF Language Tag format. Example: en-US.
user	Object	Any additional attributes for the user, these take precedence over values set during user create.
items	Array(Items)	The items for the order.

User Object

Field	Type	Description
birthday	string	The user's birthday in ISO 8601 format, this is used for alcohol eligibility validation.
phone_number	string	The user's phone number.
sms_opt_in	Boolean	Indicator whether the user has opted-in to receive SMS communications.

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 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).

Request examples

const request = require("request");
 
const options = {
  method: "POST",
  url: "https://api.foodin.ai/users/{user_id}/orders/pickup",
  headers: {
    Accept: "application/json",
    Authorization: "Bearer <token>",
    "Content-Type": "application/json",
  },
  data: {
    order_id: "string",
    service_option_hold_id: 1,
    loyalty_number: "string",
    special_instructions: "string",
    location_code: "string",
    locale: "string",
    applied_express: true,
    user: {
      birthday: "string",
      phone_number: "string",
      sms_opt_in: true,
    },
    items: [
      {
        line_num: "string",
        count: 1,
        weight: 1,
        special_instructions: "string",
        replacement_policy: "no_replacements",
        replacement_items: [
          {
            upc: "string",
          },
        ],
        item: {
          upc: "string",
        },
      },
    ],
  },
};
 
request(options, function (error, response, body) {
  if (error) throw new Error(error);
  console.log(body);
});

Response

Field	Type	Description
id	string	The ID of the order.
status	string	The current order status.
order_url	string	Link to view the order.
created_at	string	The time of order creation in ISO 8601 format.
cancellation_reason	string	The reason the order was canceled.
locale	string	The order's locale in POSIX format. Example: en_US.
fulfillment_details	Object	The order delivery details.
warnings	Array	Any warnings associated with this request.
items	Array	The items in the order.
id	string	The ID of the order.

Fulfillment_details Object

Field	Type	Description
store_location	string	The location code of the store where the order was fulfilled. The store_location is often the same as the location_code that was used to create the order. However, orders can be fulfilled from a different store location.
window_starts_at	string	The start time of the delivery window in ISO 8601 format.
window_ends_at	string	The end time of the delivery window in ISO 8601 format.
delivered_at	string	The time the order was delivered in ISO 8601 format.
bag_count	integer	The number of bags in the order.
handoff_window_starts_at	string	The start time of the handoff window in ISO 8601 format.
handoff_window_ends_at	string	The end time of the handoff window in ISO 8601 format.

Warnings Object

Field	Type	Description
error	Object	Information relevant to the error.
meta	Object	The error metadata.

Meta Object

Field	Type	Description
items	Array	The items that triggered the error.

Items Array

Field	Type	Description
item_code	string	The store reference code (RRC) or universal product code (UPC) of an item that triggered the error.

Items Object

Field	Type	Description
line_num	string	The item's line number in the order.
qty	number	The quantity of the item.
qty_unit	string	The quantity type, either "each" or "kg".
qty_fulfilled	number	The fulfilled quantity of the item.
qty_fulfilled_unit	string	The fulfilled quantity type, either "each" or "kg".
qty_requested	number	The initally requested quantity of the item.
qty_requested_unit	string	The initally requested quantity type, either "each" or "kg".
replaced	boolean	Indicates whether the item was replaced.
scan_code	string	The scan code of the item.
replacement_policy	string	The replacement policy for the item.
deliverer_provided_item_name	string	The item name provided by deliverers for items that they added.
deliverer_provided_item_price	Object	The item price provided by deliverers for items that they added.
item	Object	The item's codes.

Deliverer_provided_item_price Object

Field	Type	Description
amount	number	The amount of a specified currency.
currency	string	The currency type in ISO 4217 format. For example: USD.

Item Object

Field	Type	Description
upc	string	The item's universal product code (UPC).
rrc	string	The item's store reference code (RRC).
requested_upc	string	The requested item's universal product code (UPC).
requested_rrc	string	The requested item's store reference code (RRC).
delivered_upc	string	The delivered item's universal product code (UPC).
delivered_rrc	string	The delivered item's store reference code (RRC).

Response examples

200 Order created with item upc

{
  "id": "12345676789012345678780",
  "status": "created",
  "order_url": "https://foodin.ai/example_store/example-order",
  "created_at": "2022-02-22T00:00:00Z",
  "cancellation_reason": "deliverer_driven",
  "locale": "en_US",
  "is_express": true,
  "fulfillment_details": {
    "store_location": "000-3645",
    "window_starts_at": "2022-02-22T00:00:00Z",
    "window_ends_at": "2022-02-22T00:30:00Z"
  },
  "items": [
    {
      "line_num": "1",
      "qty": 5,
      "qty_unit": "each",
      "replaced": false,
      "scan_code": "00070481001112",
      "replacement_policy": "deliverers_choice",
      "item": {
        "upc": "123456789013",
        "rrc": "",
        "requested_upc": "123456789013",
        "requested_rrc": "",
        "delivered_upc": "123456789013",
        "delivered_rrc": ""
      }
    }
  ]
}

200 Order created with item rrc

{
  "id": "12345676789012345678780",
  "status": "created",
  "order_url": "https://foodin.ai/example_store//example-order",
  "created_at": "2022-02-22T00:00:00Z",
  "cancellation_reason": "deliverer_driven",
  "locale": "en_US",
  "is_express": true,
  "fulfillment_details": {
    "store_location": "000-3731",
    "window_starts_at": "2022-02-22T00:00:00Z",
    "window_ends_at": "2022-02-22T00:30:00Z"
  },
  "items": [
    {
      "line_num": "10",
      "qty": 10,
      "qty_unit": "each",
      "replaced": false,
      "scan_code": "00070481001121",
      "replacement_policy": "deliverers_choice",
      "item": {
        "upc": "123456789022",
        "rrc": "011-849503940",
        "requested_upc": "123456789022",
        "requested_rrc": "011-849503940",
        "delivered_upc": "123456789022",
        "delivered_rrc": "011-849503940"
      }
    }
  ]
}

4XX Errors

Code	Cause	Error Message
400	Invalid user id	"User Not Found"
400	Expired ETA option hold	"ETA option hold has expired."
400	Invalid replacement_policy	"is not included in the list"
400	Invalid quantity (negative count)	"must be greater than or equal to 0"
400	Invalid quantity (negative weight)	"must be greater than or equal to 0"
400	Invalid postal code	"not found"
400	Unsupported postal code	"not supported"
400	Invalid service option hold	"Hold not found"
400	User and order without phone number	"can't be blank"
400	Invalid location code	"Could not find specified store."
400	Invalid order params*	"There were issues with your request"
400	Fails alcohol compliance check	"Alcoholic items can not be added to this order. Please remove and retry."
400	Invalid items	"2 items not found."
400	Order id already exists	"Order already in use."
400	Request could not be processed at this time	"The request could not be completed at this time, try again later."
400	Duplicate items were provided	"Duplicate items provided for this order."
400	Alcohol outside of allowed time window	"State law restricts selling alcohol during the window you selected. Please change your delivery window to add alcohol."
400	Deactivated user account	"The user account was deactivated."
400	Service option is no longer available	"The pickup time you selected is no longer available - please select another time"
403	Inactive user	"User Not Active"

Create Order Create Direct Order