Schedule pickup

POST /v2/post_checkout/orders/{order_id}/pickup/schedule_pickup

To help reduce the customer’s wait time at the store, you can use this operation to schedule a curbside pickup.

Your request must provide the customer’s estimated time of arrival (ETA). Instacart uses that timestamp to create a record of the scheduled pickup. No more than one minute after the ETA you provide has elapsed, an automated job notifies a store associate via the Shopper App that the customer is expected to have arrived.

You can use record customer arrival to complement this operation. Recording an arrival immediately notifies the store, while scheduling a pickup does so asynchronously. This lets you build your app so that customers can notify store associates of their arrival, even if that time is before a scheduled pickup.

As long as all the preconditions are met, you can also use this operation to update a scheduled pickup. To do this, pass the same order_id and a new schedule_pickup_eta.

Preconditions

The post-checkout order must have a fulfillment_type of pickup, a pickup_category of curbside, and a workflow_state of ready_for_pickup (which is equivalent to a status of staged in the fulfillment order).

When to use

Typically, you implement this endpoint when you want your customers to be able to use your order status page to indicate that they’re on the way to the store. You can then capture the customer's location, determine their estimated travel time to the store, compute an ETA, and pass that timestamp to Instacart.

Limitations

This operation is not supported for orders that have a pickup delegate. If the order has a delegate and you schedule a pickup, the Shopper App provides the customer's name and phone number to the store associate. As a result, when a delegate is assigned to an order, you're limited to recording their arrival.

Security

Name	In	Description
Authorization	header	The Authorization header with the bearer token acquired during authentication.

Parameters

Name	In	Type	Required	Description
order_id	path	string		The order ID, which maps to id in the get post-checkout order response.

Request

Field	Type	Required	Description
schedule_pickup_eta	string		The customer’s estimated time of arrival at the store. Must be a UTC timestamp in ISO-8601 format. The provided value can’t be in the past or more than twelve hours in the future, as measured from the time of this request.

Request examples

cURL

curl --request POST \
  --url 'https://connect.instacart.com/v2/post_checkout/orders/{order_id}/pickup/schedule_pickup' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "schedule_pickup_eta": "string"
}'

Java

HttpResponse<String> response = Unirest.post("https://connect.instacart.com/v2/post_checkout/orders/{order_id}/pickup/schedule_pickup")
  .header("Accept", "application/json")
  .header("Content-Type", "application/json")
  .header("Authorization", "Bearer <token>")
  .body("{\n  \"schedule_pickup_eta\": \"string\"\n}")
  .asString();

Python

import http.client

conn = http.client.HTTPSConnection("connect.instacart.com")

payload = "{\n  \"schedule_pickup_eta\": \"string\"\n}"

headers = {
    'Accept': "application/json",
    'Content-Type': "application/json",
    'Authorization': "Bearer <token>"
}

conn.request("POST", "/v2/post_checkout/orders/{order_id}/pickup/schedule_pickup", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Go

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://connect.instacart.com/v2/post_checkout/orders/{order_id}/pickup/schedule_pickup"

	payload := strings.NewReader("{\n  \"schedule_pickup_eta\": \"string\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "application/json")
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Response

Field	Type	Required	Description
message	string		Indicates that pickup has been successfully scheduled. The message is always Scheduled pickup successfully created for order, regardless of whether the scheduled pickup record was created or updated.
order_id	string		The order ID, which maps to id in the get post-checkout order response.

Response examples

200 Success

200 Pickup scheduled successfully

{
  "message": "Scheduled pickup successfully created for order",
  "order_id": "123_456"
}

4XX Errors

Error responses return either a single error or multiple errors.

HTTP Code	Cause	Error Message	Error Code	Error Meta
400	Order is not a pickup order	"Pickup unavailable for non-pickup orders"	4001	Not applicable
400	Order is not a curbside pickup	"Cannot record user arrival for non-curbside orders"	4001	Not applicable
400	Order is not in staged state	"Scheduled pickup not available for non-staged orders"	4010	Not applicable
400	ETA format is invalid	"ETA format is invalid, expected ISO8601 UTC timestamp"	4012	Not applicable
400	ETA is in the past	"ETA must not be in the past (got: 2021-12-15T16:19:00Z)"	4013	Not applicable
400	ETA is more than 12 hours in the future	"ETA must be within 12 hours from now (got: 2021-12-16T06:19:00Z)"	4014	Not applicable
403	API not enabled via feature flag	"API not enabled"	null	Not applicable
404	No pickup status found for order	"No pickup status found for order"	4000	Not applicable
404	Order not found	"Resource not found"	4000	Not applicable