Event callbacks

The Connect platform can send callbacks (also known as webhooks) to your retailer site when an order changes status. Work with your Instacart Connect representative to enable the callbacks that make sense for your fulfillment workflows. To receive callbacks, you need to create webhooks that include an endpoint for OAuth 2.0 authentication. For more information, see Authentication for callbacks. The order in which event callbacks are sent or received is not guaranteed. For more information, see Callback errors and retries.

info

In some cases, you might receive the same callback status multiple times for the same order. This can occur when an order transitions back to a previous status, which then causes some of the steps in the workflow to be repeated.

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

The following example callbacks show the JSON payload for each event.

For delivery orders, the store_location field might not be returned until after the picking callback event occurs.

Optionally, you can add the retailer_id field to all your callbacks. To enable this option, contact your Instacart representative to update your site configuration.

Brand new

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

{
  "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",
    "store_location": "WEST-23243",
    "is_express": true,
    "is_instacartplus": true,
    "is_certified_delivery": true,
    "order_created_with_big_bulky": true,
    "delivery_window": {
      "starts_at": "2020-07-07T17:00:00Z",
      "ends_at": "2020-07-07T18:00:00Z"
    }
  }
}

Acknowledged

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

{
  "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",
    "store_location": "WEST-23243",
    "is_express": true,
    "is_instacartplus": true
  }
}

Picking

This event occurs when a shopper begins fulfilling an order.

{
  "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 a 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",
    "store_location": "WEST-23243",
    "is_express": true,
    "is_instacartplus": true,
    "order_items": [
      {
        "line_num": "1",
        "qty": 1.0,
        "qty_unit": "each",
        "qty_fulfilled": 1.0,
        "qty_fulfilled_unit": "each",
        "qty_requested": 1.0,
        "qty_requested_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",
        "substitution_status": ""
      },
      {
        "line_num": "2",
        "qty": 0.92,
        "qty_unit": "lb",
        "qty_fulfilled": 0.92,
        "qty_fulfilled_unit": "lb",
        "qty_requested": 0.84,
        "qty_requested_unit": "lb",
        "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",
        "substitution_status": ""
      }
    ]
  }
}

Order item refund

This event occurs when a 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",
    "store_location": "WEST-23243",
    "is_express": true,
    "is_instacartplus": true,
    "order_items": [
      {
        "line_num": "1",
        "qty": 1.0,
        "qty_unit": "each",
        "qty_fulfilled": 1.0,
        "qty_fulfilled_unit": "each",
        "qty_requested": 1.0,
        "qty_requested_unit": "each",
        "replaced": false,
        "refunded": false,
        "item_upc": "036000291457",
        "scan_code": "8743528",
        "substitution_status": ""
      },
      {
        "line_num": "2",
        "qty": 0.92,
        "qty_unit": "lb",
        "qty_fulfilled": 0.92,
        "qty_fulfilled_unit": "lb",
        "qty_requested": 0.84,
        "qty_requested_unit": "lb",
        "replaced": false,
        "refunded": true,
        "item_upc": "036000291457",
        "item_rrc": "329439334443",
        "scan_code": "2387549",
        "substitution_status": ""
      }
    ]
  }
}

Checkout

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

{
  "event_id": 1201895966044343904,
  "event_name": "fulfillment.checkout",
  "event_timestamp": "2020-07-07T16:35:22Z",
  "event_metadata": {
    "order_id": "b7fab7ae-11fc-4453-98e1-a2f5421a2b81",
    "post_checkout_link": "<post_checkout_link>",
    "order_url": "retailer.com/xyz",
    "store_location": "WEST-23243",
    "order_items": [
      {
        "line_num": "1",
        "qty": 1.0,
        "qty_unit": "each",
        "qty_fulfilled": 1.0,
        "qty_fulfilled_unit": "each",
        "qty_requested": 1.0,
        "qty_requested_unit": "each",
        "replaced": false,
        "refunded": false,
        "item_upc": "036000291457",
        "item_rrc": "329439334443",
        "delivered_item_upc": "036000291457",
        "delivered_item_rrc": "329439334443",
        "requested_item_upc": "036000291457",
        "requested_item_rrc": "329439334443",
        "scan_code": "8743528",
        "substitution_status": ""
      },
      {
        "line_num": "2",
        "qty": 0.92,
        "qty_unit": "lb",
        "qty_fulfilled": 0.92,
        "qty_fulfilled_unit": "lb",
        "qty_requested": 0.84,
        "qty_requested_unit": "lb",
        "replaced": true,
        "refunded": false,
        "item_upc": "432000291667",
        "item_rrc": "252439332211",
        "delivered_item_upc": "432000291667",
        "delivered_item_rrc": "252439332211",
        "requested_item_upc": "432000291667",
        "requested_item_rrc": "252439332211",
        "scan_code": "2387549",
        "substitution_status": ""
      }
    ],
    "delivery_window": {
      "starts_at": "2020-07-07T17:00:00Z",
      "ends_at": "2020-07-07T18:00:00Z"
    },
    "is_express": true,
    "is_instacartplus": true
  }
}

