Skip to main content

Create a delivery order

POST /v2/fulfillment/users/{user_id}/orders/delivery

Creates a delivery order for the reserved time slot.

If the reservation has expired, Instacart 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. The response can take several seconds to return, so for the best customer experience, create the order as soon as possible after the customer completes your checkout process.

warning

If the items in the cart changed after a time slot was reserved, the order creation might fail. For details, see the returned error message.

Order item limitations​

If your request specifies an order containing items that exceed any of the following limitations, the order is not created:

  • Maximum total quantity of items
  • Maximum total weight of beverage items
  • Maximum quantity of large or bulky items

For more information about why an order couldn't be created, see the returned error message.

Age verification for alcohol​

Some products require age validation in accordance with regional laws, such as alcohol and over-the-counter medication. When a cart contains an age-restricted product, the retailer site must request the customer’s date of birth and include it in the order sent to Instacart. If the birthday is missing or the customer is not old enough to purchase the item, Instacart Connect returns an error or removes the item based on your configuration.

Store location​

You can specify the store location in the request. When a shopper shops for an order, they are asked to shop from the selected store location, but there is no guarantee that they shop there.

Phone number requirements​

If the user_id parameter in the request path references a user that doesn't have a phone_number, then user.phone_number is required in the body.

Security​

NameInDescription
AuthorizationheaderThe Authorization header with the bearer token acquired during authentication.

Parameters​

NameInTypeRequiredDescription
user_idpathstringRequired

The ID of the user.

Request​

Each items[] in the request requires either a count or a weight. The field that needs to be defined depends on that product's catalog configuration. For more information, see Product quantity types.

FieldTypeRequiredDescription
order_idstringRequired

The unique retailer-generated order ID to use for the order. The ID can be used later for lookup.

service_option_hold_idintegerRequired

The ID of the service option hold.

loyalty_numberstringOptional

The loyalty number to use for this transaction.

initial_tip_centsintegerRequired

The pre-delivery tip amount in cents.

leave_unattendedbooleanOptional

Indicator if the customer wants the driver to leave the order unattended. Defaults to false.

special_instructionsstringOptional

Special instructions about the order to pass on to the shopper.

location_codestringOptional

The store location code used to look-up cart items.

paid_with_ebtbooleanOptional

Indicator if the order contains an EBT payment. Defaults to false.

localestringOptional

The order's locale in IETF Language Tag format. Example: en-US.

metadataHashOptional

The order-level metadata.

applied_expressbooleanOptional

Deprecated. Use applied_instacartplus instead. Indicates whether the retailer applied Instacart+ membership benefits to the order. Defaults to false.

applied_instacartplusbooleanOptional

Indicates whether the retailer applied Instacart+ membership benefits to the order. Defaults to false.

userOrderUserOptional

Any additional attributes for the user, these take precedence over values set during user create.

addressExpandedAddressRequired

The address being delivered to.

itemsArray(OrderItem)Required

The items for the order.

OrderUser Object​

FieldTypeRequiredDescription
birthdaystringOptional

The user's birthday in ISO 8601 format, this is used for alcohol eligibility validation.

phone_numberstringOptional

The user's phone number.

sms_opt_inbooleanOptional

Indicator whether the user has opted-in to receive SMS communications.

ExpandedAddress Object​

FieldTypeRequiredDescription
address_line_1stringRequired

The first address line.

address_line_2stringOptional

The second address line.

address_typestringOptional

The type of address, e.g., "residential".

postal_codestringRequired

The postal/zip code of the address.

citystringOptional

The city or town of the address, e.g., "Chicago".

OrderItem Object​

FieldTypeRequiredDescription
line_numstringRequired

The item's line number in the order.

countintegerOptional

The count of the item. Must be a non-negative integer. Depending on the item's catalog configuration, either this field or 'weight' is required.

weightnumberOptional

For items sold by weight, the numerical weight of the item. Depending on the item's catalog configuration, either this field or 'count' is required. The API interprets this value as whatever unit of measure is defined for the item in the catalog, such as lb or kg. Must be a non-negative number.

special_instructionsstringOptional

Any special instructions about the item selection.

replacement_policystringOptional

One of "no_replacements", "users_choice" (default if replacement_items specified), or "shoppers_choice" (default otherwise).

metadataHashOptional

The item-level metadata.

replacement_itemsArray(Replacement_items)Optional

A list of requested replacement items if the original item could not be found. This field needs to be turned on via configuration. Contact your Instacart Connect representative.

itemItemRequired

The item's code.

Replacement_items Object​

One of the following:

FieldTypeRequiredDescription
upcstringRequired

The item's universal product code (upc).

or

FieldTypeRequiredDescription
rrcstringRequired

The item's retailer reference code (rrc).

Item Object​

One of the following:

FieldTypeRequiredDescription
upcstringRequired

The item's universal product code (upc).

or

FieldTypeRequiredDescription
rrcstringRequired

The item's retailer reference code (rrc).

Request examples​

