Skip to main content

Event callbacks

The Connect platform sends callbacks to your retailer site when an order changes status. Some callbacks are always enabled, while others can be set to meet your requirements. To set up a callback endpoint and configure the optional callbacks, contact your Instacart Connect representative.

important

The order in which event callbacks are sent or received is not guaranteed. For more information, see Callback errors and retries.

The following table lists the callbacks, notes which ones are always enabled, and identifies which service uses them.

CallbacksEnabledDeliveryPickupLast mile delivery
Brand newEnabledโœ…โœ…โœ…
AcknowledgedEnabledโœ…โŒโœ…
PickingEnabledโœ…โœ…โŒ
Order item replacementOptionalโœ…โœ…โŒ
Order item refundOptionalโœ…โœ…โŒ
DeliveringEnabledโœ…โŒโœ…
Late deliveryOptionalโœ…โŒโœ…
Customer missingOptionalโœ…โŒโœ…
StagedEnabledโŒโœ…โœ…
Late pickupOptionalโŒโœ…โŒ
DeliveredEnabledโœ…โœ…โœ…
RescheduledOptionalโœ…โœ…โœ…
CanceledOptionalโœ…โœ…โœ…
Tip adjustmentOptionalโœ…โŒโœ…
At storeOptionalโŒโŒโœ…
Acknowledged for deliveryOptionalโŒโŒโœ…
Bags verifiedOptionalโŒโŒโœ…
Arrival at customerOptionalโŒโŒโœ…

Callback descriptions#

Brand new#

This event occurs when an order is successfully created in the Instacart system. Always enabled.

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

Acknowledged#

This event occurs when an order is acknowledged by an Instacart shopper. Always enabled.

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

Picking#

This event occurs when an Instacart shopper begins fulfilling an order. Always enabled.

{  "event_id": 1201895966044343904,  "event_name": "fulfillment.picking",  "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"  }}

Order item replacement#

This event occurs when an Instacart shopper replaces an order item.

{  "event_id": 1201895966044343904,  "event_name": "fulfillment.order_item_replacement",  "event_timestamp": "2020-07-07T16:35:22Z",  "event_metadata": {    "order_id": "b7fab7ae-11fc-4453-98e1-a2f5421a2b81",    "order_url": "retailer.com/xyz",    "order_items": [      {        "line_num": "1",        "qty": 1.0,        "qty_unit": "each",        "replaced": false,        "refunded": false,        "item_upc": "036000291457",        "item_rrc": "329439334443",        "requested_item_upc": "123456789012",        "delivered_item_upc": "036000291457",        "requested_item_rrc": "675643210909",        "delivered_item_rrc": "329439334443",        "scan_code": "8743528"      },      {        "line_num": "2",        "qty": 0.87,        "qty_unit": "lbs",        "replaced": true,        "refunded": false,        "item_upc": "036000291457",        "item_rrc": "329439334443",        "requested_item_upc": "097264536743",        "delivered_item_upc": "036000291457",        "requested_item_rrc": "321984628343",        "delivered_item_rrc": "329439334443",        "scan_code": "2387549"      }    ]  }}

Order item refund#

This event occurs when an Instacart shopper refunds an order item.

{  "event_id": 1201895966044343904,  "event_name": "fulfillment.order_item_refund",  "event_timestamp": "2020-07-07T16:35:22Z",  "event_metadata": {    "order_id": "b7fab7ae-11fc-4453-98e1-a2f5421a2b81",    "order_url": "retailer.com/xyz",    "order_items": [      {        "line_num": "1",        "qty": 1.0,        "qty_unit": "each",        "replaced": false,        "refunded": false,        "item_upc": "036000291457",        "scan_code": "8743528"      },      {        "line_num": "2",        "qty": 0.87,        "qty_unit": "lbs",        "replaced": false,        "refunded": true,        "item_upc": "036000291457",        "item_rrc": "329439334443",        "scan_code": "2387549"      }    ]  }}

Delivering#

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

{  "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",    "order_items": [      {        "line_num": "1",        "qty": 1.0,        "qty_unit": "each",        "replaced": false,        "refunded": false,        "item_upc": "036000291457",        "item_rrc": "329439334443",        "scan_code": "8743528"      },      {        "line_num": "2",        "qty": 0.87,        "qty_unit": "lbs",        "replaced": true,        "refunded": false,        "item_upc": "036000291457",        "item_rrc": "329439334443",        "scan_code": "2387549"      }    ],    "delivery_window": {      "starts_at": "2020-07-07T17:00:00Z",      "ends_at": "2020-07-07T18:00:00Z"    }  }}

Late delivery#

This event occurs when the delivery time of an order has changed.

{  "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",    "new_window": {      "starts_at": "2020-07-07T17:00:00Z",      "ends_at": "2020-07-07T18:00:00Z"    }  }}

Customer missing#

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

