Skip to main content

Create a last mile delivery order

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

Deprecated

This endpoint has been replaced by Create a last mile delivery order. The URI has changed, but the request parameters and responses remain the same. The new URI is consistent in format with the delivery and pickup workflows. This change reflects our commitment to making our API more intuitive to use when implementing multiple fulfillment workflows in your e-commerce site. The deprecated endpoint is still supported for existing implementations. For new implementations, use the revised endpoint.

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.

Security​

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

Parameters​

NameInTypeRequiredDescription
user_idpathstringRequired

The ID of the user.

Request​

FieldTypeRequiredDescription
order_idstringOptional

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.

localestringOptional

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

start_atstringOptional

The requested delivery window start time in ISO 8601 format.

end_atstringOptional

The requested delivery window end time in ISO 8601 format.

service_option_hold_idintegerRequired

The ID of the service option hold.

first_namestringRequired

The user's first name.

last_namestringRequired

The user's last name.

user_phonestringRequired

The user's phone number.

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_totalnumberOptional

The gross merchandise value (gmv) of the cart in dollar amount.

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.

with_handoff_timebooleanOptional

Indicator whether the handoff time is calculated during order creation. Defaults to false.

applied_expressbooleanOptional

Deprecated. Use applied_instacartplus instead. Indicates whether the retailer applied Instacart+ membership benefits to the order. Defaults to false.

applied_instacartplusbooleanOptional

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

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/users/{user_id}/orders' \
  --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",
    "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": "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"}
400Store does not support delivery to address"We do not currently support delivery from this store to the selected address."1001{"key":"address"}
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"}
400User with invalid phone number"Required parameter missing or invalid"1001{"key":"user_phone"}
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: $300.00."1002{"key":"initial_tip_cents"}
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}
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