Skip to main content

Create a dispatch last mile delivery order

POST /v2/fulfillment/lastmile/orders

Sends a request to create a dispatch last mile delivery order with the desired delivery window.

When you send a request to create an order, Instacart validates the order. If the request passes validations, Instacart creates the order. If the request fails validations, Instacart returns errors. For example, the request fails if the customer provides an invalid address. Your site can prompt your customers to correct the information and then try to create the order again. If Instacart cannot fulfill the order, Instacart cancels the order and sends the canceled callback. For more information, see How to handle errors.

To define a desired delivery window, use the start_at and end_at fields. The window must be a minimum of one hour long and must start and end on the hour.

note

For carts with alcohol, it is the retailer's responsibility to ensure that alcohol type, alcohol quantity, and the age of the customer are in compliance with regional laws. For alcohol delivery, retailers must also ensure that the city and county of the store and customer match. For more information, see Alcohol compliance.

You can see which delivery window was used for the order in the fulfillment_details section of the response.

tip

Instead of failing order creation when there isn't capacity to fulfill the order, Instacart can substitute your desired window with the soonest alternative on the same day. To enable, set the fallback_to_soonest_sameday flag to true.

Security

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

Request

FieldTypeRequiredDescription
order_idstringRequiredThe unique retailer-generated order ID to use for the order. The ID can be used later for lookup.
location_codestringRequiredLocation code of the store where the delivery driver picks up the order.
start_atstringRequiredThe requested delivery window start time in ISO 8601 format.
end_atstringRequiredThe requested delivery window end time in ISO 8601 format.
localestringOptionalThe order's locale in IETF Language Tag format. Example: en-US.
first_namestringRequiredThe user's first name.
last_namestringRequiredThe user's last name.
user_phonestringRequiredThe user's phone number.
user_idstringOptionalUnique user ID to use for this user. If not specified, a new user will be created.
initial_tip_centsintegerOptionalThe pre-delivery tip in cents.
items_countintegerRequiredThe number of items in the order.
bags_countintegerOptionalThe number of bags in the order.
items_weightnumberRequiredThe weight of the items in lbs.
cart_total_centsintegerOptionalThe total value of all items for the order in cents.
bag_labelstringOptionalA user-friendly label that helps shoppers identify the order.
alcoholicbooleanOptionalIndicates whether the order contains alcohol. Defaults to false.
leave_unattendedbooleanOptionalIndicates whether the user wants the driver to leave the order unattended. Defaults to false.
special_instructionsstringOptionalSpecial instructions about the order to pass on to the shopper.
customer_sms_opt_outbooleanOptionalIndicator whether the user has opted-out from receiving SMS communication. Defaults to false.
applied_instacartplusbooleanOptionalIndicates whether the retailer applied Instacart+ membership benefits to the order. Defaults to false.
fallback_to_soonest_samedaybooleanOptionalIndicates whether the order should be fulfilled by the soonest sameday service option if the requested delivery window is not available. Defaults to true.
addressAddressRequiredThe address of the user.

Address Object

FieldTypeRequiredDescription
address_line_1stringRequiredThe first address line.
address_line_2stringOptionalThe second address line.
address_typestringOptionalThe type of address, e.g., "residential".
postal_codestringRequiredThe postal/zip code of the address.

Request examples

curl --request POST \
--url https://connect.instacart.com/v2/fulfillment/lastmile/orders \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"order_id": "string",
"location_code": "string",
"start_at": "string",
"end_at": "string",
"locale": "string",
"first_name": "string",
"last_name": "string",
"user_phone": "string",
"user_id": "string",
"initial_tip_cents": 1,
"items_count": 1,
"bags_count": 1,
"items_weight": 1,
"cart_total_cents": 1,
"bag_label": "string",
"alcoholic": true,
"leave_unattended": true,
"special_instructions": "string",
"customer_sms_opt_out": true,
"applied_instacartplus": true,
"fallback_to_soonest_sameday": true,
"address": {
"address_line_1": "string",
"address_line_2": "string",
"address_type": "string",
"postal_code": "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.

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.

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": {
"window_starts_at": "2018-02-22T00:00:00Z",
"window_ends_at": "2018-02-22T00:30:00Z"
},
"is_fallback_window": false
}

4XX Errors

Error responses return either a single error or multiple errors.

HTTP CodeCauseError MessageError CodeError Meta
400Invalid postal code"not found"1001{"key":"postal_code"}
400Unsupported postal code"not supported"1001{"key":"postal_code"}
400User without phone number"can't be blank"1001{"key":"user.phone_number"}
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
400Time window is not available"Specified delivery time is not available - please select another time."1001Not applicable
400Time window is invalid"Invalid start / end at."1001Not applicable
400Address not serviceable"We do not currently support delivery from this store to the selected address."1001{"key":"address"}
* Multiple error