Skip to main content

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 actionSandbox API endpoint
Shopper is assigned the batch containing an orderPOST /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 actionSandbox API endpoint
Shopper starts shoppingPOST /v2/fulfillment_sandbox/batches/{batch_id}/advance (acknowledged picking)
Shopper finds an itemPUT /v2/fulfillment_sandbox/shoppers/{shopper_id}/orders/{order_id}/items/{line_num}
Shopper finds an item but not the requested quantity and updates the quantityPUT /v2/fulfillment_sandbox/shoppers/{shopper_id}/orders/{order_id}/items/{line_num}
Shopper adds an item to the order at the request of the shopperPOST /v2/fulfillment_sandbox/shoppers/{shopper_id}/orders/{order_id}/items
Shopper replaces an itemPUT /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 availablePUT /v2/fulfillment_sandbox/shoppers/{shopper_id}/orders/{order_id}/items/{line_num}
Shopper requests verification of item adjustmentsPOST /v2/fulfillment_sandbox/batches/{batch_id}/advance (picking verifying_replacements
Shopper checks outPOST /v2/fulfillment_sandbox/batches/{batch_id}/advance (verifying_replacements checkout)
Shopper verifies the receiptPOST /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 actionSandbox API endpoint
Shopper is in transit to the customerPOST /v2/fulfillment_sandbox/batches/{batch_id}/advance (receipt_sanity_check delivering)
Shopper delivers the orderPOST /v2/fulfillment_sandbox/batches/{batch_id}/advance (delivering completed)

Pickup

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

Instacart Shopper app actionSandbox API endpoint
Shopper checks the bagsPOST /v2/fulfillment_sandbox/batches/{batch_id}/advance (receipt_sanity_check bags_check)
Shopper stages the orderPOST /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 actionSandbox API endpoint
Generate a batch for a runnerPOST /v2/fulfillment_sandbox/batches
Customer at the storePOST /v2/fulfillment_sandbox/batches/{batch_id}/advance (brand_new at_store)
Employee runs bags out and customer verifies bagsPOST /v2/fulfillment_sandbox/batches/{batch_id}/advance (at_store bags_verified)
Customer accepts the orderPOST /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 actionSandbox API endpoint
Shopper is at the storePOST /v2/fulfillment_sandbox/batches/{batch_id}/advance (acknowledged at_store)
Shopper verifies the bagsPOST /v2/fulfillment_sandbox/batches/{batch_id}/advance (at_store bags_verified)
Shopper is in transit to the customerPOST /v2/fulfillment_sandbox/batches/{batch_id}/advance (bags_verified delivering)
Shopper delivers the orderPOST /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.