Implement the item replacement flow

Learn how to capture the customer's response to replacement items. For example, on your order status page, you might have a Review replacements page where a customer can review replacement items and approve or reject them.

You can try out this tutorial in your development environment.

1. Before you begin
2. Simulate shopping
3. Suggest a replacement item
4. Display replacement items
5. Capture the customer response
6. Summary

Before you begin

We recommend that you complete the Implement order status tutorial to learn about how orders are managed before trying this tutorial.

• An order. For instructions on how to create a delivery order, see Implement delivery.
• The user access token that you generated for the customer's order status page. This is different than the client credentials access token you used to create the order.
• The base URL of your assigned Instacart development server.

Variables used in this tutorial

The following variables are used in requests in this tutorial. When you see a variable, substitute them with values that work in your development environment.

Variable	Description
<instacart_development_domain>	The domain of your assigned Instacart development server.
<token>	The user access token that was generated for this order using the encoded user ID.
<order_id>	The order ID from the order that you created before you started this tutorial.
<order_item_id>	The item ID that has a replacement item suggested.
<shopper_id>	The ID for a fictitious shopper that you create. This is generated during the tutorial.
<batch_id>	The ID for a batch that contains the order. This is generated during the tutorial.

The responses in this tutorial show sample values in place of the variables. The responses that are returned in your environment should have a similar format to the example responses. If you are interested in other possible responses including errors, see the API documentation.

Simulate shopping

In a production environment, a shopper uses the Instacart Shopper app while picking items. For this tutorial, we'll start by simulating a shopper shopping.

Use Sandbox API to complete the following tasks:

• Create a shopper
• Generate a batch assigned to the shopper
• Advance the batch to picking

Create a shopper

In the request, substitute your values for the variables <instacart_development_domain>, <token>, <shopper_email>, <shopper_phone>, and <shopper_password>.

curl --request POST \
  --url 'https://<instacart_development_domain>/v2/fulfillment_sandbox/shoppers' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>'
  --data '{
    "email": "<shopper_email>",
    "phone": "<shopper_phone>",
    "password": "<shopper_password>"
  }'

The response contains the generated shopper ID.

{
  "id": 23728249
}

For details about this Sandbox API endpoint, see Create a shopper.

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

In the following request, substitute your values for the variables <instacart_development_domain> and <token>. In the request body, specify the generated <shopper_id>, the <order_id>, and optionally the <external_user_id>.

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": <shopper_id>,
    "orders": [
        {
            "id": "<order_id>",
            "user_id": "<external_user_id>"
        }
      ]
   }'

The response contains the batch ID.

{
  "id": 656178546
}

For details about this Sandbox API endpoint, see Generate a batch.

Advance the batch to picking

With the batch assigned to a shopper, you are now able to set the status of the batch. The batch starts in the status of acknowledged. We'll change the status from acknowledged to picking. The picking status means that the shopper has started shopping for the items in the order.

In the request, substitute your values for the variables <instacart_development_domain>, <batch_id>, and <token>. Set the workflow state to picking.

curl --request POST \
  --url 'https://<instacart_development_domain>/v2/fulfillment_sandbox/batches/<batch_id>/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 the status of the batch.

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

For details about this Sandbox API endpoint, see Advance batch.

Suggest a replacement item

Now we need an item that has a replacement item associated with it. In a production environment, when a shopper selects a replacement item for an order item, the order item status changes to replaced. We can simulate this scenario by using the Sandbox API to update an order item to the replaced status.

In the following request, substitute your values for the variables <instacart_development_domain>, <shopper_id>, order_id>, <order_item_id>, and <token>. In the request body, specify an item that is in your test store catalog as the replacement item and set the status to replaced.

curl --request POST \
 --url 'https://<instacart_development_domain>/v2/fulfillment_sandbox/shoppers/<shopper_id>/orders/<order_id>/items/<order_item_id>' \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer <token>' \
 --header 'Content-Type: application/json' \
 --data '{
    "delivered_count": 1,
    "replacement_item": {
      "rrc": "almonds"
    },
    "scans": [
      {
        "scanned_string": "1234567890123",
        "scanned_string_type": "upca"
      }
    ],
    "status": "replaced"
  }'

The response confirms that the item is updated.

{
  "success": true
}

For details about this endpoint, see Update an item as a shopper.

Display replacement items

In a production environment, poll the Get order items endpoint as described in the Implement order status tutorial. When the item changes status to replaced, display the order item with its replacement item on the page where you want customers to review the replaced items. Include a way for the customer to approve or reject the replacement. For example, you might add buttons beside each replacement.

Capture the customer response

When a customer selects approve or replace, update the item. For this tutorial, set one of the replacement statuses.

In the following request examples, substitute your values for the variables <instacart_development_domain>, <order_id>, <order_item_id>, and <token>.

Approves replacement

If the customer approves the replacement, make the following request and specify the status as APPROVED in the request body.

curl --request PUT \
  --url 'https://<instacart_development_domain>/v2/post_checkout/orders/<order_id>/items/<order_item_id>/replacement' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>'
  --data '{
    "status": "APPROVED"
  }'

A 200 response with an empty JSON body means the update was successful and the item is updated. The next time the order items are retrieved, this item has the field replacement_status set to APPROVED.

Rejects replacement

If the customer rejects the replacement, make the following request and specify the status as REJECTED in the request body.

curl --request PUT \
  --url 'https://<instacart_development_domain>/v2/post_checkout/orders/<order_id>/items/<order_item_id>/replacement' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
    "status": "REJECTED"
  }'

A 200 response with an empty JSON body means the update was successful and the item is updated. The next time the order items are retrieved, this item has the field replacement_status set to REJECTED.

note

All items with the replacement_status set to REJECTED are automatically refunded.

Summary

In this tutorial, we walked through how to use the Sandbox API to create a replacement. We learned that items with the status replaced can be displayed on a retailer-implemented Review replacements page. Finally, we captured a customer's decision to approve or reject a replacement item.