Implement the order status flow

Learn how to get order details to display on a retailer-designed order status page. Use a polling strategy to retrieve the order workflow state and item status as shopping progresses.

You can try out this tutorial in your development environment. To support your development efforts, this tutorial also includes tips to consider when you implement the workflow in a production environment.

1. Before you begin
2. Get the order
3. Get the order items
4. Get the customer address and order handling details
5. Get the shopper location
6. Summary

Before you begin

For this tutorial, you need the following items:

• An order. For instructions on how to create a delivery order, see Implement delivery.
• The user access token that you generated for the customer's order status page. This is different than the client credentials access token you used to create the order.
• The base URL of your assigned Instacart development server.

Variables used in this tutorial

The following variables are used in requests in this tutorial. When you see a variable, substitute them with values that work in your development environment.

Variable	Description
<instacart_development_domain>	The domain of your assigned Instacart development server.
<token>	The access token that was generated for this order using the encoded user ID.
<order_id>	The order ID from the order that you created before you started this tutorial.
<shopper_id>	The ID for a fictitious shopper that you create. This is generated during the tutorial.
<batch_id>	The ID for a batch that contains the order. This is generated during the tutorial.

The responses in this tutorial show sample values in place of the variables. The responses that are returned in your environment should have a similar format to the example responses. If you are interested in other possible responses including errors, see the API documentation.

Get the order

Before picking begins, get the order by order ID. The order details include the type of order, when the order was created, and the selected fulfillment time slot. Display this data in the order status page so customers can verify these details.

The response also contains the order workflow state, which you use to transition the order status page to the appropriate set of UX elements. New orders start in the workflow state brand_new, but the other workflow states depend on the type of order: delivery, pickup, and last mile delivery. For the list of workflow states for each type of order, see Get order.

Start polling this endpoint when a shopper is assigned. Send the request at whatever frequency you prefer. Whenever the order changes state, update the order status page. Stop polling when the order state is delivered.

In the request, substitute your values for the variables <instacart_development_domain>, <order_id>, and <token>.

curl --request GET \
  --url 'https://<instacart_development_domain>/v2/post_checkout/orders/<order_id>' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>'

The response contains the order details, including the workflow state.

{
  "id": "a3e30880-10b5-445e-a525-7dae3e2e15b3",
  "creation_date": "2022-01-13T18:28:07Z",
  "workflow_state": "brand_new",
  "fulfillment_type": "delivery",
  "fulfillment_details": {
    "window_starts_at": "2022-01-13T18:28:06Z",
    "window_ends_at": "2022-01-13T20:28:06Z"
  }
}

Get the order items

For delivery and pickup orders, you can get the items in the order from Instacart Connect. For last mile delivery orders, retailers don't send the list of items to Instacart.

note

If you plan to use the order status page with last mile delivery orders, you need to use a retailer-side process to obtain the list of items instead of this process.

Before picking begins, display the items in the order so that customers can verify the shopping list is accurate. The items details include the item name, image, unit of measure, and quantity.

The response also contains the status of each item at the time the request was made. All items start in the status not_picked. When shopper finds an item, the status is found. For the list of item statuses, see Get order items.

Start polling this endpoint when the shopper starts picking items. Display the items in separate lists based on the status, such as Found, Replaced, Refunded, and Still shopping. Send this request at whatever frequency you prefer and update the lists. Stop polling this endpoint when the shopper is ready to checkout and the order workflow state transitions to checkout.

In the request, substitute your values for the variables <instacart_development_domain>, <order_id>, and <token>.

curl --request GET \
  --url 'https://<instacart_development_domain>/v2/post_checkout/orders/<order_id>/items' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>'

The response contains the list of items. This example has two items, but your response contains however many items were in the order you created for testing purposes. Use the value in the status field to sort the items into the lists.

{
  "line_items": [
    {
      "id": "1234-5678-9012-abcd",
      "replacement_status": "SUBSTITUTION_STATUS_UNSPECIFIED",
      "status": "not_picked",
      "item": {
        "name": "Organic Bananas",
        "image_url": "https://example.com/product-image/file/bananas.png",
        "quantity": "10.0",
        "cost_unit": "EACH"
      }
    },
    {
      "id": "2345-6789-0123-efgh",
      "replacement_status": "SUBSTITUTION_STATUS_UNSPECIFIED",
      "status": "found",
      "item": {
        "name": "Cantaloupe",
        "image_url": "https://example.com/product-image/file/cantaloupe.png",
        "quantity": "1.0",
        "cost_unit": "EACH"
      }
    }
  ]
}