curl --request POST \
  --url 'https://connect.instacart.com/v2/fulfillment/users/{user_id}/orders/delivery' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "order_id": "string",
  "service_option_hold_id": 1,
  "loyalty_number": "string",
  "initial_tip_cents": 1,
  "leave_unattended": true,
  "special_instructions": "string",
  "location_code": "string",
  "paid_with_ebt": true,
  "locale": "string",
  "metadata": {
    "key1": "value1",
    "key2": "value2"
  },
  "applied_express": true,
  "applied_instacartplus": true,
  "user": {
    "birthday": "string",
    "phone_number": "string",
    "sms_opt_in": true
  },
  "address": {
    "address_line_1": "string",
    "address_line_2": "string",
    "address_type": "string",
    "postal_code": "string",
    "city": "string"
  },
  "items": [
    {
      "line_num": "string",
      "count": 1,
      "weight": 1,
      "special_instructions": "string",
      "replacement_policy": "no_replacements",
      "metadata": {
        "key1": "value1",
        "key2": "value2"
      },
      "replacement_items": [
        {
          "upc": "string"
        }
      ],
      "item": {
        "upc": "string"
      }
    }
  ]
}'

Response​

FieldTypeRequiredDescription
idstringRequired

The ID of the order.

statusstringRequired

The current order status.

order_urlstringOptional

Link to view the order.

created_atstringOptional

The time of order creation in ISO 8601 format.

cancellation_reasonstringOptional

The reason the order was canceled.

localestringOptional

The order's locale in POSIX format. Example: en_US.

is_expressbooleanOptional

Deprecated. Use is_instacartplus instead. Indicates whether the order received Instacart+ membership benefits. Defaults to false.

is_instacartplusbooleanOptional

Indicates whether the order received Instacart+ membership benefits. Defaults to false.

metadataHashOptional

The order-level metadata.

fulfillment_detailsOrderFulfillmentDetailsOptional

The order delivery details.

warningsArray(Error)Optional

Any warnings associated with this request.

itemsArray(OrderItem)Optional

The items in the order.

OrderFulfillmentDetails Object​

FieldTypeRequiredDescription
store_locationstringOptional

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_atstringRequired

The start time of the delivery window in ISO 8601 format.

window_ends_atstringRequired

The end time of the delivery window in ISO 8601 format.

delivered_atstringOptional

The time the order was delivered in ISO 8601 format.

bag_countintegerOptional

The number of bags in the order.

handoff_window_starts_atstringOptional

The start time of the handoff window in ISO 8601 format.

handoff_window_ends_atstringOptional

The end time of the handoff window in ISO 8601 format.

Error Object​

FieldTypeRequiredDescription
errorErrorDetailsOptional

Information relevant to the error.

metaMetaErrorOptional

The error metadata.

ErrorDetails Object​

FieldTypeRequiredDescription
messagestringOptional

The error message.

error_codeintegerOptional

The error code.

MetaError Object​

FieldTypeRequiredDescription
itemsArray(ItemInfo)Optional

The items that triggered the error.

ItemInfo Object​

FieldTypeRequiredDescription
item_codestringOptional

The retailer reference code (RRC) or universal product code (UPC) of an item that triggered the error.

OrderItem Object​

FieldTypeRequiredDescription
line_numstringRequired

The item's line number in the order.

qtynumberOptional

The quantity of the item.

qty_unitstringOptional

The quantity type, either "each" or "lb".

qty_fulfillednumberOptional

The fulfilled quantity of the item.

qty_fulfilled_unitstringOptional

The fulfilled quantity type, either "each" or "lb".

qty_requestednumberOptional

The initally requested quantity of the item.

qty_requested_unitstringOptional

The initally requested quantity type, either "each" or "lb".

replacedbooleanOptional

Indicates whether the item was replaced.

scan_codestringOptional

The scan code of the item.

replacement_policystringOptional

The replacement policy for the item.

shopper_provided_item_namestringOptional

The item name provided by shoppers for items that they added.

metadataHashOptional

The item-level metadata.

shopper_provided_item_priceMoneyOptional

The item price provided by shoppers for items that they added.

itemItemRequired

The item's codes.

Money Object​

FieldTypeRequiredDescription
amountnumberRequired

The amount of a specified currency.

currencystringRequired

The currency type in ISO 4217 format. For example: USD.

Item Object​

FieldTypeRequiredDescription
upcstringOptional

The item's universal product code (UPC).

rrcstringOptional

The item's retailer reference code (RRC).

requested_upcstringOptional

The requested item's universal product code (UPC).

requested_rrcstringOptional

The requested item's retailer reference code (RRC).

delivered_upcstringOptional

The delivered item's universal product code (UPC).

delivered_rrcstringOptional

The delivered item's retailer reference code (RRC).

Response examples​

200 Success

