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.

Soonest sameday fallback​

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.

Parameters​

None.

Request​

FieldTypeRequiredDescription
order_idstringRequired

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

location_codestringRequired

Location code of the store where the delivery driver picks up the order.

start_atstringRequired

The requested delivery window start time in ISO 8601 format.

end_atstringRequired

The requested delivery window end time in ISO 8601 format.

localestringOptional

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

first_namestringRequired

The user's first name.

last_namestringRequired

The user's last name.

user_phonestringRequired

The user's phone number.

user_idstringOptional

Unique user ID to use for this user. If not specified, a new user will be created.

initial_tip_centsintegerOptional

The pre-delivery tip in cents.

items_countintegerRequired

The number of items in the order.

bags_countintegerOptional

The number of bags in the order.

items_weightnumberRequired

The weight of the items in lbs.

cart_total_centsintegerOptional

The total value of all items for the order in cents.

bag_labelstringOptional

A user-friendly label that helps shoppers identify the order.

alcoholicbooleanOptional

Indicates whether the order contains alcohol. Defaults to false.

leave_unattendedbooleanOptional

Indicates whether the user wants the driver to leave the order unattended. Defaults to false.

special_instructionsstringOptional

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

customer_sms_opt_outbooleanOptional

Indicator whether the user has opted-out from receiving SMS communication. Defaults to false.

applied_instacartplusbooleanOptional

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

fallback_to_soonest_samedaybooleanOptional

Indicates whether the order should be fulfilled by the soonest sameday service option if the requested delivery window is not available. Defaults to true.

addressExpandedAddressRequired

The address of the user.

ExpandedAddress Object​

FieldTypeRequiredDescription
address_line_1stringRequired

The first line of the address, e.g., 123 Main St.

address_line_2stringOptional

The second line of the address, e.g., Apt 4B.

address_typestringOptional

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

postal_codestringRequired

The postal or zip code of the address.

citystringOptional

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

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",
    "city": "string"
  }
}'

Response​

FieldTypeRequiredDescription
idstringRequired

The retailer-generated order ID.

statusstringRequired

The current status of the order.

order_urlstringOptional

The URL of the Instacart-hosted order status page. If the retailer has opted not to use this feature, this field will be null or empty.

created_atstringOptional

The time of order creation in ISO 8601 format.

cancellation_reasonstringOptional

The reason the order was canceled. Only present in canceled orders. One of the following:

  • customer_driven: The customer triggered the cancellation

  • instacart_driven: Instacart triggered the cancellation

  • retailer_driven: The retailer triggered the cancellation

  • shopper_driven: The shopper triggered the cancellation

  • unbatchable: The Instacart batch system triggered the cancellation

  • other: The cancellation was triggered for another reason not listed above.

localestringOptional

Indicates how the order is localized.

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's fulfillment details.

OrderFulfillmentDetails Object​

FieldTypeRequiredDescription
store_locationstringOptional

The location code of the store where the order was fulfilled. This field's value is often the same as the location_code included in the create order request. However, orders can be fulfilled from a store that's different from the one specified by location_code.

window_starts_atstringRequired

The start of the fulfillment window in ISO 8601 format.

window_ends_atstringRequired

The end of the fulfillment window in ISO 8601 format.

delivered_atstringOptional

The time the order was delivered to the customer in ISO 8601 format. Only present for completed deliveries.

bag_countintegerOptional

The number of bags in the order, as reported by the shopper.

handoff_window_starts_atstringOptional

The start of the store-associate-to-Instacart-shopper handoff window in ISO 8601 format. This field is only populated for last mile delivery (i.e., delivery only) orders.

handoff_window_ends_atstringOptional

The end of the store-associate-to-Instacart-shopper handoff window in ISO 8601 format. This field is only populated for last mile delivery (i.e., delivery only) orders.

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"}
400User with invalid phone number"Required parameter missing or invalid"1001{"key":"user_phone"}
400Invalid last name"Required parameter missing or invalid"1001{"key":"last_name"}
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"}
400Invalid availability window parameters"ends_at must be on the hour"1001{"key":"order.end_at"}
400Delivery window validation failed from availability service"window's length must be greater than 0"1001{"key":"order.end_at"}
400Invalid address ID"invalid_address_id"1001{"key":"invalid_parameters"}
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}
400Service option is no longer available"Service option is no longer available"1001{"key":"service_option_id"}
400Requested delivery window not available at this store"Requested delivery window is not available at this store - please select another time."1001Not applicable
400No delivery windows currently available"No delivery windows are currently available - please try again later or select a different store."1001Not applicable
400Alcohol delivery not enabled for this store"Alcohol delivery not enabled for this store."1001Not applicable
400Store is currently closed for delivery"This store is currently closed for delivery."1001Not applicable
400Invalid delivery window format"Delivery windows must start and end on the hour (e.g., 3:00pm-5:00pm). Windows starting at :30 are not supported."1001Not applicable
* Multiple error
Last updated on