Skip to main content

Create a last mile delivery order

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

Creates a last mile 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.

Important

When you create a last mile delivery order, be sure to specify a unique, retailer-generated order_id in the request. You’ll need to use this ID later to find and track the order in our system.

Security​

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

Parameters​

NameInTypeRequiredDescription
user_idpathstringRequiredThe ID of the user.

Request​

FieldTypeRequiredDescription
order_idstringOptionalThe 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.
localestringOptionalThe order's locale in IETF Language Tag format. Example: en-US.
start_atstringOptionalThe requested delivery window start time in ISO 8601 format.
end_atstringOptionalThe requested delivery window end time in ISO 8601 format.
service_option_hold_idintegerRequiredThe ID of the service option hold.
first_namestringRequiredThe user's first name.
last_namestringRequiredThe user's last name.
user_phonestringRequiredThe user's phone number.
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_totalnumberOptionalThe gross merchandise value (gmv) of the cart in dollar amount.
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.
with_handoff_timebooleanOptionalIndicator whether the handoff time is calculated during order creation. Defaults to false.
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.
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.
info

To define a valid start_at and end_at delivery window, the following set of conditions must all be true:

  • At least one of the start_at or the end_at is within the service option window.
  • The start_at is within 2 hours of the service option start time.
  • The end_at is within 2 hours of the service option end time.

For example, if the service option window is 14:00-16:00, then the following request windows are valid: 13:30-14:30, 14:00-15:00, 14:30-15:30, 15:00-16:00, or 15:30-16:30. The following request windows are invalid: 12:00-13:59, 13:00-17:00, 11:00-15:00, or 15:00-19:00.

Request examples​

curl --request POST \
  --url 'https://connect.instacart.com/v2/fulfillment/users/{user_id}/orders/last_mile' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "order_id": "string",
  "location_code": "string",
  "locale": "string",
  "start_at": "string",
  "end_at": "string",
  "service_option_hold_id": 1,
  "first_name": "string",
  "last_name": "string",
  "user_phone": "string",
  "initial_tip_cents": 1,
  "items_count": 1,
  "bags_count": 1,
  "items_weight": 1,
  "cart_total": 1,
  "bag_label": "string",
  "alcoholic": true,
  "leave_unattended": true,
  "special_instructions": "string",
  "customer_sms_opt_out": true,
  "with_handoff_time": true,
  "applied_express": true,
  "applied_instacartplus": 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": "2058-02-22T00:00:00Z",
  "cancellation_reason": "shopper_driven",
  "locale": "en_US",
  "is_express": true,
  "is_instacartplus": true,
  "fulfillment_details": {
    "window_starts_at": "2058-02-22T00:00:00Z",
    "window_ends_at": "2058-02-22T00:30:00Z"
  },
  "handoff_time": "2058-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"}
400Handoff time is requested but not configured"Handoff time calculation is not configured for this retailer."1001{"key":"with_handoff_time"}
400Expired ETA option hold"ETA option hold has expired."1001{"key":"service_option_hold_id"}
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
400Order id already exists"Order already in use."1003Not applicable
400Invalid start at/end at"Invalid start / end at."1001{"key":"order.start_at"}
400Invalid first name"First name is invalid"1001{"key":"first_name"}
400Request could not be processed at this time"The request could not be completed at this time, try again later."2003{"wait":"30"}
400Missing or invalid address"Required parameter missing or invalid"1001{"key":"address"}
400Invalid address"invalid_address"1001{"key":"address"}
400Location not available for delivery"Specified store is not available for delivery."1001{"key":"location_code"}
400Service option is no longer available"The delivery time you selected is no longer available - please select another time"1001{"key":"service_option_id"}
400Address contains PO box"address contains PO Box"1001{"key":"address"}
400Invalid service option hold"Hold not found"1001{"key":"service_option_hold_id"}
400Tip over maximum"Tip value is above maximum: $500.00."1002{"key":"initial_tip_cents"}
403Inactive user"User Not Active"nullNot applicable
404Order not found"Resource not found"4000Not applicable
423The target resource is locked"The target resource is locked."null{"key":"order_id"}
* Multiple error
Last updated on