Skip to main content

Event callbacks

Instacart Connect can notify you of order status change events through callbacks. To get notifications about specific events, you need to set up one or more webhooks and ensure each can handle errors and retries.

tip

Work with your Instacart Connect representative to decide which events make sense for your fulfillment workflows.

For some orders, your webhooks might receive the same event notification multiple times. This can occur when an order reverts to a previous status, causing certain steps in the workflow to repeat.

Event callbacks can contain a variety of data structures. However, the configuration of the order and your account determines the fields in each event's payload.

Callbacks by fulfillment workflow type

The following table lists the available callbacks and identifies which fulfillment workflows can use them.

CallbacksDeliveryPickupLast mile delivery
Brand new
Acknowledged
Picking
Order item replacement
Order item refund
Checkout
Delivering
Order location
Late delivery
Customer missing
Staged *
Customer acknowledged
Pickup runner started
Unable to find customer
Runner not found
Pickup Geofence reached
Late pickup
Delivered
Rescheduled
Canceled
Tip adjustment
At store
Acknowledged for delivery
Bags verified
Arrival at customer
At store ETA
Rating updated
Rating reminder

* This callback is sent only when the shopper who picks the order is different from the shopper who delivers the order.

note

Dispatch last mile delivery workflows can use the same callbacks as last mile delivery workflows.

Callback descriptions

For each available event callback, this section provides a brief description and an example payload. However, the fields included in the actual payloads sent to your webhooks are determined by the configuration of the order and your account.

Brand new

This event occurs when an order is successfully created in Instacart's system.

In this callback, the following event_metadata fields are conditional and may not always be present:

  • store_location
  • order_created_with_big_bulky
  • delivery_window
  • is_certified_delivery
{
"event_id": 301370064,
"event_name": "fulfillment.brand_new",
"event_metadata": {
"order_id": "testorder1",
"order_url": "",
"is_express": false,
"store_location": "42",
"is_instacartplus": false,
"post_checkout_link": "",
"is_certified_delivery": false,
"order_created_with_big_bulky": false,
"delivery_window": {
"ends_at": "2025-03-14T20:00:00Z",
"starts_at": "2025-03-14T19:00:00Z"
}
},
"event_timestamp": "2025-03-14T16:03:17Z"
}

Acknowledged

This event occurs when an order is acknowledged by a shopper.

In this callback, the following event_metadata fields are conditional and may not always be present:

  • store_location
  • order_delivery_id
{
"event_id": 301370064,
"event_name": "fulfillment.acknowledged",
"event_metadata": {
"order_id": "testorder1",
"order_url": "",
"is_express": false,
"store_location": "42",
"is_instacartplus": false,
"order_delivery_id": "16412931655205044",
"post_checkout_link": ""
},
"event_timestamp": "2025-03-14T16:13:37Z"
}

Picking

This event occurs when a shopper begins fulfilling an order.

{
"event_id": 301370065,
"event_name": "fulfillment.picking",
"event_metadata": {
"order_id": "testorder1",
"order_url": "",
"store_location": "42",
"post_checkout_link": ""
},
"event_timestamp": "2025-03-14T16:13:37Z"
}

Order item replacement

This event occurs when a shopper replaces an order item.

In this callback, the following event_metadata fields are conditional and may not always be present:

  • store_location
{
"event_id": 301370066,
"event_name": "fulfillment.order_item_replacement",
"event_metadata": {
"order_id": "testorder1",
"order_url": "",
"is_express": false,
"order_items": [
{
"qty": 1.0,
"item_rrc": "604188",
"item_upc": "00051500029275",
"line_num": "1",
"qty_unit": "each",
"refunded": false,
"replaced": false,
"scan_code": "00051500029275",
"qty_fulfilled": 1.0,
"qty_requested": 1.0,
"delivered_item_rrc": "604188",
"delivered_item_upc": "00051500029275",
"qty_fulfilled_unit": "each",
"qty_requested_unit": "each",
"requested_item_rrc": "604188",
"requested_item_upc": "00051500029275",
"substitution_status": ""
},
{
"qty": 0.0,
"item_rrc": "23226",
"item_upc": "00079813000118",
"line_num": "2",
"qty_unit": "each",
"refunded": true,
"replaced": false,
"scan_code": "",
"qty_fulfilled": 0.0,
"qty_requested": 2.0,
"delivered_item_rrc": "23226",
"delivered_item_upc": "00079813000118",
"qty_fulfilled_unit": "each",
"qty_requested_unit": "each",
"requested_item_rrc": "23226",
"requested_item_upc": "00079813000118",
"substitution_status": ""
},
{
"qty": 1.0,
"item_rrc": "753695",
"item_upc": "00747479001052",
"line_num": "3",
"qty_unit": "each",
"refunded": false,
"replaced": true,
"scan_code": "00747479001052",
"qty_fulfilled": 1.0,
"qty_requested": 1.0,
"delivered_item_rrc": "753695",
"delivered_item_upc": "00747479001052",
"qty_fulfilled_unit": "each",
"qty_requested_unit": "each",
"requested_item_rrc": "753682",
"requested_item_upc": "00747479000079",
"substitution_status": "PENDING"
}
],
"store_location": "42",
"is_instacartplus": false,
"post_checkout_link": ""
},
"event_timestamp": "2025-03-14T16:14:36Z"
}

