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.

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.

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#

NameInRequiredDescription
user_idpathโœ…The ID of the user.

Request#

FieldTypeRequiredDescription
order_idstringโœ…Unique ID to use for this order, 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.
special_instructionsstringSpecial instructions about the order to pass on to the shopper.
location_codestringโœ…Location code returned by location api.
localestringThe order's locale in IETF Language Tag format. Example: en-US.
userUserAny additional attributes for the user, these take precedence over values set during user create.
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. Defaults to false.

Items Object#

FieldTypeRequiredDescription
line_numstringโœ…The item's line number in the order.
countintegerThe count of the item. Must be a non-negative integer.
weightnumberThe weight of the item (defaults to lbs in the US). 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.
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/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",  "locale": "string",  "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
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.
fulfillment_detailsFulfillment_detailsThe order delivery details.
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 at in ISO 8601 format.
bag_countintegerThe number of bags in the order.

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".
replacedbooleanIndicates whether the item was replaced.
scan_codestringThe scan code of the item.
replacement_policystringThe replacement policy for the item.
itemItemโœ…The item's codes.

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#

{  "id": "12345676789012345678780",  "status": "created",  "order_url": "https://example.com/example-order",  "created_at": "2018-02-22T00:00:00Z",  "cancellation_reason": "",  "locale": "en_US",  "fulfillment_details": {    "store_location": "000-314",    "window_starts_at": "2018-02-22T00:00:00Z",    "window_ends_at": "2018-02-22T00:00:00Z"  },  "items": [    {      "line_num": "1",      "qty": 47,      "qty_unit": "each",      "replaced": false,      "scan_code": "ascandoe",      "replacement_policy": "shoppers_choice",      "item": {        "upc": "123456789012",        "rrc": "",        "requested_upc": "123456789012",        "requested_rrc": "",        "delivered_upc": "123456789012",        "delivered_rrc": ""      }    }  ]}