This documentation is in beta, and might contain errors. Contact us at integration@instabee.com with any questions.

Instabee API

Home Delivery Events

V2 webhooks can be configured in the Instabee merchant portal at partner.instabee.com.

Authentication

V2 webhooks support:

  • HTTP Basic Auth - provide username and password in the portal
  • OAuth2 - configure a token endpoint and credentials in the portal

V2 Request Headers

Every V2 callback includes these custom headers:

HeaderDescription
Budbee-EventEvent type (e.g. DELIVERED_TO_CONSUMER)
Budbee-Event-IDUnique event identifier
TimestampEvent time in ISO 8601 UTC

V2 Events

EventDescription
PARCEL_CREATEDNew parcel registered
SORTED_AT_TERMINALParcel sorted at terminal
PARCEL_RECALLEDParcel recalled by merchant
HOME_DELIVERY_CHANGEDHome delivery details updated
DELIVERED_TO_CONSUMERSuccessfully delivered to consumer
DELIVERY_FAILEDDelivery attempt failed
DELIVERY_CANCELLEDDelivery cancelled
RETURN_BOOKED_HOMEHome pickup return booked
RETURN_HOME_PICKED_UPHome pickup return collected
RETURN_HOME_PICK_UP_FAILEDHome pickup return failed
RETURN_HOME_PICK_UP_CANCELLEDHome pickup return cancelled
RETURNED_TO_MERCHANTParcel returned to merchant
LOCKER_CHANGEDLocker assignment changed
DELIVERED_TO_LOCKERParcel placed in locker
CONSUMER_PICKED_UP_FROM_LOCKERConsumer collected from locker
INJECTED_IN_LOCKERParcel injected directly into locker
CHANGED_TO_LOCKER_DELIVERYDelivery type changed to locker
CHANGED_TO_HOME_DELIVERYDelivery type changed to home
RETURN_BOOKED_LOCKERLocker return booked
RETURN_LOCKER_PICK_UP_FAILEDLocker return pickup failed
DELIVERY_VEHICLE_LOADEDParcel loaded onto delivery vehicle

V2 Event Payload

1{
2  "event": "PARCEL_RECALLED",
3  "eventData": {
4    "tmsId": "93f98546-3c92-4dd1-9893-44563cb740ff",
5    "reason": "REQUESTED_BY_BUDBEE",
6    "shipmentId": "INSTABEE-1046",
7    "cartId": "INSTABEE-1046",
8    "responsible": "BUDBEE",
9    "packageId": "TEST1000002318411",
10    "budbeeOrderToken": "zke3vj1rz",
11    "timestamp": "2026-09-09T10:40:47.772Z"
12  }
13}

V2 Payload Parameters

paramTypeDescription
eventstringEvent type (see V2 Events table)
eventDataobjectEvent-specific data (fields vary by event type)
eventData.tmsIdstringBudbee's internal shipment identifier
eventData.reasonstringReason for the event, when applicable
eventData.shipmentIdstringYour shipment identifier
eventData.cartIdstringYour cart identifier
eventData.responsiblestringWho triggered the event
eventData.packageIdstringPackage identifier
eventData.budbeeOrderTokenstringBudbee order token for the shipment
eventData.timestampstringEvent time in ISO 8601 UTC

V2 Data Types

FieldValuesDescription
responsibleBUDBEE, CONSUMER, MERCHANTWho triggered the event
timestampISO 8601 UTCDate/time format used in V2 events (unlike the API which uses epoch ms)

Command Palette

Search for a command to run...