The Shopper app and the Sandbox API

You can simulate a shopper’s behavior with the Sandbox API. For the delivery and pickup workflows, you can simulate the shopper picking items from the shelf.

The following tables show the actions that usually occur in the Instacart Shopper app and the API endpoint you can use to simulate those actions.

note

Use this page as a quick reference. To understand path parameters and view the required and optional body parameters, click through to the linked topic.

Assigned

An order is batched and is available to be assigned. The batch type is set to the fulfillment workflow: delivery, pickup, or delivery_only (last mile delivery).

Instacart Shopper app action	Sandbox API endpoint
Shopper is assigned the batch containing an order	POST /v2/fulfillment_sandbox/batches (acknowledged)

Picking

For the delivery and pickup workflows, a shopper uses the Instacart Shopper app while picking the items off the shelves.

Instacart Shopper app action	Sandbox API endpoint
Shopper starts shopping	POST /v2/fulfillment_sandbox/batches/{batch_id}/advance (acknowledged → picking)
Shopper finds an item	PUT /v2/fulfillment_sandbox/shoppers/{shopper_id}/orders/{order_id}/items/{line_num}
Shopper finds an item but not the requested quantity and updates the quantity	PUT /v2/fulfillment_sandbox/shoppers/{shopper_id}/orders/{order_id}/items/{line_num}
Shopper adds an item to the order at the request of the shopper	POST /v2/fulfillment_sandbox/shoppers/{shopper_id}/orders/{order_id}/items
Shopper replaces an item	PUT /v2/fulfillment_sandbox/shoppers/{shopper_id}/orders/{order_id}/items/{line_num}
Shopper to refund an item's entire requested quantity because the item is out of stock and a suitable replacement is not available	PUT /v2/fulfillment_sandbox/shoppers/{shopper_id}/orders/{order_id}/items/{line_num}
Shopper requests verification of item adjustments	POST /v2/fulfillment_sandbox/batches/{batch_id}/advance (picking → verifying_replacements
Shopper checks out	POST /v2/fulfillment_sandbox/batches/{batch_id}/advance (verifying_replacements → checkout)
Shopper verifies the receipt	POST /v2/fulfillment_sandbox/batches/{batch_id}/advance (checkout → receipt_sanity_check)

Delivery

The delivery-specific actions occur after the shopper checks out.

Instacart Shopper app action	Sandbox API endpoint
Shopper is in transit to the customer	POST /v2/fulfillment_sandbox/batches/{batch_id}/advance (receipt_sanity_check → delivering)
Shopper delivers the order	POST /v2/fulfillment_sandbox/batches/{batch_id}/advance (delivering → completed)

Pickup

The pickup-specific actions occur after the shopper checks out.

Instacart Shopper app action	Sandbox API endpoint
Shopper checks the bags	POST /v2/fulfillment_sandbox/batches/{batch_id}/advance (receipt_sanity_check → bags_check)
Shopper stages the order	POST /v2/fulfillment_sandbox/batches/{batch_id}/advance (bags_check → staged)

At this point, a runner_customer batch must be created for an employee to run the bags from the staging area to the customer. The Advance batch endpoint moves this batch through the remaining states.

Instacart Shopper app action	Sandbox API endpoint
Generate a batch for a runner	POST /v2/fulfillment_sandbox/batches
Customer at the store	POST /v2/fulfillment_sandbox/batches/{batch_id}/advance (brand_new → at_store)
Employee runs bags out and customer verifies bags	POST /v2/fulfillment_sandbox/batches/{batch_id}/advance (at_store → bags_verified)
Customer accepts the order	POST /v2/fulfillment_sandbox/batches/{batch_id}/advance (bags_verified → completed)

Last mile delivery

The last mile delivery actions are used with the assigned action. The picking, delivery, and pickup actions are not applicable to last mile deliveries.

Instacart Shopper app action	Sandbox API endpoint
Shopper is at the store	POST /v2/fulfillment_sandbox/batches/{batch_id}/advance (acknowledged → at_store)
Shopper verifies the bags	POST /v2/fulfillment_sandbox/batches/{batch_id}/advance (at_store → bags_verified)
Shopper is in transit to the customer	POST /v2/fulfillment_sandbox/batches/{batch_id}/advance (bags_verified → delivering)
Shopper delivers the order	POST /v2/fulfillment_sandbox/batches/{batch_id}/advance (delivering → completed)

note

Dispatch last mile delivery is a simpler implementation of last mile delivery. The actions that apply to last mile delivery also apply to dispatch last mile delivery.