Order item refund

This event occurs when a shopper refunds an order item.

In this callback, the following event_metadata fields are conditional and may not always be present:

  • store_location
{
"event_id": 301370067,
"event_name": "fulfillment.order_item_refund",
"event_metadata": {
"order_id": "testorder1",
"order_url": "",
"is_express": false,
"order_items": [
{
"qty": 1.0,
"item_rrc": "604188",
"item_upc": "00051500029275",
"line_num": "1",
"qty_unit": "each",
"refunded": false,
"replaced": false,
"scan_code": "00051500029275",
"qty_fulfilled": 1.0,
"qty_requested": 1.0,
"delivered_item_rrc": "604188",
"delivered_item_upc": "00051500029275",
"qty_fulfilled_unit": "each",
"qty_requested_unit": "each",
"requested_item_rrc": "604188",
"requested_item_upc": "00051500029275",
"substitution_status": ""
},
{
"qty": 0.0,
"item_rrc": "23226",
"item_upc": "00079813000118",
"line_num": "2",
"qty_unit": "each",
"refunded": true,
"replaced": false,
"scan_code": "",
"qty_fulfilled": 0.0,
"qty_requested": 2.0,
"delivered_item_rrc": "23226",
"delivered_item_upc": "00079813000118",
"qty_fulfilled_unit": "each",
"qty_requested_unit": "each",
"requested_item_rrc": "23226",
"requested_item_upc": "00079813000118",
"substitution_status": ""
},
{
"qty": 1.0,
"item_rrc": "753695",
"item_upc": "00747479001052",
"line_num": "3",
"qty_unit": "each",
"refunded": false,
"replaced": true,
"scan_code": "00747479001052",
"qty_fulfilled": 1.0,
"qty_requested": 1.0,
"delivered_item_rrc": "753695",
"delivered_item_upc": "00747479001052",
"qty_fulfilled_unit": "each",
"qty_requested_unit": "each",
"requested_item_rrc": "753682",
"requested_item_upc": "00747479000079",
"substitution_status": "PENDING"
}
],
"store_location": "42",
"is_instacartplus": false,
"post_checkout_link": ""
},
"event_timestamp": "2025-03-14T16:14:44Z"
}

Checkout​

This event occurs when all picking for the order has been completed.

In this callback, the following event_metadata fields are conditional and may not always be present:

  • store_location
  • delivery_window
{
"event_id": 301370068,
"event_name": "fulfillment.checkout",
"event_metadata": {
"order_id": "testorder1",
"order_url": "",
"is_express": false,
"order_items": [
{
"qty": 1.0,
"item_rrc": "604188",
"item_upc": "00051500029275",
"line_num": "1",
"qty_unit": "each",
"refunded": false,
"replaced": false,
"scan_code": "00051500029275",
"qty_fulfilled": 1.0,
"qty_requested": 1.0,
"delivered_item_rrc": "604188",
"delivered_item_upc": "00051500029275",
"qty_fulfilled_unit": "each",
"qty_requested_unit": "each",
"requested_item_rrc": "604188",
"requested_item_upc": "00051500029275",
"substitution_status": ""
},
{
"qty": 0.0,
"item_rrc": "23226",
"item_upc": "00079813000118",
"line_num": "2",
"qty_unit": "each",
"refunded": true,
"replaced": false,
"scan_code": "",
"qty_fulfilled": 0.0,
"qty_requested": 2.0,
"delivered_item_rrc": "23226",
"delivered_item_upc": "00079813000118",
"qty_fulfilled_unit": "each",
"qty_requested_unit": "each",
"requested_item_rrc": "23226",
"requested_item_upc": "00079813000118",
"substitution_status": ""
},
{
"qty": 1.0,
"item_rrc": "753695",
"item_upc": "00747479001052",
"line_num": "3",
"qty_unit": "each",
"refunded": false,
"replaced": true,
"scan_code": "00747479001052",
"qty_fulfilled": 1.0,
"qty_requested": 1.0,
"delivered_item_rrc": "753695",
"delivered_item_upc": "00747479001052",
"qty_fulfilled_unit": "each",
"qty_requested_unit": "each",
"requested_item_rrc": "753682",
"requested_item_upc": "00747479000079",
"substitution_status": "PENDING"
}
],
"store_location": "42",
"delivery_window": {
"ends_at": "2025-03-14T20:00:00Z",
"starts_at": "2025-03-14T19:00:00Z"
},
"is_instacartplus": false,
"post_checkout_link": ""
},
"event_timestamp": "2025-03-14T16:15:06Z"
}