{
  "id": "12345676789012345678780",
  "status": "created",
  "order_url": "https://example.com/example-order",
  "created_at": "2018-02-22T00:00:00Z",
  "cancellation_reason": "shopper_driven",
  "locale": "en_US",
  "is_express": true,
  "is_instacartplus": true,
  "fulfillment_details": {
    "store_location": "000-31820",
    "window_starts_at": "2018-02-22T00:00:00Z",
    "window_ends_at": "2018-02-22T00:30:00Z"
  },
  "items": [
    {
      "line_num": "8",
      "qty": 6,
      "qty_unit": "each",
      "replaced": false,
      "scan_code": "00070481001119",
      "replacement_policy": "shoppers_choice",
      "rx": false,
      "item": {
        "upc": "123456789020",
        "rrc": "",
        "requested_upc": "123456789020",
        "requested_rrc": "",
        "delivered_upc": "123456789020",
        "delivered_rrc": ""
      }
    }
  ]
}

4XX Errors

Error responses return either a single error or multiple errors.

HTTP CodeCauseError MessageError CodeError Meta
400Invalid user id"User Not Found"1001{"key":"user_id"}
400User with invalid phone number"Required parameter missing or invalid"1001{"key":"user_phone"}
400Invalid Quantity, expected count"One of these items had an invalid quantity amount, 0001234567892 expected count"2012{"item_code":"0001234567892","expected_param":"count","error_name":"WrongQuantityParameterError"}
400Expired ETA option hold"ETA option hold has expired."1001{"key":"service_option_hold_id"}
400Invalid replacement_policy"is not included in the list"1001{"key":"items[0].replacement_policy"}
400Invalid quantity (negative count)"must be greater than or equal to 0"1001{"key":"items[0].count"}
400Invalid quantity (negative weight)"must be greater than or equal to 0"1001{"key":"items[0].weight"}
400Invalid postal code"not found"1001{"key":"postal_code"}
400Unsupported postal code"not supported"1001{"key":"postal_code"}
400Invalid service option hold"Hold not found"1001{"key":"service_option_hold_id"}
400User and order without phone number"can't be blank"1001{"key":"user.phone_number"}
400Tip over maximum"Tip value is above maximum: $300.00."1001{"key":"initial_tip_cents"}
400Invalid location code"Could not find specified store."1001{"key":"location_code"}
400Invalid order params*"There were issues with your request"9999Not applicable
400Age requirement otc medicine"You must be over 18 to purchase over the counter medicine in your cart."1001{"items":[{"item_upc":"12345"}]}
400Fails alcohol compliance check"Alcoholic items can not be added to this order. Please remove and retry."2001Not applicable
400Invalid items"2 items not found."2000{"upcs":["111111111111","222222222222"],"items":[{"item_upc":"111111111111"},{"item_upc":"222222222222"}]}
400Invalid address"invalid_address"1001{"key":"address"}
400Invalid zip code for alcohol"Cannot deliver alcohol to this zip code."1001{"items":[{"item_upc":"928473737373"}],"key":"zip_code"}
400Order id already exists"Order already in use."1003Not applicable
400Request could not be processed at this time"The request could not be completed at this time, try again later."2003{"wait":"30"}
400Duplicate items were provided"Duplicate items provided for this order."2007{"duplicate_items":[{"item_upc":"123456789999","item_rrc":null,"line_num":"0"},{"item_upc":"123456789999","item_rrc":null,"line_num":"1"}]}
400Duplicate line nums"Duplicate line_num values not allowed: 1"2006{"duplicate_line_nums":["1"]}
400Alcohol outside of allowed time window"State law restricts selling alcohol during the window you selected. Please change your delivery window to add alcohol."2001{"upcs":["alcohol_upc"],"items":[{"item_upc":"alcohol_upc"}]}
400Deactivated user account"The user account was deactivated."1002{"key":"access_token"}
400Service option is no longer available"The delivery time you selected is no longer available - please select another time"1001{"key":"service_option_id"}
400Too many big and bulky items"The number of big and bulky items in your cart exceeds our maximum limit for a single delivery. Please remove 2 such items from your cart to continue."2023Not applicable
400Too much beverage"The weight of beverages in your cart exceeds our maximum limit for a single delivery. Please remove 20lb of beverages from your cart to continue."2026Not applicable
400Too many items"The number of items in your cart exceeds our maximum limit for a single delivery. Please remove 15 items from your cart to continue."2024Not applicable
400Too much weight"The total weight of items in your cart exceeds our maximum limit for a single delivery. Please remove 20 lb from your cart to continue."2027Not applicable
400Some items are not deliverable"Some items are not deliverable"2005{"items":[{"item_upc":"123456789075"}]}
400Invalid Quantity, expected weight"One of these items had an invalid quantity amount, some_upc expected weight"2012{"upc":"some_upc","item_code":"some_upc","expected_param":"weight"}
400User birthday missing or invalid for alcohol order"Required parameter missing or invalid"1001{"key":"user_birthday","items":[{"item_upc":"alcohol_upc"}]}
400Another order created recently"Another order has been recently created for this user, please try again in a little while."2003{"wait":10,"retry":true}
403Inactive user"User Not Active"nullNot applicable
404Order not found"Resource not found"4000Not applicable
* Multiple error
Last updated on