Implement dispatch last mile delivery

Learn how to implement a dispatch last mile delivery workflow. You can try out this tutorial in your development environment.

tip

For the simplest integration, call the find store locations near the customer and then the create the order endpoints. You can skip the optional create a Connect user account and validate the customer's address endpoint.

This tutorial includes the optional Create a Connect user account and validate the customer's address endpoint. Use this endpoint to validate the customer address before creating the order. Pre-validation can reduce the potential for failed validations when creating the order.

note

While this tutorial shows you how to create an order, the order you create is sent to a development version of the Fulfillment engine. You don't need to worry about groceries showing up at the example address we use!

To support your development efforts, this tutorial also includes tips and best practices to consider when you implement the workflow in a production environment.

Before you begin
Find store locations near the customer
(Optional) Create a Connect user account and validate the customer's address
Fill a cart
Understand changes required in the checkout process
Create the order
How to handle errors?
What happens to an order in a production environment?
After an order is completed
Summary

Before you begin

For this tutorial, you need the following items:

A generated access token
The base URL of your assigned Instacart development server
Store locations are defined in your development environment

If store locations are not yet in your development environment, contact your Instacart representative.

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 generated access token.
`<location_code>`	The store location where the shopper picks up the order. If you need to find stores that offer delivery, use the Find stores offering dispatch last mile delivery endpoint.

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, see the API documentation.

Find store locations near the customer

Find the stores offering delivery near the specified address. In the request, substitute your values for the variables <instacart_development_domain> and <token>. If you don't have stores near this address, substitute an address that you know is close to one of your stores.

curl --request POST \
  --url 'https://<instacart_development_domain>/v2/fulfillment/lastmile/stores' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "find_by": {
    "address_line_1": "50 Beale St",
    "postal_code": "94105"
  }
}'

The response contains the array of store locations near the address.

{
  "stores": [
    {
      "name": "Test Warehouse Location 365",
      "location_code": "000-32162",
      "flags": {
        "alcohol": false,
        "pickup": true,
        "pickup_only": false,
        "long_distance_delivery": false
      }
    },
    {
      "name": "Test Warehouse Location 366",
      "location_code": "000-32170",
      "flags": {
        "alcohol": true,
        "pickup": true,
        "pickup_only": false,
        "long_distance_delivery": true
      }
    }
  ],
  "is_partial": false
}

From the response returned in your development environment, choose a store to use in this tutorial. You'll substitute the location code for the variable <location_code> in requests.

Production environment tip

When you get the list of stores, you can either choose a store location for the customer or allow the customer to select a store location where they want to shop. You can think of the selected store as the inventory store. If your retailer site passes this store location when it creates an order, the store location is also likely to be the fulfillment store.

(Optional) Create a Connect user account and validate the customer's address

note

This step is optional. You can create a dispatch last mile delivery order without creating a Connect user account. If you skip this step, you provide the customer’s address when you create the order.

Create the Connect user account and validate the customer's address. The Connect user account contains the minimum information required by Instacart to create and fulfill an order. The account must have at least a unique user ID and the customer address. The user ID is defined by you, but it must be unique for all retailer customers. For example, you might choose user names or loyalty card IDs.

Create the user account and validate the address. In the request path, we create a user ID kamalsingh1234. Substitute your values for the variables <instacart_development_domain> and <token>.

curl --request POST \
    --url 'https://<instacart_development_domain>/v2/fulfillment/users/kamalsingh1234/addresses' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
    "address_line_1": "50 Beale St",
    "postal_code": "94105",
}'

A successful JSON response has the status code 200 and the following fields:

{
  "address": {
    "address_line_1": "50 Beale St",
    "postal_code": "94105"
  },
  "user_id": "kamalsingh1234"
}

Fill a cart

To create an order, you need a cart with some items in it. Use your development environment to add an item to the cart that is available at the selected store.

Understand changes required in the checkout process

During the checkout process, your storefront needs to include prompts to collect the information necessary to create an order. For this tutorial, the Create the order request contains sample values for these items.

The information to collect before you create an order includes:

A valid delivery address.
Confirmation to leave the delivery unattended. Default is false.
Confirmation if Electronic Benefits Transfer (EBT) is used as a payment method. Default is false.
(Optional) Loyalty card number.
(Optional) Special instructions.
Tip amount.
If a cart contains alcohol, the customer's date of birth. The customer must be old enough to legally purchase alcohol in their region. Advise the customer that they must show identification with their date of birth when the order is delivered and that alcohol cannot be left unattended.
If you want to update your customer based on the callbacks your site receives about the status of the order, ask your customer to opt in to receiving SMS notifications.

Near the end of the checkout process, your storefront needs to handle the following tasks:

Display the order details for review, and enable a customer to change items or update any of the collected information.
Prompt for payment. Reserve the payment amount but wait to process the payment until after your site receives a callback to confirm that the order was delivered. Refunds might affect the total cost of the order.
Prompt the user to select a time slot.

Create the order

Send a request to create a dispatch last mile delivery order. The order requires a retailer-generated order ID, store location, desired delivery window, customer information, and item count and weight.