Delivering

This event occurs when the order has left the store location and is being delivered.

In this callback, the following event_metadata fields are conditional and may not always be present:

  • store_location
  • bags_count
  • delivery_window
  • pos_payment_method
  • is_certified_delivery
  • order_created_with_big_bulky
{
"event_id": 1201895966044343904,
"event_name": "fulfillment.delivering",
"event_timestamp": "2020-07-07T16:35:22Z",
"event_metadata": {
"order_id": "b7fab7ae-11fc-4453-98e1-a2f5421a2b81",
"order_url": "retailer.com/xyz",
"store_location": "WEST-23243",
"delivery_eta": "2020-07-07T17:30:00Z",
"is_express": true,
"is_instacartplus": true,
"is_certified_delivery": true,
"order_created_with_big_bulky": true,
"order_items": [
{
"qty": 1.0,
"item_rrc": "604188",
"item_upc": "00051500029275",
"line_num": "1",
"qty_unit": "each",
"refunded": false,
"replaced": false,
"scan_code": "00051500029275",
"qty_fulfilled": 1.0,
"qty_requested": 1.0,
"delivered_item_rrc": "604188",
"delivered_item_upc": "00051500029275",
"qty_fulfilled_unit": "each",
"qty_requested_unit": "each",
"requested_item_rrc": "604188",
"requested_item_upc": "00051500029275",
"substitution_status": ""
},
{
"qty": 1.0,
"item_rrc": "604188",
"item_upc": "00051500029275",
"line_num": "2",
"qty_unit": "each",
"refunded": false,
"replaced": false,
"scan_code": "00051500029275",
"qty_fulfilled": 1.0,
"qty_requested": 1.0,
"delivered_item_rrc": "604188",
"delivered_item_upc": "00051500029275",
"qty_fulfilled_unit": "each",
"qty_requested_unit": "each",
"requested_item_rrc": "604188",
"requested_item_upc": "00051500029275",
"substitution_status": ""
}
],
"delivery_window": {
"starts_at": "2020-07-07T17:00:00Z",
"ends_at": "2020-07-07T18:00:00Z"
},
"bags_count": 3,
"pos_payment_method": "UNSPECIFIED",
"post_checkout_link": "https://mocked-post-checkout-link.example.com"
}
}

Order location

This event occurs when the order's status moves to delivering. In the callback, Instacart provides you the coordinates of the the shopper's location. To be notified of this event, an order location callback frequency, which determines the interval between updates, must be defined in your Connect account. Instacart sends location updates at the designated intervals until the order's status changes. To set or change this interval, contact your Instacart representative.

In this callback, the following event_metadata fields are conditional and may not always be present:

  • store_location
{
"event_id": 1201895966044343904,
"event_name": "fulfillment.order_location",
"event_timestamp": "2020-07-07T16:35:22Z",
"event_metadata": {
"order_id": "b7fab7ae-11fc-4453-98e1-a2f5421a2b81",
"order_url": "retailer.com/xyz",
"store_location": "WEST-23243",
"coordinates": {
"latitude": 1,
"longitude": 1
},
"post_checkout_link": "https://mocked.example.com"
}
}

Late delivery

This event occurs when the delivery time of an order changes.

In this callback, the following event_metadata fields are conditional and may not always be present:

  • store_location
{
"event_id": 1201895966044343904,
"event_name": "fulfillment.late_delivery",
"event_timestamp": "2020-07-07T16:35:22Z",
"event_metadata": {
"order_id": "b7fab7ae-11fc-4453-98e1-a2f5421a2b81",
"order_url": "retailer.com/xyz",
"store_location": "WEST-23243",
"new_window": {
"starts_at": "2020-07-07T17:00:00Z",
"ends_at": "2020-07-07T18:00:00Z"
},
"post_checkout_link": "https://mocked.example.com"
}
}

Customer missing

This event occurs when a shopper attempts to deliver an order and the customer is missing.

In this callback, the following event_metadata fields are conditional and may not always be present:

  • store_location
{
"event_id": 1201895966044343904,
"event_name": "fulfillment.customer_mia",
"event_timestamp": "2020-07-07T16:35:22Z",
"event_metadata": {
"order_id": "b7fab7ae-11fc-4453-98e1-a2f5421a2b81",
"order_url": "retailer.com/xyz",
"store_location": "WEST-23243",
"post_checkout_link": "https://mocked.example.com"
}
}

Staged

This event occurs when the shopping and checkout are complete and the order has been placed in the staging area. When enabled in the context of a delivery workflow, this callback is sent only when the shopper who picks the order is different from the shopper who delivers the order.

