Skip to main content

Test pickup

Test the pickup workflow from order creation through to the customer picking up the order. 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 staged
  8. Generate a batch for the runner
  9. Advance the batch to completed
  10. 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 pickup. 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": "pickup",
    "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 staged​

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, bags_check, and staged.

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 staged state.

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

Generate a batch for the runner​

After the order is staged, create a batch for the runner with the batch type runner_customer. Generally speaking, the runner is a retailer employee. They bring the order from the staging area to the customer.

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": "runner_customer",
    "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, 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 pickup 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