Skip to main content

Test delivery

Test the delivery workflow from order creation through delivery. Use the Sandbox API endpoints to simulate the actions of a shopper and the related changes in order status in the Instacart system.

For this test, we assume the simplest use case, that is, the shopper finds all items and therefore does not add, replace, or refund items. If you want to test these scenarios, see the linked how-to guides.

  1. Before you begin
  2. Create a user and an order
  3. Create a shopper
  4. Generate a batch
  5. Advance the batch to picking
  6. Test item additions and replacements
  7. Advance the batch to completed
  8. Summary

Before you begin​

For this tutorial, you need the following items:

Variables used in this tutorial​

The following variables are used in requests in this tutorial. When you see a variable, substitute a value that works in your development environment.

VariableDescription
<instacart_development_domain>The domain of your assigned Instacart development server.
<token>The generated access token.
<user_id>The ID of a fictitious customer. The user ID is used in the Generate a batch step. Technically, the user ID is not required, but because of the way that orders are stored, the response is faster if you include the user ID in the request. We will use kamalsingh1234.
<order_id>The ID of the order created by the retailer site. We will use a1b2c3.
<shopper_id>The ID for a fictitious shopper that you create. This is generated during the tutorial.
<batch_id>The ID for the batch you generate. This is generated during the tutorial.

Create a user and an order​

To create an order, use the Fulfillment API endpoints in the development environment. For help creating an order, see the steps in Implement delivery. The rest of this tutorial covers the activities described in What happens in a production environment but within your development environment.

Create a shopper​

Create a shopper for testing purposes.

curl --request POST \
  --url 'https://<instacart_development_domain>/v2/fulfillment_sandbox/shoppers' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "susanjones@example.com",
    "phone": "8005555123"
    }'

The response contains a shopper ID for this shopper.

{
  "id": 21850710
}

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 user ID in the request. Omit it if you don’t have it.

The following request uses the generated shopper ID, the order ID a1b2c3, and the user ID kamalsingh1234.

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": 21850710,
    "orders": [
        {
            "id": "a1b2c3",
            "user_id": "kamalsingh1234"
        }
      ]
   }'

The response contains the batch ID.

{
  "id": 656178546
}

Advance the batch to picking​

The batch starts in the status of acknowledged. Use the Advance batch endpoint to change the status from acknowledged to picking. The picking status means that the shopper has started shopping for the items in the order.

The following request specifies the generated batch ID in the path.

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

The response contains the batch ID and new status.

{
  "id": 656178546,
  "workflow_state": "picking"
}

Test item additions and replacements​

At this point, you can test how the shopper can modify item quantities, add items, find items, replace items, and set items to refund. For more information, see How to test item additions and How to test item updates.

Advance the batch to completed​

Use the Advance batch endpoint to update the batch status. Each time you call it, the batch status changes in the following order: verifying_replacements, checkout, receipt_sanity_check, delivering, and completed.

The following request specifies the batch ID in the path.

curl --request POST \
  --url 'https://<instacart_development_domain>/v2/fulfillment_sandbox/batches/656178546/advance' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \

The batch changes state.

{
  "id": 656178546,
  "workflow_state": "verifying_replacements"
}

Repeat the same request until the response contains the completed state.

{
  "id": 656178546,
  "workflow_state": "completed"
}

Summary​

We simulated what happens after a delivery order is created. In this flow, we assumed that the shopper found all items. To test more complex flows, see How to test item additions and How to test item updates.

Last updated on