In this callback, the following event_metadata fields are conditional and may not always be present:

  • store_location
  • pickup_link
  • status_link
  • bags_count
{
"event_id": 301370072,
"event_name": "fulfillment.staged",
"event_metadata": {
"order_id": "testorder1",
"order_url": "",
"bags_count": 1,
"is_express": false,
"order_items": [
{
"qty": 1.0,
"item_rrc": "604188",
"item_upc": "00051500029275",
"line_num": "1",
"qty_unit": "each",
"refunded": false,
"replaced": false,
"scan_code": "00051500029275",
"qty_fulfilled": 1.0,
"qty_requested": 1.0,
"delivered_item_rrc": "604188",
"delivered_item_upc": "00051500029275",
"qty_fulfilled_unit": "each",
"qty_requested_unit": "each",
"requested_item_rrc": "604188",
"requested_item_upc": "00051500029275",
"substitution_status": ""
},
{
"qty": 0.0,
"item_rrc": "23226",
"item_upc": "00079813000118",
"line_num": "2",
"qty_unit": "each",
"refunded": true,
"replaced": false,
"scan_code": "",
"qty_fulfilled": 0.0,
"qty_requested": 2.0,
"delivered_item_rrc": "23226",
"delivered_item_upc": "00079813000118",
"qty_fulfilled_unit": "each",
"qty_requested_unit": "each",
"requested_item_rrc": "23226",
"requested_item_upc": "00079813000118",
"substitution_status": ""
},
{
"qty": 1.0,
"item_rrc": "753695",
"item_upc": "00747479001052",
"line_num": "3",
"qty_unit": "each",
"refunded": false,
"replaced": true,
"scan_code": "00747479001052",
"qty_fulfilled": 1.0,
"qty_requested": 1.0,
"delivered_item_rrc": "753695",
"delivered_item_upc": "00747479001052",
"qty_fulfilled_unit": "each",
"qty_requested_unit": "each",
"requested_item_rrc": "753682",
"requested_item_upc": "00747479000079",
"substitution_status": "PENDING"
}
],
"pickup_link": "https://c.inst.cr/s/Y1Q1SEZBUUUx",
"status_link": "https://c.inst.cr/s/Y1Q1SEZBUUUx",
"store_location": "42",
"is_instacartplus": false,
"post_checkout_link": ""
},
"event_timestamp": "2025-03-14T16:16:34Z"
}

Customer acknowledged

This event occurs when the runner is collecting the bags from the staging area.

In this callback, the following event_metadata fields are conditional and may not always be present:

  • store_location
{
"event_id": 1201895966044343904,
"event_name": "fulfillment.customer_acknowledged",
"event_timestamp": "2020-07-07T16:35:22Z",
"event_metadata": {
"order_id": "b7fab7ae-11fc-4453-98e1-a2f5421a2b81",
"shopper_display_name": "Chris",
"order_url": "retailer.com/xyz",
"store_location": "WEST-23243"
}
}

Pickup runner started

This event occurs when the pickup runner is heading outside with bags.

In this callback, the following event_metadata fields are conditional and may not always be present:

  • store_location
{
"event_id": 1201895966044343904,
"event_name": "fulfillment.pickup_runner_started",
"event_timestamp": "2020-07-07T16:35:22Z",
"event_metadata": {
"order_id": "b7fab7ae-11fc-4453-98e1-a2f5421a2b81",
"order_url": "retailer.com/xyz",
"store_location": "WEST-23243"
}
}

Unable to find customer

This event occurs when the pickup runner is unable to find the customer.

In this callback, the following event_metadata fields are conditional and may not always be present:

  • store_location
{
"event_id": 1201895966044343904,
"event_name": "fulfillment.unable_to_find_customer",
"event_timestamp": "2020-07-07T16:35:22Z",
"event_metadata": {
"order_id": "b7fab7ae-11fc-4453-98e1-a2f5421a2b81",
"order_url": "retailer.com/xyz",
"store_location": "WEST-23243"
}
}

Runner not found

This event occurs when no pickup runner is available. The message to the customer explains that the curbside pickup has transitioned to an in-store pickup.

In this callback, the following event_metadata fields are conditional and may not always be present:

  • store_location
{
"event_id": 1201895966044343904,
"event_name": "fulfillment.runner_not_found",
"event_timestamp": "2020-07-07T16:35:22Z",
"event_metadata": {
"order_id": "b7fab7ae-11fc-4453-98e1-a2f5421a2b81",
"order_url": "retailer.com/xyz",
"store_location": "WEST-23243"
}
}

Pickup Geofence reached

This event occurs when the customer reaches the store's virtual Geofence. The message to the customer contains any additional pickup instructions.

In this callback, the following event_metadata fields are conditional and may not always be present:

  • store_location
{
"event_id": 1201895966044343904,
"event_name": "fulfillment.pickup_geofence_reached",
"event_timestamp": "2020-07-07T16:35:22Z",
"event_metadata": {
"order_id": "b7fab7ae-11fc-4453-98e1-a2f5421a2b81",
"order_url": "retailer.com/xyz",
"store_location": "WEST-23243"
}
}

