Event callbacks (webhooks)

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.

Callbacks	Delivery	Pickup	Last 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

Field	Type	Description
`event_id`	integer	The ID of the event that triggered the callback.
`event_name`	string	The name of the event that triggered the callback. For valid values, see `event_name` in each example event payload.
`event_timestamp`	string	The time the event occurred in ISO 8601 format.
`event_metadata`	EventMetadata	Metadata related to the event.

`EventMetadata` object

Field	Type	Description
`order_id`	string	The ID of the order relevant to the event.
`order_url`	string	The URL to view the order status.
`retailer_id`*	string	The ID of the retailer. To enable this field, contact your Instacart representative.
`store_location`*	string	The 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`*	boolean	Deprecated. Indicates whether the order received Instacart+ membership benefits.
`is_instacartplus`*	boolean	Indicates whether the order received Instacart+ membership benefits.
`is_certified_delivery`*	boolean	Indicates whether the order requires certified delivery.
`certified_delivery_name`*	string	The name of the individual who certified the delivery.
`certified_delivery_confirmed_at`*	date-time	The time the certified delivery was confirmed.
`order_created_with_big_bulky`*	boolean	Indicates whether the order included big and bulky items at order creation.
`post_checkout_link`*	string	Delivery. The URL of the Order status page; `nil` if the Connect Order status page is not enabled.
`delivery_window`*	DeliveryWindow	Delivery. The expected time window the order will be delivered within.
`new_window`*	DeliveryWindow	The expected time window the order will be delivered or ready for pickup.
`order_items`*	Array(OrderItem)	The items included in the order.
`cancellation_reason`*	string	The person or entity that canceled the order. For a list of possible values, see Cancellation reasons and cancellation types.
`cancellation_type`*	string	Provides 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`*	string	Pickup. A link to the pickup status page that allows users to notify the retailer they have arrived at the store.
`bags_count`*	integer	The number of bags for the order.
`bag_label`*	string	A user-friendly label that helps shoppers identify the order.
`has_partner_picker_shopper`*	boolean	Indicates whether a partner shopper picked the order. To enable this field, contact your Instacart representative.
`delivery_eta`*	string	The estimated time of arrival of the order in ISO 8601 format.
`driver_eta`*	string	The estimated time of arrival of the shopper to the store location in ISO 8601 format.
`coordinates`*	Coordinates	The coordinates.
`rating_value`*	string	The star rating value for the completed order.
`highlights`*	string	The highlights for the completed order.
`thank_you_note`*	string	The completion message for the order feedback.
`pos_payment_method`*	string	The payment method used at the point of sale (POS).

`DeliveryWindow` object

Field	Type	Description
`starts_at`	string	The time the delivery or pickup window begins in ISO 8601 format.
`ends_at`	string	The time the delivery or pickup window ends in ISO 8601 format.

`OrderItem` object

