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.

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

danger

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.

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.

note

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.

Security​

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

Parameters​

NameInTypeRequiredDescription
user_idpathstring✅The ID of the user.

Request​

FieldTypeRequiredDescription
order_idstring✅The unique retailer-generated order ID to use for the order. The ID can be used later for lookup.
service_option_hold_idinteger✅The ID of the service option hold.
loyalty_numberstringThe loyalty number to use for this transaction.
initial_tip_centsinteger✅The pre-delivery tip amount in cents.
leave_unattendedbooleanIndicator if the customer wants the driver to leave the order unattended. Defaults to false.
special_instructionsstringSpecial instructions about the order to pass on to the shopper.
location_codestringThe store location code used to look-up cart items.
paid_with_ebtbooleanIndicator if the order contains an EBT payment. Defaults to false.
localestringThe order's locale in IETF Language Tag format. Example: en-US.
applied_expressbooleanDeprecated. Use `applied_instacartplus` instead. Indicates whether the retailer applied Instacart+ membership benefits to the order. Defaults to false.
applied_instacartplusbooleanIndicates whether the retailer applied Instacart+ membership benefits to the order. Defaults to false.
userUserAny additional attributes for the user, these take precedence over values set during user create.
addressAddress✅The address being delivered to.
itemsArray(Items)✅The items for the order.

User Object​

FieldTypeRequiredDescription
birthdaystringThe user's birthday in ISO 8601 format, this is used for alcohol eligibility validation.
phone_numberstringThe user's phone number.
sms_opt_inbooleanIndicator whether the user has opted-in to receive SMS communications.

Address Object​

FieldTypeRequiredDescription
address_line_1string✅The first address line.
address_line_2stringThe second address line.
address_typestringThe type of address, e.g., "residential".
postal_codestring✅The postal/zip code of the address.

Items Object​

FieldTypeRequiredDescription
line_numstring✅The item's line number in the order.
countintegerThe count of the item. Must be a non-negative integer.
weightnumberFor items sold by weight, the numerical weight of the item. 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_instructionsstringAny special instructions about the item selection.
replacement_policystringOne of "no_replacements", "users_choice" (default if replacement_items specified), or "shoppers_choice" (default otherwise).
replacement_itemsArray(Replacement_items)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.
itemItem✅The item's code.

Replacement_items Object​

One of the following:

FieldTypeRequiredDescription
upcstring✅The item's universal product code (upc).

or

FieldTypeRequiredDescription
rrcstring✅The item's retailer reference code (rrc).

Item Object​

One of the following:

FieldTypeRequiredDescription
upcstring✅The item's universal product code (upc).

or

FieldTypeRequiredDescription
rrcstring✅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",
  "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"
  },
  "items": [
    {
      "line_num": "string",
      "count": 1,
      "weight": 1,
      "special_instructions": "string",
      "replacement_policy": "no_replacements",
      "replacement_items": [
        {
          "upc": "string"
        }
      ],
      "item": {
        "upc": "string"
      }
    }
  ]
}'

Response​

FieldTypeRequiredDescription
idstring✅The ID of the order.
statusstring✅The current order status.
order_urlstringLink to view the order.
created_atstringThe time of order creation in ISO 8601 format.
cancellation_reasonstringThe reason the order was canceled.
localestringThe order's locale in POSIX format. Example: en_US.
is_expressbooleanDeprecated. Use `is_instacartplus` instead. Indicates whether the order received Instacart+ membership benefits. Defaults to false.
is_instacartplusbooleanIndicates whether the order received Instacart+ membership benefits. Defaults to false.
fulfillment_detailsFulfillment_detailsThe order delivery details.
warningsArray(Warnings)Any warnings associated with this request.
itemsArray(Items)The items in the order.

Fulfillment_details Object​

FieldTypeRequiredDescription
store_locationstringThe 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_atstring✅The start time of the delivery window in ISO 8601 format.
window_ends_atstring✅The end time of the delivery window in ISO 8601 format.
delivered_atstringThe time the order was delivered in ISO 8601 format.
bag_countintegerThe number of bags in the order.
handoff_window_starts_atstringThe start time of the handoff window in ISO 8601 format.
handoff_window_ends_atstringThe end time of the handoff window in ISO 8601 format.

Warnings Object​

FieldTypeRequiredDescription
errorErrorInformation relevant to the error.
metaMetaThe error metadata.

Error Object​

FieldTypeRequiredDescription
messagestringThe error message.
error_codeintegerThe error code.

Meta Object​

FieldTypeRequiredDescription
itemsArray(Items)The items that triggered the error.

Items Object​

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

Items Object​

FieldTypeRequiredDescription
line_numstring✅The item's line number in the order.
qtynumberThe quantity of the item.
qty_unitstringThe quantity type, either "each" or "lb".
qty_fulfillednumberThe fulfilled quantity of the item.
qty_fulfilled_unitstringThe fulfilled quantity type, either "each" or "lb".
qty_requestednumberThe initally requested quantity of the item.
qty_requested_unitstringThe initally requested quantity type, either "each" or "lb".
replacedbooleanIndicates whether the item was replaced.
scan_codestringThe scan code of the item.
replacement_policystringThe replacement policy for the item.
shopper_provided_item_namestringThe item name provided by shoppers for items that they added.
shopper_provided_item_priceShopper_provided_item_priceThe item price provided by shoppers for items that they added.
itemItem✅The item's codes.

Shopper_provided_item_price Object​

FieldTypeRequiredDescription
amountnumber✅The amount of a specified currency.
currencystring✅The currency type in ISO 4217 format. For example: USD.

Item Object​

FieldTypeRequiredDescription
upcstringThe item's universal product code (UPC).
rrcstringThe item's retailer reference code (RRC).
requested_upcstringThe requested item's universal product code (UPC).
requested_rrcstringThe requested item's retailer reference code (RRC).
delivered_upcstringThe delivered item's universal product code (UPC).
delivered_rrcstringThe 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-31796",
    "window_starts_at": "2018-02-22T00:00:00Z",
    "window_ends_at": "2018-02-22T00:30:00Z"
  },
  "items": [
    {
      "line_num": "1",
      "qty": 5,
      "qty_unit": "each",
      "replaced": false,
      "scan_code": "00070481001112",
      "replacement_policy": "shoppers_choice",
      "item": {
        "upc": "123456789013",
        "rrc": "",
        "requested_upc": "123456789013",
        "requested_rrc": "",
        "delivered_upc": "123456789013",
        "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"}
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: $500.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"9999{}
400Fails alcohol compliance check"Alcoholic items can not be added to this order. Please remove and retry."2001{}
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."1003{}
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"}]}
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"}
403Inactive user"User Not Active"null{}
404Order not found"Resource not found"4000{}
* Multiple error
Last updated on