Late pickup

This event occurs when the pickup time of an order changes.

In this callback, the following event_metadata fields are conditional and may not always be present:

  • store_location
{
"event_id": 1201895966044343904,
"event_name": "fulfillment.late_pickup",
"event_timestamp": "2020-07-07T16:35:22Z",
"event_metadata": {
"order_id": "b7fab7ae-11fc-4453-98e1-a2f5421a2b81",
"order_url": "retailer.com/xyz",
"post_checkout_link": "https://mocked.example.com",
"store_location": "WEST-23243",
"new_window": {
"starts_at": "2020-07-07T17:00:00Z",
"ends_at": "2020-07-07T18:00:00Z"
}
}
}

Delivered

This event occurs when the order is successfully delivered or picked up by a customer.

In this callback, the following event_metadata fields are conditional and may not always be present:

  • store_location
  • bags_count
  • is_certified_delivery
  • certified_delivery_name
  • certified_delivery_confirmed_at
{
"event_id": 301370088,
"event_name": "fulfillment.delivered",
"event_metadata": {
"order_id": "testorder1",
"order_url": "",
"bags_count": 10,
"is_express": false,
"order_items": [
{
"qty": 1.0,
"item_rrc": "604188",
"item_upc": "00051500029275",
"line_num": "1",
"qty_unit": "each",
"refunded": false,
"replaced": false,
"scan_code": "00051500029275",
"qty_fulfilled": 1.0,
"qty_requested": 1.0,
"delivered_item_rrc": "604188",
"delivered_item_upc": "00051500029275",
"qty_fulfilled_unit": "each",
"qty_requested_unit": "each",
"requested_item_rrc": "604188",
"requested_item_upc": "00051500029275",
"substitution_status": ""
},
{
"qty": 0.0,
"item_rrc": "23226",
"item_upc": "00079813000118",
"line_num": "2",
"qty_unit": "each",
"refunded": true,
"replaced": false,
"scan_code": "",
"qty_fulfilled": 0.0,
"qty_requested": 2.0,
"delivered_item_rrc": "23226",
"delivered_item_upc": "00079813000118",
"qty_fulfilled_unit": "each",
"qty_requested_unit": "each",
"requested_item_rrc": "23226",
"requested_item_upc": "00079813000118",
"substitution_status": ""
},
{
"qty": 1.0,
"item_rrc": "753695",
"item_upc": "00747479001052",
"line_num": "3",
"qty_unit": "each",
"refunded": false,
"replaced": true,
"scan_code": "00747479001052",
"qty_fulfilled": 1.0,
"qty_requested": 1.0,
"delivered_item_rrc": "753695",
"delivered_item_upc": "00747479001052",
"qty_fulfilled_unit": "each",
"qty_requested_unit": "each",
"requested_item_rrc": "753682",
"requested_item_upc": "00747479000079",
"substitution_status": "PENDING"
}
],
"store_location": "42",
"is_instacartplus": false,
"pos_payment_method": "MARQETA",
"post_checkout_link": "",
"is_certified_delivery": false,
"certified_delivery_name": "MockedName",
"certified_delivery_confirmed_at": "2025-01-01T12:00:00Z"
},
"event_timestamp": "2025-03-14T16:26:39Z"
}

Rescheduled

This event occurs when an order is rescheduled and will be fulfilled at another time.

In this callback, the following event_metadata fields are conditional and may not always be present:

  • store_location
{
"event_id": 1201895966044343904,
"event_name": "fulfillment.rescheduled",
"event_timestamp": "2020-07-07T16:35:22Z",
"event_metadata": {
"order_id": "b7fab7ae-11fc-4453-98e1-a2f5421a2b81",
"order_url": "retailer.com/xyz",
"store_location": "WEST-23243",
"new_window": {
"starts_at": "2020-07-07T17:00:00Z",
"ends_at": "2020-07-07T18:00:00Z"
},
"post_checkout_link": "https://mocked.example.com"
}
}

Canceled

This event occurs when an order is canceled for any reason. For a list of possible cancellation_reason and cancellation_type values, see Cancellation reasons and cancellation types. You can use this information in customer notifications.

In this callback, the following event_metadata fields are conditional and may not always be present:

  • store_location
  • cancellation_type
{
"event_id": 301370102,
"event_name": "fulfillment.canceled",
"event_metadata": {
"order_id": "testorder2",
"order_url": "",
"store_location": "42",
"cancellation_type": "cancelled by retailer",
"pos_payment_method": "UNSPECIFIED",
"post_checkout_link": "",
"cancellation_reason": "retailer_driven"
},
"event_timestamp": "2025-03-14T16:38:43Z"
}

Tip adjustment

This event occurs when the tip for an order is successfully updated after delivery completion.

