Implement a pickup experience

Learn how to implement the Post-checkout API pickup experience on a retailer-designed order status page. The pickup experience starts when a pickup order transitions to the workflow state ready_for_pickup and ends when the customer picks up the order.

You can try out this tutorial in your development environment. To support your development efforts, this tutorial also includes tips to consider when you implement the workflow in a production environment.

1. Before you begin
2. Simulate an order ready for pickup
3. Get the pickup instructions
4. Create and get the vehicle information
5. Record when the customer arrives at the store
6. Summary

Before you begin

We recommend you complete the Implement order status tutorial to learn about how orders are managed before trying out the pickup experience.

For this tutorial, you need the following items:

• A pickup order. For instructions on how to create a pickup order, see Implement pickup.
• 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.
• Pickup instructions by store and by pickup category are set up in the development environment. Your Instacart Connect representative helps to set up this information when a retailer decides to use the Post-checkout API.

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.
<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 an order ready for pickup

To try out the pickup endpoints, we have to advance the order status. Before we can do that, we need to create a batch with the order and assign a shopper to the batch. Then we can simulate the shopper staging the order for pickup by advancing the batch to the staged status. When the batch is in staged, the order is set to ready_for_pickup.

Use Sandbox API to complete the following tasks:

1. Create a shopper
2. Generate a batch assigned to the shopper
3. Advance the batch to staged

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 staged

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 staged. The staged status means that the order is in the staging area at the store waiting for the customer to arrive.

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

curl --request POST \
  --url 'https://<instacart_development_domain>/v2/fulfillment_sandbox/batches/<batch_id>/advance' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>'
  --data '{
    "workflow_state": "staged"
  }'

The response contains the batch ID and the status of the batch.

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

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

Get the pickup instructions

You can have more than one set of instructions based on the pickup category, which can be one of curbside, in_store, or locker. When you call the endpoint, it checks the pickup category in the order and retrieves the instructions that match that category.

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

curl --request GET \
  --url 'https://<instacart_development_domain>/v2/post_checkout/orders/<order_id>/pickup/details' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>'

The response contains the category and the associated pickup instructions and pictures.

{
  "pickup_instructions": [
    {
      "category": "curbside",
      "instruction": "Please pull into the designated parking area for pickup and let us know that you've arrived!",
      "instruction_images": [
        {
          "url": "https://example.com/image/store.jpg",
          "value": ""
        },
        {
          "url": "https://example.com/image/sign_to_pickup_area.jpg",
          "value": "Parking spots are located on the left side of the building facing the main entrance."
        },
        {
          "url": "https://example.com/image/sign_at_pickup_parking.jpg",
          "value": "Parking spots are marked with curbside pickup signs."
        }
      ]
    }
  ]
}

If you get an error, contact your Instacart representative. It is possible that the instructions are not set up in the development environment.

Production environment

In a production environment, your site notifies the customer that the order is ready and links to the instructions.

Create and get the vehicle information

Retrieve the vehicle data associated with the customer. In your pickup view, prompt the customer to confirm or update the vehicle information. If the response is empty, prompt the customer to add their vehicle information. In this example, we add some vehicle information and then retrieve it.

Add some vehicle information. In the request, substitute your values for the variables <instacart_development_domain>, <order_id>, and <token>. Add the details in the request body.

curl --request PUT \
  --url 'https://<instacart_development_domain>/v2/post_checkout/orders/<order_id>/pickup/vehicle_info' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>'
  --data '{
    "model": "Model A",
    "vehicle_type": "sedan",
    "license_plate": "ABC123DEF",
    "color": "black"
  }'

The response contains the details you added. The id is a vehicle identifier and is different in your response.

{
  "vehicle_info": {
    "id": 5925991,
    "model": "Model A",
    "vehicle_type": "sedan",
    "license_plate": "ABC123DEF",
    "color": "black",
    "color_hex": "#3E3E3E"
  }
}

Retrieve the vehicle information to display to the customer. In the request, substitute your values for the variables <instacart_development_domain>, <token>, and <order_id>.

curl --request GET \
  --url 'https://<instacart_development_domain>/v2/post_checkout/orders/<order_id>/pickup/vehicle_info' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>'

If vehicle information exists, the response is the same as the preceding call. Otherwise, the response contains the following error. When you receive this error, prompt the customer to add the vehicle information.

```json
{
    "error": {
        "message": "Resource not found",
        "code": 4000
    },
    "meta": {}
}

Record when the customer arrives at the store

In your pickup view, you need a button or some other way for the customer to alert the store that they have arrived. When your site receives that notification, you can call the following request.

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

curl --request POST \
  --url 'https://<instacart_development_domain>/v2/post_checkout/orders/<order_id>/pickup/user_arrived'
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>'

The response verifies that the arrival was recorded successfully.

{
  "success": true
}

A runner batch is created automatically and an employee can be assigned to run the order to the customer.

Production environment

A production implementation must also handle the following circumstances:

• There is a delay in finding a runner. Notify the customer of the delay.
• A runner cannot be found. You might want to advise the customer to go into the store and send them the in-store pickup instructions.
• A customer reports their arrival before they get to the store. Create an operational process to return an order to the staging area. Notify the customer that the runner could not find their vehicle.
• A customer forgets to report their arrival at the store. You might want to create an operational process to monitor the pickup location for vehicles that appear to be waiting longer than usual.

Summary

In this tutorial, when the order changed to ready_for_pickup, we retrieved the information to display in the pickup view. The pickup instructions are returned based on the pickup category set in the order. The vehicle information can be created, updated, and retrieved. The customer is required to notify the store when they arrive.

You can advance the batch to closed or keep it open to use in another tutorial.

For information about the pickup workflow states, see Get an order.