Delivering

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

{
  "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": [
      {
        "line_num": "1",
        "qty": 1.0,
        "qty_unit": "each",
        "qty_fulfilled": 1.0,
        "qty_fulfilled_unit": "each",
        "qty_requested": 1.0,
        "qty_requested_unit": "each",
        "replaced": false,
        "refunded": false,
        "item_upc": "036000291457",
        "item_rrc": "329439334443",
        "scan_code": "8743528",
        "substitution_status": ""
      },
      {
        "line_num": "2",
        "qty": 0.92,
        "qty_unit": "lb",
        "qty_fulfilled": 0.92,
        "qty_fulfilled_unit": "lb",
        "qty_requested": 0.84,
        "qty_requested_unit": "lb",
        "replaced": true,
        "refunded": false,
        "item_upc": "036000291457",
        "item_rrc": "329439334443",
        "scan_code": "2387549",
        "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"
  }
}

Order location

This event occurs while the order is in the delivering status and the Order location callback frequency parameter is set in the retailer's Connect client configuration. The Order location callback frequency parameter specifies how often to send this event callback. The event updates the shopper's location at the specified interval until the order changes status. To set or change the interval, contact your Instacart representative.

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

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

Customer missing

This event occurs when a 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",
    "store_location": "WEST-23243"
  }
}

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 the delivery workflow, this callback is sent only when the shopper who picks the order is different from the shopper who delivers the order.

{
  "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",
    "store_location": "WEST-23243",
    "is_express": true,
    "is_instacartplus": true,
    "order_items": [
      {
        "line_num": "1",
        "qty": 1.0,
        "qty_unit": "each",
        "qty_fulfilled": 1.0,
        "qty_fulfilled_unit": "each",
        "qty_requested": 1.0,
        "qty_requested_unit": "each",
        "replaced": false,
        "refunded": false,
        "item_upc": "036000291457",
        "item_rrc": "329439334443",
        "scan_code": "8743528",
        "substitution_status": ""
      },
      {
        "line_num": "2",
        "qty": 0.92,
        "qty_unit": "lb",
        "qty_fulfilled": 0.92,
        "qty_fulfilled_unit": "lb",
        "qty_requested": 0.84,
        "qty_requested_unit": "lb",
        "replaced": true,
        "refunded": false,
        "item_upc": "036000291457",
        "item_rrc": "329439334443",
        "scan_code": "2387549",
        "substitution_status": ""
      }
    ],
    "pickup_link": "retailer.com/xyz",
    "bags_count": 3
  }
}

Customer acknowledged

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

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

{
  "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 was unable to find the customer.

{
  "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 was available. The message to the customer explains that the curbside pickup has transitioned to an in-store pickup.

{
  "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 virtual Geofence for the store. The message to the customer contains any additional pickup instructions.

{
  "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 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",
      "store_location": "WEST-23243"
    }
  }
}

Delivered

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

{
  "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",
    "store_location": "WEST-23243",
    "is_express": true,
    "is_instacartplus": true,
    "is_certified_delivery": true,
    "order_items": [
      {
        "line_num": "1",
        "qty": 1.0,
        "qty_unit": "each",
        "qty_fulfilled": 1.0,
        "qty_fulfilled_unit": "each",
        "qty_requested": 1.0,
        "qty_requested_unit": "each",
        "replaced": false,
        "refunded": false,
        "item_upc": "036000291457",
        "item_rrc": "329439334443",
        "scan_code": "8743528",
        "substitution_status": ""
      },
      {
        "line_num": "2",
        "qty": 0.92,
        "qty_unit": "lb",
        "qty_fulfilled": 0.92,
        "qty_fulfilled_unit": "lb",
        "qty_requested": 0.84,
        "qty_requested_unit": "lb",
        "replaced": true,
        "refunded": false,
        "item_upc": "036000291457",
        "item_rrc": "329439334443",
        "scan_code": "2387549",
        "substitution_status": ""
      },
      {
        "line_num": "2",
        "qty": 0.92,
        "qty_unit": "lb",
        "qty_fulfilled": 0.92,
        "qty_fulfilled_unit": "lb",
        "qty_requested": 0.84,
        "qty_requested_unit": "lb",
        "replaced": false,
        "refunded": false,
        "item_upc": "",
        "item_rrc": "",
        "scan_code": "2387549",
        "substitution_status": "",
        "shopper_provided_item_name": "Apples",
        "shopper_provided_item_price": {
          "amount": 6.99,
          "currency": "USD"
        }
      }
    ],
    "bags_count": 3,
    "pos_payment_method": "UNSPECIFIED",
    "has_partner_picker_shopper": true
  }
}

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",
    "store_location": "WEST-23243",
    "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. The cancellation_reason field identifies who or what triggered the cancellation. The cancellation_type describes the cancellation. You can use this information in customer notifications. For more information about the cancellation reasons and cancellation types, see Cancellation reasons and cancellation types.