In this callback, the following event_metadata fields are conditional and may not always be present:

  • store_location
{
"event_id": 1201895966044343904,
"event_name": "fulfillment.tip_adjustment",
"event_timestamp": "2020-07-07T16:35:22Z",
"event_metadata": {
"order_id": "b7fab7ae-11fc-4453-98e1-a2f5421a2b81",
"order_url": "retailer.com/xyz",
"store_location": "WEST-23243",
"is_express": true,
"is_instacartplus": true,
"order_items": [
{
"qty": 1.0,
"item_rrc": "604188",
"item_upc": "00051500029275",
"line_num": "1",
"qty_unit": "each",
"refunded": false,
"replaced": false,
"scan_code": "00051500029275",
"qty_fulfilled": 1.0,
"qty_requested": 1.0,
"delivered_item_rrc": "604188",
"delivered_item_upc": "00051500029275",
"qty_fulfilled_unit": "each",
"qty_requested_unit": "each",
"requested_item_rrc": "604188",
"requested_item_upc": "00051500029275",
"substitution_status": ""
},
{
"qty": 1.0,
"item_rrc": "604188",
"item_upc": "00051500029275",
"line_num": "2",
"qty_unit": "each",
"refunded": false,
"replaced": false,
"scan_code": "00051500029275",
"qty_fulfilled": 1.0,
"qty_requested": 1.0,
"delivered_item_rrc": "604188",
"delivered_item_upc": "00051500029275",
"qty_fulfilled_unit": "each",
"qty_requested_unit": "each",
"requested_item_rrc": "604188",
"requested_item_upc": "00051500029275",
"substitution_status": ""
}
],
"post_checkout_link": "https://mocked.example.com"
}
}

At store

This event occurs when a shopper arrives at the store to pick up a last mile delivery order.

In this callback, the following event_metadata fields are conditional and may not always be present:

  • store_location
{
"event_id": 1201895966044343904,
"event_name": "fulfillment.at_store",
"event_timestamp": "2020-07-07T16:35:22Z",
"event_metadata": {
"order_id": "b7fab7ae-11fc-4453-98e1-a2f5421a2b81",
"order_url": "retailer.com/xyz",
"store_location": "WEST-23243",
"post_checkout_link": "https://mocked.example.com"
}
}

Acknowledged for delivery

This event occurs when a shopper acknowledges a last mile delivery order.

In this callback, the following event_metadata fields are conditional and may not always be present:

  • store_location.
{
"event_id": 1201895966044343904,
"event_name": "fulfillment.acknowledged_for_delivery",
"event_timestamp": "2020-07-07T16:35:22Z",
"event_metadata": {
"order_id": "b7fab7ae-11fc-4453-98e1-a2f5421a2b81",
"order_url": "retailer.com/xyz",
"store_location": "WEST-23243",
"post_checkout_link": "https://mocked.example.com"
}
}

Bags verified

This event occurs when a shopper verifies the bags of a last mile delivery order at the store.

In this callback, the following event_metadata fields are conditional and may not always be present:

  • store_location
{
"event_id": 1201895966044343904,
"event_name": "fulfillment.bags_verified",
"event_timestamp": "2020-07-07T16:35:22Z",
"event_metadata": {
"order_id": "b7fab7ae-11fc-4453-98e1-a2f5421a2b81",
"order_url": "retailer.com/xyz",
"store_location": "WEST-23243",
"post_checkout_link": "https://mocked.example.com"
}
}

Arrival at customer

This event occurs when a shopper arrives at the customer's location with a last mile delivery order.

In this callback, the following event_metadata fields are conditional and may not always be present:

  • store_location
{
"event_id": 1201895966044343904,
"event_name": "fulfillment.arrival_at_customer",
"event_timestamp": "2020-07-07T16:35:22Z",
"event_metadata": {
"order_id": "b7fab7ae-11fc-4453-98e1-a2f5421a2b81",
"order_url": "retailer.com/xyz",
"store_location": "WEST-23243",
"post_checkout_link": "https://mocked.example.com"
}
}

At store ETA

After a shopper acknowledges a last mile delivery order, this event occurs every two minutes. The callback provides the shopper's estimated time of arrival at the store's location.

In this callback, the following event_metadata fields are conditional and may not always be present:

  • store_location
  • bag_label
{
"event_id": 1201895966044343904,
"event_name": "fulfillment.at_store_eta",
"event_timestamp": "2020-07-07T16:35:22Z",
"event_metadata": {
"order_id": "b7fab7ae-11fc-4453-98e1-a2f5421a2b81",
"order_url": "retailer.com/xyz",
"store_location": "WEST-23243",
"driver_eta": "2020-07-07T16:55:22Z",
"bag_label": "Singh",
"post_checkout_link": "https://mocked.example.com"
}
}

Rating updated

This event occurs when the order's rating is created or updated through the Feedback API. For more information, see Order feedback.