{  "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"  }}

Staged#

This event occurs when the shopping and checkout are complete and the order has been placed in the staging area. Always enabled.

{  "event_id": 1201895966044343904,  "event_name": "fulfillment.staged",  "event_timestamp": "2020-07-07T16:35:22Z",  "event_metadata": {    "order_id": "b7fab7ae-11fc-4453-98e1-a2f5421a2b81",    "order_url": "retailer.com/xyz",    "order_items": [      {        "line_num": "1",        "qty": 1.0,        "qty_unit": "each",        "replaced": false,        "refunded": false,        "item_upc": "036000291457",        "item_rrc": "329439334443",        "scan_code": "8743528"      },      {        "line_num": "2",        "qty": 0.87,        "qty_unit": "lbs",        "replaced": true,        "refunded": false,        "item_upc": "036000291457",        "item_rrc": "329439334443",        "scan_code": "2387549"      }    ],    "pickup_link": "retailer.com/xyz",    "status_link": "Deprecated"  }}

Late pickup#

This event occurs when the pickup time of an order has changed.

{  "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",    "new_window": {      "starts_at": "2020-07-07T17:00:00Z",      "ends_at": "2020-07-07T18:00:00Z"    }  }}

Delivered#

This event occurs when the order has been successfully delivered or picked up by a customer. Always enabled.

{  "event_id": 1201895966044343904,  "event_name": "fulfillment.delivered",  "event_timestamp": "2020-07-07T16:35:22Z",  "event_metadata": {    "order_id": "b7fab7ae-11fc-4453-98e1-a2f5421a2b81",    "order_url": "retailer.com/xyz",    "order_items": [      {        "line_num": "1",        "qty": 1.0,        "qty_unit": "each",        "replaced": false,        "refunded": false,        "item_upc": "036000291457",        "item_rrc": "329439334443",        "scan_code": "8743528"      },      {        "line_num": "2",        "qty": 0.87,        "qty_unit": "lbs",        "replaced": true,        "refunded": false,        "item_upc": "036000291457",        "item_rrc": "329439334443",        "scan_code": "2387549"      }    ]  }}

Rescheduled#

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

{  "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",    "new_window": {      "starts_at": "2020-07-07T17:00:00Z",      "ends_at": "2020-07-07T18:00:00Z"    }  }}

Canceled#

This event occurs when an order has been canceled for any reason.

{  "event_id": 1201895966044343904,  "event_name": "fulfillment.canceled",  "event_timestamp": "2020-07-07T16:35:22Z",  "event_metadata": {    "order_id": "b7fab7ae-11fc-4453-98e1-a2f5421a2b81",    "order_url": "retailer.com/xyz",    "cancellation_reason": "customer requested"  }}

Tip adjustment#

This event occurs when the tip for an order has successfully been updated after delivery or pickup is complete.

{  "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",    "order_items": [      {        "line_num": "1",        "qty": 1.0,        "qty_unit": "each",        "replaced": false,        "refunded": false,        "item_upc": "036000291457",        "item_rrc": "329439334443",        "scan_code": "8743528"      },      {        "line_num": "2",        "qty": 0.87,        "qty_unit": "lbs",        "replaced": true,        "refunded": false,        "item_upc": "036000291457",        "item_rrc": "329439334443",        "scan_code": "2387549"      }    ]  }}

At store#

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

{  "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"  }}

Acknowledged for delivery#

This event occurs when a last mile delivery order is acknowledged by an Instacart shopper.

{  "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"  }}

Bags verified#

This event occurs when an Instacart shopper has verified the bags of a last mile delivery order at the store.

{  "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"  }}

Arrival at customer#

This event occurs when an Instacart shopper has arrived at the customer's location with their last mile delivery order.

{  "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"  }}

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 the event_name in each of the callbacks.
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.
store_location*stringThe location code of the store where the order is fulfilled.
post_checkout_link*stringDelivery. The URL link to the Connect Post Checkout app of the given order; nil if Connect Post Checkout app 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 reason the order was canceled.
status_link*stringDeprecated. Use pickup_link instead. โ€” A link to the pickup status page that allows users to notify the retailer they are at the store.
pickup_link*stringPickup. A link to the pickup status page that allows users to notify the retailer they are at the store.

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.
qty_unitstringThe quantity type, either each or lb.
replacedbooleanIndicates whether the item was replaced.
refundedbooleanIndicates whether the item was refunded.
item_upc*stringThe item's universal product code (UPC).
item_rrc*stringThe item's retailer reference code (RRC).
scan_code*stringThe scan code of the item.

Callback errors and retries#

If a callback endpoint returns an error, Connect retries the event callback five times at the following intervals: 4 seconds, 16 seconds, 64 seconds, 256 seconds, and 1024 seconds. If another event occurs during the retries and its callback is successful before the failed callback succeeds, the events can be received 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.