Skip to main content

How to asynchronously create a last mile delivery order

Learn how to asynchronously create a last mile delivery order. Asynchronous order creation enables you to reduce API response times and quickly move your customers through the checkout process.

Beta

Asynchronous order creation of last mile delivery orders is in beta release. To enable this feature, contact your Instacart representative.

When you send a request to asynchronously create a last mile delivery order, Instacart validates the order. If the validations pass, Instacart creates the order. If the validations fail, 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.

If Instacart successfully creates the order, the response contains some details about the order, such as the order ID, order status, store location, and delivery window. Instacart sends additional order details, such as the order URL and Instacart+ membership status, in the Brand New callback. In contrast, when you create a last mile delivery order without asynchronous order creation enabled, Instacart takes some time to validate and then create the order, but the response contains all order details.

When you request to asynchronously create a last mile delivery order, it’s possible that the request succeeds, but then the order creation fails later. If order creation fails, Instacart sends the Canceled callback.

Prerequisite​

You need the follow things:

  • The asynchronous order creation configuration is enabled in your retailer configuration.
  • The Last mile delivery workflow is implemented on your site.
  • The Brand New callback is enabled for your last mile delivery workflow.

For help with prerequisites, contact your Instacart Connect representative.

Create the asynchronous last mile delivery order​

The following example from the Implement last mile delivery tutorial has been modified to show the response when you request to asynchronously create a last mile delivery order. The example also shows the Brand New callback that Instacart sends.

  1. The retailer sends a request to create a last mile delivery order. The following example shows a sample request:

    curl --request POST \
      --url 'https://<instacart_development_domain>/v2/fulfillment/users/kamalsingh1234/orders/last_mile' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <token>' \
      --header 'Content-Type: application/json' \
      --data '{
        "order_id": "xyz123456",
        "service_option_hold_id": "<service_option_hold_id>",
        "location_code": "<location_code>",
        "locale": "en-US",
        "first_name": "Kamal",
        "last_name": "Singh",
        "user_phone": "800-555-0101",
        "initial_tip_cents": 200,
        "items_count": 12,
      "bags_count": 3,
        "items_weight": 15,
      "cart_total": 5400,
      "alcoholic": false,
      "leave_unattended": true,
      "special_instructions": "Ring the doorbell.",
      "address": {
          "address_line_1": "50 Beale St",
          "postal_code": "94105"
        }
    }'

  2. Instacart executes validations for the address, store location, and fulfillment capacity.

  3. If the validations pass, Instacart creates the order. The response contains some details about the order. Instacart sends additional order information, such as the order_url, in the Brand New callback.

    {
      "id": "xyz123456",
      "status": "created",
      "fulfillment_details": {
        "store_location": "1003",
        "window_starts_at": "2022-06-04T11:00:00Z",
        "window_ends_at": "2022-06-04T12:00:00Z"
      }
    }

  4. Your site receives the Brand New callback, which contains all order details.

    {
      "id": "xyz123456",
      "status": "brand_new",
      "order_url": "https://<instacart_development_domain>/s/dWl2N3U1d203",
      "created_at": "2021-06-22T20:57:22Z",
      "cancellation_reason": "",
      "locale": "en_US",
      "is_express": true,
      "is_instacartplus": true,
      "fulfillment_details": {
        "store_location": "<location_code>",
        "window_starts_at": "2021-06-22T20:57:21Z",
        "window_ends_at": "2021-06-23T01:57:21Z"
      },
      "is_fallback_window": false
    }

How to handle errors?​

When you request to create an order, Instacart validates the customer address, store location, and fulfillment capacity. If validations fail, Instacart returns client-side or server-side errors.

Client-side errors are correctable errors, such as an invalid address or missing phone number. If validations fail because of a client-side error, your site can prompt your customer to correct the information and then create the order again.

The following example shows a client error:

{
  "error": {
    "message": "Required parameter missing or invalid",
    "code": 1001
  },
  "meta": {
    "key": "address"
  }
}

Server-side errors are non-correctable errors, such as timeouts or issues on the Instacart servers. If validations fail because of a server-side error, Instacart will retry two times. If the retries fail, then Instacart cancels the order and sends the canceled callback. For more information, see Event callbacks.

Also, it’s possible that the request succeeds, but then the order creation fails later. If order creation fails, Instacart sends the Canceled callback.

For more information about client-side and server-side errors, see Error and status codes.

Last updated on