In this callback, the following event_metadata fields are conditional and may not always be present:

  • store_location
  • rating_value
  • highlights
  • thank_you_note
{
"event_id": 1201895966044343904,
"event_name": "fulfillment.rating_updated",
"event_timestamp": "2020-07-07T16:35:22Z",
"event_metadata": {
"order_id": "b7fab7ae-11fc-4453-98e1-a2f5421a2b81",
"order_url": "retailer.com/xyz",
"store_location": "WEST-23243",
"rating_value": "STARS5",
"highlights": ["SMOOTH_DELIVERY"],
"thank_you_note": "thanks!",
"post_checkout_link": "https://mocked.example.com"
}
}

Rating reminder

If an order's rating still hasn't been assigned one hour after a successful delivery or pick up, then this reminder event occurs.

In this callback, the following event_metadata fields are conditional and may not always be present:

  • store_location
{
"event_id": 1201895966044343904,
"event_name": "fulfillment.rating_reminder",
"event_timestamp": "2020-07-07T16:35:22Z",
"event_metadata": {
"order_id": "b7fab7ae-11fc-4453-98e1-a2f5421a2b81",
"order_url": "WEST-23243",
"store_location": "WEST-23243",
"post_checkout_link": "https://mocked.example.com"
}
}

Object descriptions

The following objects are used in callbacks.

note

Fields marked with * are not always present.

Order Callback object

FieldTypeDescription
event_idintegerThe ID of the event that triggered the callback.
event_namestringThe name of the event that triggered the callback. For valid values, see event_name in each example event payload.
event_timestampstringThe time the event occurred in ISO 8601 format.
event_metadataEventMetadataMetadata related to the event.

EventMetadata object

FieldTypeDescription
order_idstringThe ID of the order relevant to the event.
order_urlstringThe URL to view the order status.
retailer_id*stringThe ID of the retailer. To enable this field, contact your Instacart representative.
store_location*stringThe location code of the store where the order's items are picked. For delivery orders, this field might not be returned until after the picking event occurs.
is_express*booleanDeprecated. Indicates whether the order received Instacart+ membership benefits.
is_instacartplus*booleanIndicates whether the order received Instacart+ membership benefits.
is_certified_delivery*booleanIndicates whether the order requires certified delivery.
certified_delivery_name*stringThe name of the individual who certified the delivery.
certified_delivery_confirmed_at*date-timeThe time the certified delivery was confirmed.
order_created_with_big_bulky*booleanIndicates whether the order included big and bulky items at order creation.
post_checkout_link*stringDelivery. The URL of the Order status page; nil if the Connect Order status page is not enabled.
delivery_window*DeliveryWindowDelivery. The expected time window the order will be delivered within.
new_window*DeliveryWindowThe expected time window the order will be delivered or ready for pickup.
order_items*Array(OrderItem)The items included in the order.
cancellation_reason*stringThe person or entity that canceled the order. For a list of possible values, see Cancellation reasons and cancellation types.
cancellation_type*stringProvides details on why the order was canceled by the person or entity identified by cancellation_reason. For a list of possible values, see Cancellation reasons and cancellation types.
pickup_link*stringPickup. A link to the pickup status page that allows users to notify the retailer they have arrived at the store.
bags_count*integerThe number of bags for the order.
bag_label*stringA user-friendly label that helps shoppers identify the order.
has_partner_picker_shopper*booleanIndicates whether a partner shopper picked the order. To enable this field, contact your Instacart representative.
delivery_eta*stringThe estimated time of arrival of the order in ISO 8601 format.
driver_eta*stringThe estimated time of arrival of the shopper to the store location in ISO 8601 format.
coordinates*CoordinatesThe coordinates.
rating_value*stringThe star rating value for the completed order.
highlights*stringThe highlights for the completed order.
thank_you_note*stringThe completion message for the order feedback.
pos_payment_method*stringThe payment method used at the point of sale (POS).

DeliveryWindow object

FieldTypeDescription
starts_atstringThe time the delivery or pickup window begins in ISO 8601 format.
ends_atstringThe time the delivery or pickup window ends in ISO 8601 format.

OrderItem object