Field	Type	Description
`line_num`	string	The item's line number in the order.
`qty`	float	The quantity of the item provided to the customer. In other words, the quantity that the customer actually received. Matches value of `qty_fulfilled`.
`qty_unit`	string	The unit of measurement for the `qty` of the item, either `each` or `lb`. Matches value of `qty_fulfilled_unit`.
`qty_fulfilled`*	float	The 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`*	string	The unit of measurement for the `qty_fulfilled` of the item, either `each` or `lb`. Matches value of `qty_unit`.
`qty_requested`*	float	The quantity of the item requested by the customer.
`qty_requested_unit`*	string	The unit of measurement for the `qty_requested` of the item, either `each` or `lb`.
`replaced`	boolean	Indicates whether the item was replaced.
`refunded`	boolean	Indicates whether the item was refunded.
`item_upc`*	string	The 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`*	string	The 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`*	string	The 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`*	string	The 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`*	string	The universal product code (UPC) of the item requested by the customer.
`requested_item_rrc`*	string	The retailer reference code (RRC) of the item requested by the customer.
`scan_code`*	string	The scan code of the item.
`substitution_status`*	string	The customer's approval status of the substitution. One of `PENDING`, `APPROVED`, or `REJECTED`.
`shopper_provided_item_name`*	string	The item name provided by shoppers for items that they added.
`shopper_provided_item_price`*	Shopper_provided_item_price	The item price provided by shoppers for items that they added.

`Shopper_provided_item_price` object

Field	Type	Description
`amount`	float	The amount of a specified currency.
`currency`	string	The currency type in ISO 4217 format. For example: USD.

`Coordinates` object

Field	Type	Description
`latitude`	number	The latitude.
`longitude`	number	The longitude.

Cancellation reasons and cancellation types

The following table describes the valid cancellation_reason values:

Cancellation Reason	Description
`customer_driven`	The customer triggered the cancellation.
`instacart_driven`	Instacart triggered the cancellation.
`retailer_driven`	The retailer triggered the cancellation.
`shopper_driven`	The shopper triggered the cancellation.
`unbatchable`	The Instacart batch system triggered the cancellation.
`other`	The cancellation was triggered by another source.

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

Cancellation Reason	Cancellation Type	Description
`customer_driven`	`duplicate order`	The customer reported the order as a duplicate order.
`customer_driven`	`customer app navigation issue`	The customer reported an app navigation issue.
`customer_driven`	`customer requested since order is early`	The customer requested the cancellation because the order would be early.
`customer_driven`	`customer requested since order is late`	The customer requested the cancellation because the order would be late.
`customer_driven`	`customer mia`	The shopper reported that the customer is unavailable.
`customer_driven`	`incorrect customer information (phone/address)`	The customer requested the cancellation because of incorrect information, such as the incorrect phone number or address.
`customer_driven`	`customer requested to cancel`	The customer requested the cancellation.
`customer_driven`	`cancelled by customer`	The customer canceled the order.
`instacart_driven`	`fraudulent customer`	Instacart canceled the fraudulent customer’s order.
`instacart_driven`	`manual_fraud`	Instacart canceled the fraudulent order.
`instacart_driven`	`missing charge log for delivery`	Instacart canceled the order because of the missing charge log for delivery.
`instacart_driven`	`system error`	Instacart canceled the order because of a system error.
`retailer_driven`	`card decline on reauth`	The order was canceled because the payment card was declined.
`retailer_driven`	`shopper initiated out of stock`	The shopper canceled the order because items were out of stock.
`retailer_driven`	`fulfillment initiated out of stock`	The retailer canceled the order because items were out of stock.
`retailer_driven`	`single item order out of stock`	The retailer canceled the single item order because the item was out of stock.
`retailer_driven`	`too many out of stock items`	The retailer canceled the order because many of the items were out of stock.
`retailer_driven`	`store early closure`	The retailer canceled the order because of early store closure.
`retailer_driven`	`cancelled by retailer`	The retailer canceled the order.
`shopper_driven`	`shopper unable to complete order`	The shopper was unable to complete the order.
`shopper_driven`	`shopper could not find address`	The shopper was unable to find the address.
`unbatchable`	`unable to reschedule unbatchable`	Instacart canceled the order because the batched order could not be rescheduled.
`unbatchable`	`unable to reschedule as no option found`	Instacart canceled the order because the order could not be rescheduled.
`unbatchable`	`unbatchable`	Instacart canceled the order because the order could not be batched.
`other`	`other`	The order was canceled for other reasons.
`other`	`Instacart Connect order with all items refunded`	Instacart Connect canceled the order and refunded all items.
`other`	`OnLine Pay Failure`	The online payment failed.
`other`	`mass cancellation`	The retailer canceled all store orders due to a store issue.
`other`	`unknown`	The order was canceled for unknown reasons.
`other`	`none`	The 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.

Callbacks by fulfillment workflow type​

Callback descriptions​

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​

Object descriptions​

Order Callback object​

EventMetadata object​

DeliveryWindow object​

OrderItem object​

Shopper_provided_item_price object​

Coordinates object​

Cancellation reasons and cancellation types​

Callback errors and retries​

Callbacks by fulfillment workflow type

Callback descriptions

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

Object descriptions

`Order Callback` object

`EventMetadata` object

`DeliveryWindow` object

`OrderItem` object

`Shopper_provided_item_price` object

`Coordinates` object

Cancellation reasons and cancellation types

Callback errors and retries