Skip to main content

Create a pickup order

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

Creates a pickup 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.

Security​

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

Parameters​

NameInTypeRequiredDescription
user_idpathstringRequiredThe ID of the user.

Request​

FieldTypeRequiredDescription
order_idstringRequiredThe unique retailer-generated order ID to use for the order. The ID can be used later for lookup.
service_option_hold_idintegerRequiredThe ID of the service option hold.
loyalty_numberstringOptionalThe loyalty number to use for this transaction.
special_instructionsstringOptionalSpecial instructions about the order to pass on to the shopper.
location_codestringRequiredThe location code of the store fulfilling the order.
paid_with_ebtbooleanOptionalIndicator if the order contains an EBT payment. Defaults to false.
localestringOptionalThe order's locale in IETF Language Tag format. Example: en-US.
applied_expressbooleanOptionalDeprecated. Use `applied_instacartplus` instead. Indicates whether the retailer applied Instacart+ membership benefits to the order. Defaults to false.
applied_instacartplusbooleanOptionalIndicates whether the retailer applied Instacart+ membership benefits to the order. Defaults to false.
userOrderUserOptionalAny additional attributes for the user, these take precedence over values set during user create.
itemsArray(OrderItem)RequiredThe items for the order.

OrderUser Object​

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

OrderItem Object​

FieldTypeRequiredDescription
line_numstringRequiredThe item's line number in the order.
countintegerOptionalThe count of the item. Must be a non-negative integer.
weightnumberOptionalFor 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_instructionsstringOptionalAny special instructions about the item selection.
replacement_policystringOptionalOne of "no_replacements", "users_choice" (default if replacement_items specified), or "shoppers_choice" (default otherwise).
replacement_itemsArray(Replacement_items)OptionalA 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.
itemItemRequiredThe item's code.

Replacement_items Object​

One of the following:

FieldTypeRequiredDescription
upcstringRequiredThe item's universal product code (upc).

or

FieldTypeRequiredDescription
rrcstringRequiredThe item's retailer reference code (rrc).

Item Object​

One of the following:

FieldTypeRequiredDescription
upcstringRequiredThe item's universal product code (upc).

or

FieldTypeRequiredDescription
rrcstringRequiredThe item's retailer reference code (rrc).

Request examples​

curl --request POST \
  --url 'https://connect.instacart.com/v2/fulfillment/users/{user_id}/orders/pickup' \
  --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",
  "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
  },
  "items": [
    {
      "line_num": "string",
      "count": 1,
      "weight": 1,
      "special_instructions": "string",
      "replacement_policy": "no_replacements",
      "replacement_items": [
        {
          "upc": "string"
        }
      ],
      "item": {
        "upc": "string"
      }
    }
  ]
}'

Response​

FieldTypeRequiredDescription
idstringRequiredThe ID of the order.
statusstringRequiredThe current order status.
order_urlstringOptionalLink to view the order.
created_atstringOptionalThe time of order creation in ISO 8601 format.
cancellation_reasonstringOptionalThe reason the order was canceled.
localestringOptionalThe order's locale in POSIX format. Example: en_US.
is_expressbooleanOptionalDeprecated. Use `is_instacartplus` instead. Indicates whether the order received Instacart+ membership benefits. Defaults to false.
is_instacartplusbooleanOptionalIndicates whether the order received Instacart+ membership benefits. Defaults to false.
fulfillment_detailsOrderFulfillmentDetailsOptionalThe order delivery details.
warningsArray(Error)OptionalAny warnings associated with this request.
itemsArray(OrderItem)OptionalThe items in the order.

OrderFulfillmentDetails Object​

FieldTypeRequiredDescription
store_locationstringOptionalThe 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_atstringRequiredThe start time of the delivery window in ISO 8601 format.
window_ends_atstringRequiredThe end time of the delivery window in ISO 8601 format.
delivered_atstringOptionalThe time the order was delivered in ISO 8601 format.
bag_countintegerOptionalThe number of bags in the order.
handoff_window_starts_atstringOptionalThe start time of the handoff window in ISO 8601 format.
handoff_window_ends_atstringOptionalThe end time of the handoff window in ISO 8601 format.

Error Object​

FieldTypeRequiredDescription
errorErrorDetailsOptionalInformation relevant to the error.
metaMetaErrorOptionalThe error metadata.

ErrorDetails Object​

FieldTypeRequiredDescription
messagestringOptionalThe error message.
error_codeintegerOptionalThe error code.

MetaError Object​

FieldTypeRequiredDescription
itemsArray(ItemInfo)OptionalThe items that triggered the error.

ItemInfo Object​

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

OrderItem Object​

FieldTypeRequiredDescription
line_numstringRequiredThe item's line number in the order.
qtynumberOptionalThe quantity of the item.
qty_unitstringOptionalThe quantity type, either "each" or "lb".
qty_fulfillednumberOptionalThe fulfilled quantity of the item.
qty_fulfilled_unitstringOptionalThe fulfilled quantity type, either "each" or "lb".
qty_requestednumberOptionalThe initally requested quantity of the item.
qty_requested_unitstringOptionalThe initally requested quantity type, either "each" or "lb".
replacedbooleanOptionalIndicates whether the item was replaced.
scan_codestringOptionalThe scan code of the item.
replacement_policystringOptionalThe replacement policy for the item.
shopper_provided_item_namestringOptionalThe item name provided by shoppers for items that they added.
shopper_provided_item_priceMoneyOptionalThe item price provided by shoppers for items that they added.
itemItemRequiredThe item's codes.

Money Object​

FieldTypeRequiredDescription
amountnumberRequiredThe amount of a specified currency.
currencystringRequiredThe currency type in ISO 4217 format. For example: USD.

Item Object​

FieldTypeRequiredDescription
upcstringOptionalThe item's universal product code (UPC).
rrcstringOptionalThe item's retailer reference code (RRC).
requested_upcstringOptionalThe requested item's universal product code (UPC).
requested_rrcstringOptionalThe requested item's retailer reference code (RRC).
delivered_upcstringOptionalThe delivered item's universal product code (UPC).
delivered_rrcstringOptionalThe 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-32963",
    "window_starts_at": "2018-02-22T00:00:00Z",
    "window_ends_at": "2018-02-22T00:30:00Z"
  },
  "items": [
    {
      "line_num": "89",
      "qty": 12,
      "qty_unit": "each",
      "replaced": false,
      "scan_code": "00070481001200",
      "replacement_policy": "shoppers_choice",
      "item": {
        "upc": "123456789098",
        "rrc": "",
        "requested_upc": "123456789098",
        "requested_rrc": "",
        "delivered_upc": "123456789098",
        "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"}
400Invalid replacement_policy"is not included in the list"1001{"key":"items[0].replacement_policy"}
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"}
400Invalid location code"Specified store is not available for pickup."1001{"key":"location_code"}
400Invalid order params*"There were issues with your request"9999Not applicable
400Fails alcohol compliance check"Alcoholic items can not be added to this order. Please remove and retry."2001Not applicable
400Invalid zip code for alcohol"Cannot deliver alcohol to this zip code."1001{"items":[{"item_upc":"928473737373"}],"key":"zip_code"}
400Invalid items"2 items not found."2000{"upcs":["111111111111","222222222222"],"items":[{"item_upc":"111111111111"},{"item_upc":"222222222222"}]}
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"}]}
400Order id already exists"Order already in use."1003Not applicable
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"nullNot applicable
* Multiple error
Last updated on