FieldTypeDescription
line_numstringThe item's line number in the order.
qtyfloatThe quantity of the item provided to the customer. In other words, the quantity that the customer actually received. Matches value of qty_fulfilled.
qty_unitstringThe unit of measurement for the qty of the item, either each or lb. Matches value of qty_fulfilled_unit.
qty_fulfilled*floatThe quantity of the item provided to the customer. In other words, the quantity that the customer actually received. Matches value of qty.
qty_fulfilled_unit*stringThe unit of measurement for the qty_fulfilled of the item, either each or lb. Matches value of qty_unit.
qty_requested*floatThe quantity of the item requested by the customer.
qty_requested_unit*stringThe unit of measurement for the qty_requested of the item, either each or lb.
replacedbooleanIndicates whether the item was replaced.
refundedbooleanIndicates whether the item was refunded.
item_upc*stringThe universal product code (UPC) of the item provided to the customer. In other words, the UPC of the item that the customer actually received. Matches the value of delivered_item_upc.
item_rrc*stringThe retailer reference code (RRC) of the item provided to the customer. In other words, the RRC of the item that the customer actually received. Matches the value of delivered_item_rrc.
delivered_item_upc*stringThe universal product code (UPC) of the item provided to the customer. In other words, the UPC of the item that the customer actually received. Matches the value of item_upc.
delivered_item_rrc*stringThe retailer reference code (RRC) of the item provided to the customer. In other words, the RRC of the item that the customer actually received. Matches the value of item_rc.
requested_item_upc*stringThe universal product code (UPC) of the item requested by the customer.
requested_item_rrc*stringThe retailer reference code (RRC) of the item requested by the customer.
scan_code*stringThe scan code of the item.
substitution_status*stringThe customer's approval status of the substitution. One of PENDING, APPROVED, or REJECTED.
shopper_provided_item_name*stringThe item name provided by shoppers for items that they added.
shopper_provided_item_price*Shopper_provided_item_priceThe item price provided by shoppers for items that they added.

Shopper_provided_item_price object

FieldTypeDescription
amountfloatThe amount of a specified currency.
currencystringThe currency type in ISO 4217 format. For example: USD.

Coordinates object

FieldTypeDescription
latitudenumberThe latitude.
longitudenumberThe longitude.

Cancellation reasons and cancellation types

The following table describes the valid cancellation_reason values:

Cancellation ReasonDescription
customer_drivenThe customer triggered the cancellation.
instacart_drivenInstacart triggered the cancellation.
retailer_drivenThe retailer triggered the cancellation.
shopper_drivenThe shopper triggered the cancellation.
unbatchableThe Instacart batch system triggered the cancellation.
otherThe cancellation was triggered by another source.

For each cancellation_reason, the following table describes the valid cancellation_type values:

Cancellation ReasonCancellation TypeDescription
customer_drivenduplicate orderThe customer reported the order as a duplicate order.
customer_drivencustomer app navigation issueThe customer reported an app navigation issue.
customer_drivencustomer requested since order is earlyThe customer requested the cancellation because the order would be early.
customer_drivencustomer requested since order is lateThe customer requested the cancellation because the order would be late.
customer_drivencustomer miaThe shopper reported that the customer is unavailable.
customer_drivenincorrect customer information (phone/address)The customer requested the cancellation because of incorrect information, such as the incorrect phone number or address.
customer_drivencustomer requested to cancelThe customer requested the cancellation.
customer_drivencancelled by customerThe customer canceled the order.
instacart_drivenfraudulent customerInstacart canceled the fraudulent customer’s order.
instacart_drivenmanual_fraudInstacart canceled the fraudulent order.
instacart_drivenmissing charge log for deliveryInstacart canceled the order because of the missing charge log for delivery.
instacart_drivensystem errorInstacart canceled the order because of a system error.
retailer_drivencard decline on reauthThe order was canceled because the payment card was declined.
retailer_drivenshopper initiated out of stockThe shopper canceled the order because items were out of stock.
retailer_drivenfulfillment initiated out of stockThe retailer canceled the order because items were out of stock.
retailer_drivensingle item order out of stockThe retailer canceled the single item order because the item was out of stock.
retailer_driventoo many out of stock itemsThe retailer canceled the order because many of the items were out of stock.
retailer_drivenstore early closureThe retailer canceled the order because of early store closure.
retailer_drivencancelled by retailerThe retailer canceled the order.
shopper_drivenshopper unable to complete orderThe shopper was unable to complete the order.
shopper_drivenshopper could not find addressThe shopper was unable to find the address.
unbatchableunable to reschedule unbatchableInstacart canceled the order because the batched order could not be rescheduled.
unbatchableunable to reschedule as no option foundInstacart canceled the order because the order could not be rescheduled.
unbatchableunbatchableInstacart canceled the order because the order could not be batched.
otherotherThe order was canceled for other reasons.
otherInstacart Connect order with all items refundedInstacart Connect canceled the order and refunded all items.
otherOnLine Pay FailureThe online payment failed.
othermass cancellationThe retailer canceled all store orders due to a store issue.
otherunknownThe order was canceled for unknown reasons.
othernoneThe order was canceled without a reason.

Callback errors and retries

If your webhook's callback endpoint returns an error, Connect makes up to five retry attempts at the following intervals: 4 seconds, 16 seconds, 64 seconds, 256 seconds, and 1024 seconds. If another event occurs during these retries, that event's callback might succeed before any of the retries do. In this case, you would receive the events out of order.

Best practice

Monitor the callback endpoint to catch and resolve issues early.

The Instacart Connect operations team also checks for repeated retries and attempts to contact the retailer about issues.