{
  "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",
    "store_location": "WEST-23243",
    "cancellation_reason": "customer_driven",
    "cancellation_type": "duplicate order",
    "pos_payment_method": "UNSPECIFIED"
  }
}

Tip adjustment

This event occurs when the tip for an order has successfully been updated after delivery 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",
    "store_location": "WEST-23243",
    "is_express": true,
    "is_instacartplus": true,
    "order_items": [
      {
        "line_num": "1",
        "qty": 1.0,
        "qty_unit": "each",
        "qty_fulfilled": 1.0,
        "qty_fulfilled_unit": "each",
        "qty_requested": 1.0,
        "qty_requested_unit": "each",
        "replaced": false,
        "refunded": false,
        "item_upc": "036000291457",
        "item_rrc": "329439334443",
        "scan_code": "8743528",
        "substitution_status": ""
      },
      {
        "line_num": "2",
        "qty": 0.92,
        "qty_unit": "lb",
        "qty_fulfilled": 0.92,
        "qty_fulfilled_unit": "lb",
        "qty_requested": 0.84,
        "qty_requested_unit": "lb",
        "replaced": true,
        "refunded": false,
        "item_upc": "036000291457",
        "item_rrc": "329439334443",
        "scan_code": "2387549",
        "substitution_status": ""
      }
    ]
  }
}

At store

This event occurs when a 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",
    "store_location": "WEST-23243"
  }
}

Acknowledged for delivery

This event occurs when a last mile delivery order is acknowledged by a 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",
    "store_location": "WEST-23243"
  }
}

Bags verified

This event occurs when a 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",
    "store_location": "WEST-23243"
  }
}

Arrival at customer

This event occurs when a 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",
    "store_location": "WEST-23243"
  }
}

At store ETA

Once a last mile delivery order is acknowledged, this event is emitted every two minutes with the shopper's estimated time of arrival to the store location.

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

Rating updated

This event occurs when the order rating is created or updated through the API.

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

Rating reminder

This event occurs one hour after the order is delivered or picked up. This callback is sent when the order does not have a rating at the time the event occurs.

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

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 the `event_name` in each of the callbacks.
`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.
`store_location`*	string	The location code of the store where the order is fulfilled.
`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.
`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 link to the Connect Post Checkout app of the given order; `nil` if Connect Post Checkout app 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 reason the order was canceled, such as who or what triggered the cancellation.
`cancellation_type`*	string	The type of cancellation.
`pickup_link`*	string	Pickup. A link to the pickup status page that allows users to notify the retailer they are 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.
`qty_unit`	string	The quantity type, either `each` or `lb`.
`qty_fulfilled`	float	The fulfilled quantity of the item.
`qty_fulfilled_unit`	string	The fulfilled quantity type, either `each` or `lb`.
`qty_requested`	float	The customer requested quantity of the item.
`qty_requested_unit`	string	The customer requested quantity type, either `each` or `lb`.
`replaced`	boolean	Indicates whether the item was replaced.
`refunded`	boolean	Indicates whether the item was refunded.
`item_upc`*	string	The item's universal product code (UPC).
`item_rrc`*	string	The item's retailer reference code (RRC).
`delivered_item_upc`*	string	The delivered item's universal product code (UPC).
`delivered_item_rrc`*	string	The delivered item's retailer reference code (RRC).
`requested_item_upc`*	string	The requested item's universal product code (UPC).
`requested_item_rrc`*	string	The requested item's retailer reference code (RRC).
`scan_code`*	string	The scan code of the item.
`substitution_status`*	string	The user'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 list of valid cancellation reasons:

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.

The following table describes the list of valid cancellation types and identifies the cancellation reason for each cancellation type:

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 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.

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​