When you send the request to create a dispatch last mile delivery order, Instacart validates the order, including customer address, store location, and fulfillment capacity. If validations pass, Instacart creates the order.

tip

Instead of failing order creation when there isn't capacity to fulfill the order, Instacart can substitute your desired window with the soonest alternative on the same day. To enable this option, set the fallback_to_soonest_sameday flag to true.

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

curl --request POST \
 --url 'https://<instacart_development_domain>/v2/fulfillment/lastmile/orders' \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer <token>' \
 --header 'Content-Type: application/json' \
 --data '{
 "order_id": "<order_id>",
 "location_code": "<location_code>",
 "start_at": "2022-06-04T11:00:00Z",
 "end_at": "2022-06-04T12:00:00Z",
 "locale": "en-US",
 "first_name": "Kamal",
 "last_name": "Singh",
 "user_phone": "800-555-0101",
 "user_id": "string",
 "initial_tip_cents": 200,
 "items_count": 12,
 "bags_count": 3,
 "items_weight": 15,
 "cart_total_cents": 5400,
 "bag_label": "bag-xyz123456",
 "alcoholic": true,
 "leave_unattended": true,
 "special_instructions": "Ring the doorbell.",
 "customer_sms_opt_out": true,
 "applied_instacartplus": true,
 "fallback_to_soonest_sameday": true,
 "address": {
   "address_line_1": "50 Beale St",
   "postal_code": "94105"
 }
}'

The response contains details about the newly created order. Instacart sends additional order information, such as the order_url, in the brand new callback.

{
  "id": "<order_id>",
  "status": "created",
  "fulfillment_details": {
    "store_location": "1003",
    "window_starts_at": "2022-06-04T11:00:00Z",
    "window_ends_at": "2022-06-04T12:00:00Z"
  }
}

Production environment tip

It can take several seconds to receive confirmation that the order is created. For your storefront, consider what you want to show to the customer while they wait for confirmation.

When the order is successfully created in the Instacart system, your site receives the brand new callback. The brand new callback includes the full order details.

{
  "id": "xyz123456",
  "status": "brand_new",
  "order_url": "https://<instacart_development_domain>/s/dWl2N3U1d203",
  "created_at": "2021-06-22T20:57:22Z",
  "cancellation_reason": "",
  "locale": "en_US",
  "is_express": true,
  "is_instacartplus": true,
  "fulfillment_details": {
    "store_location": "<location_code>",
    "window_starts_at": "2021-06-22T20:57:21Z",
    "window_ends_at": "2021-06-23T01:57:21Z"
  },
  "is_fallback_window": false
}

How to handle errors?

When you request to create an order, Instacart validates the customer address, store location, and fulfillment capacity. If validations fail, Instacart returns client-side or server-side errors.

Client-side errors are correctable errors, such as an invalid address or missing phone number. If validations fail because of a client-side error, your site can prompt your customer to correct the information and then create the order again.

The following example shows a client error:

{
  "error": {
    "message": "Required parameter missing or invalid",
    "code": 1001
  },
  "meta": {
    "key": "address"
  }
}

Server-side errors are non-correctable errors, such as timeouts or issues on the Instacart servers. If validations fail because of a server-side error, Instacart will retry two times. If the retries fail, then Instacart cancels the order and sends the canceled callback. For more information, see Event callbacks.

Also, it’s possible that the request succeeds, but then the order creation fails later. If order creation fails, Instacart sends the Canceled callback.

For more information about client-side and server-side errors, see Error and status codes.

What happens to an order in a production environment?

As previously mentioned, an order created in a development environment is not fulfilled. To complete this tutorial, let's review what happens to orders created in a production environment.

In a production environment, a retailer employee receives the order. Based on the selected time slot, the employee shops for the order. Optionally, the retailer site can provide a way for the customer to update a dispatch last mile delivery order or cancel a dispatch last mile delivery order.

When the order is ready, the employee brings the bags to a staging area. Your retailer site calls the Stage a dispatch last mile delivery order endpoint, which updates the order status to staged. The order is batched for delivery during the selected time slot. The assigned shopper picks up and delivers the order.

info

Instacart dispatches a shopper only after the order status is set to staged. To ensure the delivery is made within the selected time slot, be sure to stage orders with enough lead time for a shopper to get to the store, pick up the order, and arrive at the customer's location.

tip

You can get the order status with the Get a dispatch last mile delivery order endpoint.

After an order is completed

After an order is delivered to your customer, you can provide a way for your customer to update their tip and give feedback on the order. For more information about updating a tip, see Update a tip. For more information about giving order feedback, see Create or update order feedback (backend) and Create or update order feedback (frontend).

Summary

In this tutorial, we created a dispatch last mile delivery order. We discussed optional endpoints and what happens in a production environment while the order is in the fulfillment process. Finally, we discussed providing a way for your customer to update their tip and give feedback on their completed order.

Before you begin​

Variables used in this tutorial​

Find store locations near the customer​

(Optional) Create a Connect user account and validate the customer's address​

Fill a cart​

Understand changes required in the checkout process​

Create the order​

How to handle errors?​

What happens to an order in a production environment?​

After an order is completed​

Summary​