Skip to main content

Test last mile delivery

Test the last mile 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.

  1. Before you begin
  2. Create a user and an order
  3. Create a shopper
  4. Generate a batch
  5. Advance the batch to completed
  6. 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 last mile 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",
"password": "cakeMIX1!"
}'

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

The response contains the batch ID.

{
"id": 656178546
}

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: at_store, bags_verified, 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": "at_store"
}

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

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

Summary

We simulated what happens after a last mile delivery order is created.