Get the customer address and order handling details

When an order is created, create the order status page and display the customer's address and order handling preferences. Preferences includes notes, instructions, whether the order contains alcohol, and whether to leave the order unattended. You don't need to poll this endpoint because this data doesn't change after an order is created.

In the request, substitute your values for the variables <instacart_development_domain> and <token>.

curl --request GET \
  --url 'https://<instacart_development_domain>/v2/post_checkout/orders/<order_id>/handling' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>'

The example response contains the customer's address and coordinates. There are no instructions. The order doesn't contain alcohol and the order cannot be left unattended.

{
  "address": {
    "address_line_1": "501 Belt Line Rd",
    "locality": "Collinsville",
    "administrative_area": "IL",
    "postal_code": "62234",
    "country_code": "US"
  },
  "coordinates": {
    "latitude": 38.6924568,
    "longitude": -89.9785745
  },
  "dropoff_location": "",
  "notes": "",
  "instructions": "",
  "leave_unattended": false,
  "alcoholic": false,
  "certified_delivery": true
}

Get the shopper location

While the order is in the workflow state delivering, you can get the shopper's location to display on a mapping component.

Start polling this endpoint when the workflow state transitions to delivering. Stop polling when the workflow state transitions to delivered.

curl --request GET \
  --url 'https://<instacart_development_domain>/v2/post_checkout/orders/<order_id>/location'
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>'

The response contains the shopper's location in geographic coordinates.

{
  "coordinates": {
    "latitude": 1,
    "longitude": 1
  }
}

Testing

To test this implementation, use the Sandbox API to create and assign a shopper and advance the order status.

Create a shopper

In the request, substitute your values for the variables <instacart_development_domain>, <token>, <shopper_email>, <shopper_phone>, and <shopper_password>.

curl --request POST \
  --url 'https://<instacart_development_domain>/v2/fulfillment_sandbox/shoppers' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>'
  --data '{
    "email": "<shopper_email>",
    "phone": "<shopper_phone>",
    "password": "<shopper_password>"
  }'

The response contains the generated shopper ID.

{
  "id": 23728249
}

For details about this Sandbox API endpoint, see Create a shopper.

Generate a batch

An order must be batched before it can be shopped. Create a batch that contains the order and assign it to the shopper you just created.

note

The user ID is not required, but because of the way that orders are stored, the response is faster if you include the <external_user_id> in the request. Omit it if you don’t have it.

In the following request, substitute your values for the variables <instacart_development_domain> and <token>. In the request body, specify the generated <shopper_id>, the <order_id>, and optionally the <external_user_id>.

curl --request POST \
  --url 'https://<instacart_development_domain>/v2/fulfillment_sandbox/batches' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "batch_type": "delivery",
    "shopper_id": <shopper_id>,
    "orders": [
        {
            "id": "<order_id>",
            "user_id": "<external_user_id>"
        }
      ]
   }'

The response contains the batch ID.

{
  "id": 656178546
}

For details about this Sandbox API endpoint, see Generate a batch.

Advance the batch

With the batch assigned to a shopper, you are now able to cycle the batch through the workflow states. Ensure that your polling starts, continues, and stops at the appropriate state transitions.

The batch starts in the status of acknowledged. Each time you call the following endpoint, the batch cycles to the next status in the workflow. For information about the statuses and workflows, see Shopper app and Sandbox API

In the request, substitute your values for the variables <instacart_development_domain>, <batch_id>, and <token>.

curl --request POST \
  --url 'https://<instacart_development_domain>/v2/fulfillment_sandbox/batches/<batch_id>/advance' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>'
  --data '{
    "workflow_state": "staged"
  }'

The response contains the batch ID and the status of the batch.

{
  "id": 791485965,
  "workflow_state": "staged"
}

For details about this Sandbox API endpoint, see Advance a batch.

Summary

In this tutorial, we retrieved the data for a new order. For the endpoints that include state or status updates, we identified when to start and stop polling the endpoints.