Events

Karla generates events throughout the customer journey, from order creation to delivery completion. Understanding the event hierarchy and structure is crucial for building integrations, setting up webhooks, and creating responsive campaigns.

Third-party tools

We can integrate with any third-party tool that allows custom event creation via their API. If the tool allows passing a custom attributes object, such object will have the format defined here.

Contact us for more information about how to integrate triggers with any tool you use.

Event Hierarchy

Events in Karla follow a four-level hierarchy:

1. Source

The top-level entity that generates the event:

• shipments - Package delivery events
• claims - Customer service request events
• campaigns - Marketing interaction events
• customers - Customer behavior events
• system - System operation events

2. Ref

The event reference. Format will be different depending on its source:

Shipments: {source}/{phase}/{event_name}

• Example: shipments/delivered/SUCCESSFULLY_DELIVERED

Claims: {source}/{action}

• Example: claims/created

info

When subscribing to events via a webhook's enabled_events field, you can use the phase-level ref, like shipments/delivered to receive all events belonging to the delivered shipment phase or claims to get all relevant claim actions.

3. Event Name

The most granular event identifier (e.g., SUCCESSFULLY_DELIVERED, OUT_FOR_DELIVERY)

4. Event Group

Klaviyo-friendly groupings for easier campaign management (e.g., shipment_delivered, shipment_in_transit)

Shipment Events

Shipment events are generated by fulfilled shipments only (those with tracking numbers). Draft shipments only generate pre-transit events.

Draft vs Fulfilled Events

• Draft shipments: Only generate ORDER_CREATED and ORDER_CANCELLED events (no tracking number yet)
• Fulfilled shipments: Generate all other tracking events

See Shipment States Explained for more details.

Event Structure

Ref Pattern: shipments/{phase}/{event_name}

By Phase

Order Created (order_created)

Events when order is placed but before carrier pickup:

Event Name	Ref	Event Group
ORDER_CREATED	shipments/order_created/ORDER_CREATED	shipment_pre_transit
ORDER_IN_PROCESSING	shipments/order_created/ORDER_IN_PROCESSING	shipment_pre_transit

Order Processed (order_processed)

Events when package is prepared for shipping (23 events total):

Event Name	Ref	Event Group
ORDER_PROCESSED	shipments/order_processed/ORDER_PROCESSED	shipment_pre_transit
PARCEL_DATA_SUBMITTED_TO_CARRIER	shipments/order_processed/PARCEL_DATA_SUBMITTED_TO_CARRIER	shipment_pre_transit
PICKUP_SUCCESSFUL	shipments/order_processed/PICKUP_SUCCESSFUL	shipment_pre_transit
PARCEL_DISPATCHED	shipments/order_processed/PARCEL_DISPATCHED	shipment_pre_transit

See all order_processed events (23 total)

Event Name	Ref	Event Group
CARRIER_UNKNOWN	shipments/order_processed/CARRIER_UNKNOWN	shipment_pre_transit
DISPATCHED_FROM_FORWARDING_DEPOT	shipments/order_processed/DISPATCHED_FROM_FORWARDING_DEPOT	shipment_pre_transit
ERROR_IN_PARCEL_DATA_SUBMISSION	shipments/order_processed/ERROR_IN_PARCEL_DATA_SUBMISSION	shipment_pre_transit
ORDER_PROCESSED	shipments/order_processed/ORDER_PROCESSED	shipment_pre_transit
PARCEL_COLLECTED_FROM_DROP_OFF_LOCATION	shipments/order_processed/PARCEL_COLLECTED_FROM_DROP_OFF_LOCATION	shipment_pre_transit
PARCEL_DATA_SUBMISSION_DELAYED	shipments/order_processed/PARCEL_DATA_SUBMISSION_DELAYED	shipment_pre_transit
PARCEL_DATA_SUBMITTED_TO_CARRIER	shipments/order_processed/PARCEL_DATA_SUBMITTED_TO_CARRIER	shipment_pre_transit
PARCEL_DISPATCHED	shipments/order_processed/PARCEL_DISPATCHED	shipment_pre_transit
PARCEL_DROPPED_OFF_AT_PARCEL_LOCKER	shipments/order_processed/PARCEL_DROPPED_OFF_AT_PARCEL_LOCKER	shipment_pre_transit
PARCEL_DROPPED_OFF_AT_POST_OFFICE	shipments/order_processed/PARCEL_DROPPED_OFF_AT_POST_OFFICE	shipment_pre_transit
PARCEL_DROPPED_OFF_IN_PARCEL_SHOP	shipments/order_processed/PARCEL_DROPPED_OFF_IN_PARCEL_SHOP	shipment_pre_transit
PARCEL_DROPPED_OFF_OVER_THE_COUNTER	shipments/order_processed/PARCEL_DROPPED_OFF_OVER_THE_COUNTER	shipment_pre_transit
PARCEL_DROPPED_OFF_WITH_CARRIER	shipments/order_processed/PARCEL_DROPPED_OFF_WITH_CARRIER	shipment_pre_transit
PARCEL_READY_FOR_PICKUP	shipments/order_processed/PARCEL_READY_FOR_PICKUP	shipment_pre_transit
PICKUP_ATTEMPTED	shipments/order_processed/PICKUP_ATTEMPTED	shipment_pre_transit
PICKUP_DELAYED	shipments/order_processed/PICKUP_DELAYED	shipment_pre_transit
PICKUP_FAILED	shipments/order_processed/PICKUP_FAILED	shipment_pre_transit
PICKUP_SUCCESSFUL	shipments/order_processed/PICKUP_SUCCESSFUL	shipment_pre_transit
PROCEEDING_TO_CARRIER_FACILITY	shipments/order_processed/PROCEEDING_TO_CARRIER_FACILITY	shipment_pre_transit
RECEIPT_AT_FORWARDING_DEPOT	shipments/order_processed/RECEIPT_AT_FORWARDING_DEPOT	shipment_pre_transit
SHIPMENT_INFO_SENT_TO_LAST_MILE_SERVICE_PROVIDER	shipments/order_processed/SHIPMENT_INFO_SENT_TO_LAST_MILE_SERVICE_PROVIDER	shipment_pre_transit
SHIPMENT_NEVER_ARRIVED	shipments/order_processed/SHIPMENT_NEVER_ARRIVED	shipment_pre_transit

In Transit (in_transit)

Events when package is moving through carrier network (50+ events total):

Event Name	Ref	Event Group
DISPATCHED_FROM_SORTING_CENTER	shipments/in_transit/DISPATCHED_FROM_SORTING_CENTER	shipment_in_transit
ARRIVAL_AT_FINAL_DELIVERY_CENTER	shipments/in_transit/ARRIVAL_AT_FINAL_DELIVERY_CENTER	shipment_in_transit
SHIPMENT_EN_ROUTE	shipments/in_transit/SHIPMENT_EN_ROUTE	shipment_in_transit
DELAY_EXPECTED	shipments/in_transit/DELAY_EXPECTED	shipment_carrier_delay
SHIPMENT_DAMAGED	shipments/in_transit/SHIPMENT_DAMAGED	shipment_damaged

See all in_transit events (50+ total)

Event Name	Ref	Event Group
ACCEPTED_BY_DESTINATION_OFFICE	shipments/in_transit/ACCEPTED_BY_DESTINATION_OFFICE	shipment_in_transit
ACCEPTED_BY_ORIGIN_OFFICE	shipments/in_transit/ACCEPTED_BY_ORIGIN_OFFICE	shipment_in_transit
ARRIVAL_AT_FINAL_DELIVERY_CENTER	shipments/in_transit/ARRIVAL_AT_FINAL_DELIVERY_CENTER	shipment_in_transit
ARRIVAL_AT_TRANSPORT_HUB	shipments/in_transit/ARRIVAL_AT_TRANSPORT_HUB	shipment_in_transit
ARRIVAL_IN_DESTINATION_COUNTRY	shipments/in_transit/ARRIVAL_IN_DESTINATION_COUNTRY	shipment_in_transit
ARRIVED_AT_SORTING_CENTER	shipments/in_transit/ARRIVED_AT_SORTING_CENTER	shipment_in_transit
ASSIGNED_TO_TRANSPORT	shipments/in_transit/ASSIGNED_TO_TRANSPORT	shipment_in_transit
AT_SORTING_CENTER	shipments/in_transit/AT_SORTING_CENTER	shipment_in_transit
AT_TRANSPORT_HUB	shipments/in_transit/AT_TRANSPORT_HUB	shipment_in_transit
COMPLETION_OF_CUSTOMS_PROCESSING	shipments/in_transit/COMPLETION_OF_CUSTOMS_PROCESSING	shipment_in_transit
COMPLETION_OF_EXPORT_PROCESSING	shipments/in_transit/COMPLETION_OF_EXPORT_PROCESSING	shipment_in_transit
CUSTOMS_PROCESSING	shipments/in_transit/CUSTOMS_PROCESSING	shipment_in_transit
DELAY_EXPECTED	shipments/in_transit/DELAY_EXPECTED	shipment_carrier_delay
DELAY_IN_TRANSPORT_MISROUTED_SHIPMENT	shipments/in_transit/DELAY_IN_TRANSPORT_MISROUTED_SHIPMENT	shipment_carrier_delay
DELAY_IN_TRANSPORT_OFFLOADED_SHIPMENT	shipments/in_transit/DELAY_IN_TRANSPORT_OFFLOADED_SHIPMENT	shipment_carrier_delay
DELAY_IN_TRANSPORT	shipments/in_transit/DELAY_IN_TRANSPORT	shipment_carrier_delay
DEPARTURE_FROM_TRANSPORT_HUB	shipments/in_transit/DEPARTURE_FROM_TRANSPORT_HUB	shipment_in_transit
DISPATCHED_FROM_DELIVERY_CENTER	shipments/in_transit/DISPATCHED_FROM_DELIVERY_CENTER	shipment_in_transit
DISPATCHED_FROM_SORTING_CENTER	shipments/in_transit/DISPATCHED_FROM_SORTING_CENTER	shipment_in_transit
DISPATCHING_STARTED_AT_PROCESSING_CENTER	shipments/in_transit/DISPATCHING_STARTED_AT_PROCESSING_CENTER	shipment_in_transit
ENCODING_COMPLETED_AT_PROCESSING_CENTER	shipments/in_transit/ENCODING_COMPLETED_AT_PROCESSING_CENTER	shipment_in_transit
ENCODING_ERROR_IN_PROCESSING_AT_SORTING_CENTER	shipments/in_transit/ENCODING_ERROR_IN_PROCESSING_AT_SORTING_CENTER	shipment_in_transit
ENCODING_STARTED_AT_PROCESSING_CENTER	shipments/in_transit/ENCODING_STARTED_AT_PROCESSING_CENTER	shipment_in_transit
ERROR_IN_PROCESSING_AT_SORTING_CENTER	shipments/in_transit/ERROR_IN_PROCESSING_AT_SORTING_CENTER	shipment_in_transit
EXPORT_PROCESSING	shipments/in_transit/EXPORT_PROCESSING	shipment_in_transit
FAILED_TO_HAND_OVER_TO_DELIVERY_PARTNER	shipments/in_transit/FAILED_TO_HAND_OVER_TO_DELIVERY_PARTNER	shipment_in_transit
HANDED_OVER_TO_DELIVERY_PARTNER	shipments/in_transit/HANDED_OVER_TO_DELIVERY_PARTNER	shipment_in_transit
HELD_AT_CUSTOMS_FOR_ADDITIONAL_PAYMENT	shipments/in_transit/HELD_AT_CUSTOMS_FOR_ADDITIONAL_PAYMENT	shipment_in_transit
HELD_AT_CUSTOMS_FOR_CLARIFICATIONS	shipments/in_transit/HELD_AT_CUSTOMS_FOR_CLARIFICATIONS	shipment_in_transit
HELD_AT_CUSTOMS	shipments/in_transit/HELD_AT_CUSTOMS	shipment_in_transit
HELD_AT_EXPORT_PROCESSING	shipments/in_transit/HELD_AT_EXPORT_PROCESSING	shipment_in_transit
INBOUND_FLIGHT_ARRIVED	shipments/in_transit/INBOUND_FLIGHT_ARRIVED	shipment_in_transit
INBOUND_TRUCK_ARRIVED	shipments/in_transit/INBOUND_TRUCK_ARRIVED	shipment_in_transit
ISSUES_IN_PROCESSING_BY_CUSTOMS_AUTHORITIES	shipments/in_transit/ISSUES_IN_PROCESSING_BY_CUSTOMS_AUTHORITIES	shipment_in_transit
MORE_INFO_ON_CARRIER_WEBSITE	shipments/in_transit/MORE_INFO_ON_CARRIER_WEBSITE	shipment_in_transit
OUTBOUND_FLIGHT_DEPARTED	shipments/in_transit/OUTBOUND_FLIGHT_DEPARTED	shipment_in_transit
OUTBOUND_TRUCK_DEPARTED	shipments/in_transit/OUTBOUND_TRUCK_DEPARTED	shipment_in_transit
PROCESSED_AT_DELIVERY_CENTER	shipments/in_transit/PROCESSED_AT_DELIVERY_CENTER	shipment_in_transit
PROCESSING_AT_TRANSPORT_HUB	shipments/in_transit/PROCESSING_AT_TRANSPORT_HUB	shipment_in_transit
SCANNED_AT_PROCESSING_CENTER	shipments/in_transit/SCANNED_AT_PROCESSING_CENTER	shipment_in_transit
SHIPMENT_AT_FINAL_DELIVERY_CENTER	shipments/in_transit/SHIPMENT_AT_FINAL_DELIVERY_CENTER	shipment_in_transit
SHIPMENT_DAMAGED	shipments/in_transit/SHIPMENT_DAMAGED	shipment_damaged
SHIPMENT_DELAYED_DUE_TO_CUSTOMER_REQUEST	shipments/in_transit/SHIPMENT_DELAYED_DUE_TO_CUSTOMER_REQUEST	shipment_delayed_due_to_customer_request
SHIPMENT_EN_ROUTE	shipments/in_transit/SHIPMENT_EN_ROUTE	shipment_in_transit
SHIPMENT_MISROUTED	shipments/in_transit/SHIPMENT_MISROUTED	shipment_in_transit
SORTING_COMPLETED_AT_PROCESSING_CENTER	shipments/in_transit/SORTING_COMPLETED_AT_PROCESSING_CENTER	shipment_in_transit
SORTING_ERROR_IN_PROCESSING_AT_SORTING_CENTER	shipments/in_transit/SORTING_ERROR_IN_PROCESSING_AT_SORTING_CENTER	shipment_in_transit
SORTING_STARTED_AT_PROCESSING_CENTER	shipments/in_transit/SORTING_STARTED_AT_PROCESSING_CENTER	shipment_in_transit
START_OF_CUSTOMS_PROCESSING	shipments/in_transit/START_OF_CUSTOMS_PROCESSING	shipment_in_transit
START_OF_EXPORT_PROCESSING	shipments/in_transit/START_OF_EXPORT_PROCESSING	shipment_in_transit
TRANSPORT_ARRIVED	shipments/in_transit/TRANSPORT_ARRIVED	shipment_in_transit
TRANSPORT_DEPARTED	shipments/in_transit/TRANSPORT_DEPARTED	shipment_in_transit

In Delivery (in_delivery)

Events when package is out for delivery (19 events total):

Event Name	Ref	Event Group
OUT_FOR_DELIVERY	shipments/in_delivery/OUT_FOR_DELIVERY	shipment_out_for_delivery
IN_DELIVERY	shipments/in_delivery/IN_DELIVERY	shipment_out_for_delivery
DELIVERY_ATTEMPTED	shipments/in_delivery/DELIVERY_ATTEMPTED	shipment_delivery_failed

See all in_delivery events (19 total)

Event Name	Ref	Event Group
ATTEMPTED_DELIVERY_UNDELIVERABLE	shipments/in_delivery/ATTEMPTED_DELIVERY_UNDELIVERABLE	shipment_delivery_failed
DELIVERY_ATTEMPTED_ADDRESS_COULD_NOT_BE_FOUND	shipments/in_delivery/DELIVERY_ATTEMPTED_ADDRESS_COULD_NOT_BE_FOUND	shipment_delivery_failed_address_issue
DELIVERY_ATTEMPTED_ADDRESSEE_MOVED	shipments/in_delivery/DELIVERY_ATTEMPTED_ADDRESSEE_MOVED	shipment_delivery_failed_address_issue
DELIVERY_ATTEMPTED_ADDRESSEE_NOT_KNOWN_AT_ADDRESS	shipments/in_delivery/DELIVERY_ATTEMPTED_ADDRESSEE_NOT_KNOWN_AT_ADDRESS	shipment_delivery_failed_address_issue
DELIVERY_ATTEMPTED_CASH_ON_DELIVERY_AMOUNT_NOT_READY	shipments/in_delivery/DELIVERY_ATTEMPTED_CASH_ON_DELIVERY_AMOUNT_NOT_READY	shipment_delivery_failed
DELIVERY_ATTEMPTED_FAILED_WILL_TRY_AGAIN	shipments/in_delivery/DELIVERY_ATTEMPTED_FAILED_WILL_TRY_AGAIN	shipment_delivery_second_attempt
DELIVERY_ATTEMPTED_FORWARDING_TO_PICKUP_LOCATION	shipments/in_delivery/DELIVERY_ATTEMPTED_FORWARDING_TO_PICKUP_LOCATION	shipment_delivery_failed_forwarded_to_parcel_shop
DELIVERY_ATTEMPTED_LAST_ATTEMPT	shipments/in_delivery/DELIVERY_ATTEMPTED_LAST_ATTEMPT	shipment_delivery_failed
DELIVERY_ATTEMPTED_RECIPIENT_NOT_AT_HOME	shipments/in_delivery/DELIVERY_ATTEMPTED_RECIPIENT_NOT_AT_HOME	shipment_delivery_failed
DELIVERY_ATTEMPTED	shipments/in_delivery/DELIVERY_ATTEMPTED	shipment_delivery_failed
DELIVERY_LAPSED	shipments/in_delivery/DELIVERY_LAPSED	shipment_delivery_failed
DELIVERY_OPTION_REQUESTED_BY_RECEIVER	shipments/in_delivery/DELIVERY_OPTION_REQUESTED_BY_RECEIVER	shipment_delivery_failed
DELIVERY_SCHEDULED_IN_THE_FINAL_DELIVERY_DEPOT	shipments/in_delivery/DELIVERY_SCHEDULED_IN_THE_FINAL_DELIVERY_DEPOT	shipment_out_for_delivery
IN_DELIVERY	shipments/in_delivery/IN_DELIVERY	shipment_out_for_delivery
NO_DELIVERY_ATTEMPT_ON_ROUTE	shipments/in_delivery/NO_DELIVERY_ATTEMPT_ON_ROUTE	shipment_delivery_failed
OUT_FOR_DELIVERY	shipments/in_delivery/OUT_FOR_DELIVERY	shipment_out_for_delivery
PATCHED	shipments/in_delivery/PATCHED	shipment_out_for_delivery
SHIPMENT_ON_HOLD_IN_DELIVERY_CENTER	shipments/in_delivery/SHIPMENT_ON_HOLD_IN_DELIVERY_CENTER	shipment_out_for_delivery
SHIPMENT_ON_ITS_WAY_TO_PICKUP_LOCATION	shipments/in_delivery/SHIPMENT_ON_ITS_WAY_TO_PICKUP_LOCATION	shipment_out_for_delivery

Collect (collect)

Events when package is ready for pickup at parcel shops/lockers (6 events total):

Event Name	Ref	Event Group
ARRIVED_AT_PARCEL_LOCKER	shipments/collect/ARRIVED_AT_PARCEL_LOCKER	shipment_delivered_to_parcel_locker
ARRIVED_AT_PARCEL_SHOP	shipments/collect/ARRIVED_AT_PARCEL_SHOP	shipment_delivered_to_parcel_shop
ARRIVED_AT_POST_OFFICE	shipments/collect/ARRIVED_AT_POST_OFFICE	shipment_delivered_to_parcel_shop

See all collect events (6 total)

Event Name	Ref	Event Group
ARRIVED_AT_PARCEL_LOCKER	shipments/collect/ARRIVED_AT_PARCEL_LOCKER	shipment_delivered_to_parcel_locker
ARRIVED_AT_PARCEL_SHOP	shipments/collect/ARRIVED_AT_PARCEL_SHOP	shipment_delivered_to_parcel_shop
ARRIVED_AT_POST_OFFICE	shipments/collect/ARRIVED_AT_POST_OFFICE	shipment_delivered_to_parcel_shop
SUCCESSFULLY_DELIVERED_TO_NEIGHBOR	shipments/collect/SUCCESSFULLY_DELIVERED_TO_NEIGHBOR	shipment_delivered_to_neighbour
SUCCESSFULLY_DELIVERED_AND_LEFT_AT_LETTER_BOX	shipments/collect/SUCCESSFULLY_DELIVERED_AND_LEFT_AT_LETTER_BOX	shipment_delivered_to_letterbox
DELIVERY_ATTEMPTED_RECIPIENT_NOT_AT_HOME_CARD_LEFT	shipments/collect/DELIVERY_ATTEMPTED_RECIPIENT_NOT_AT_HOME_CARD_LEFT	shipment_delivery_failed

Delivered (delivered)

Events when package is successfully delivered (10 events total):

Event Name	Ref	Event Group
SUCCESSFULLY_DELIVERED	shipments/delivered/SUCCESSFULLY_DELIVERED	shipment_delivered
SUCCESSFULLY_COLLECTED_AT_PARCEL_LOCKER	shipments/delivered/SUCCESSFULLY_COLLECTED_AT_PARCEL_LOCKER	shipment_delivered_to_parcel_locker
SUCCESSFULLY_COLLECTED_AT_PARCEL_SHOP	shipments/delivered/SUCCESSFULLY_COLLECTED_AT_PARCEL_SHOP	shipment_delivered_to_parcel_shop

See all delivered events (10 total)

Event Name	Ref	Event Group
PARCEL_TRANSFERRED_TO_THIRD_PARTY	shipments/delivered/PARCEL_TRANSFERRED_TO_THIRD_PARTY	shipment_delivered
SUCCESSFULLY_COLLECTED_AT_PARCEL_LOCKER	shipments/delivered/SUCCESSFULLY_COLLECTED_AT_PARCEL_LOCKER	shipment_delivered_to_parcel_locker
SUCCESSFULLY_COLLECTED_AT_PARCEL_SHOP	shipments/delivered/SUCCESSFULLY_COLLECTED_AT_PARCEL_SHOP	shipment_delivered_to_parcel_shop
SUCCESSFULLY_COLLECTED_AT_POST_OFFICE	shipments/delivered/SUCCESSFULLY_COLLECTED_AT_POST_OFFICE	shipment_delivered_to_parcel_shop
SUCCESSFULLY_COLLECTED	shipments/delivered/SUCCESSFULLY_COLLECTED	shipment_picked_up
SUCCESSFULLY_DELIVERED_AND_CASH_ON_DELIVERY_COLLECTED	shipments/delivered/SUCCESSFULLY_DELIVERED_AND_CASH_ON_DELIVERY_COLLECTED	shipment_delivered
SUCCESSFULLY_DELIVERED_AND_LEFT_AT_DOOR	shipments/delivered/SUCCESSFULLY_DELIVERED_AND_LEFT_AT_DOOR	shipment_delivered
SUCCESSFULLY_DELIVERED_AND_PROOF_OF_DELIVERY_COLLECTED	shipments/delivered/SUCCESSFULLY_DELIVERED_AND_PROOF_OF_DELIVERY_COLLECTED	shipment_delivered
SUCCESSFULLY_DELIVERED	shipments/delivered/SUCCESSFULLY_DELIVERED	shipment_delivered
USER_SUCCESSFULLY_DELIVERED	shipments/delivered/USER_SUCCESSFULLY_DELIVERED	shipment_delivered

Delivery Failed (delivery_failed)

Events when delivery attempts fail (6 events total):

Event Name	Ref	Event Group
DELIVERY_ATTEMPTED_REJECTED_BY_ADDRESSEE	shipments/delivery_failed/DELIVERY_ATTEMPTED_REJECTED_BY_ADDRESSEE	shipment_refused_then_returned
SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_LOCKER_RETURNED_TO_BASE	shipments/delivery_failed/SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_LOCKER_RETURNED_TO_BASE	shipment_not_picked_up_then_returned

See all delivery_failed events (6 total)

Event Name	Ref	Event Group
DELIVERY_ATTEMPTED_REJECTED_BY_ADDRESSEE	shipments/delivery_failed/DELIVERY_ATTEMPTED_REJECTED_BY_ADDRESSEE	shipment_refused_then_returned
SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_LOCKER_RETURNED_TO_BASE	shipments/delivery_failed/SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_LOCKER_RETURNED_TO_BASE	shipment_not_picked_up_then_returned
SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_LOCKER_RETURNED_TO_ORIGIN_COUNTRY	shipments/delivery_failed/SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_LOCKER_RETURNED_TO_ORIGIN_COUNTRY	shipment_not_picked_up_then_returned
SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_SHOP_RETURNED_TO_BASE	shipments/delivery_failed/SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_SHOP_RETURNED_TO_BASE	shipment_not_picked_up_then_returned
SHIPMENT_NOT_PICKED_UP_FROM_POST_OFFICE_RETURNED_TO_BASE	shipments/delivery_failed/SHIPMENT_NOT_PICKED_UP_FROM_POST_OFFICE_RETURNED_TO_BASE	shipment_not_picked_up_then_returned
SHIPMENT_NOT_PICKED_UP_RETURNED_TO_ORIGIN_COUNTRY	shipments/delivery_failed/SHIPMENT_NOT_PICKED_UP_RETURNED_TO_ORIGIN_COUNTRY	shipment_not_picked_up_then_returned

Returned (returned)

Events when packages are returned to sender (7 events total):

Event Name	Ref	Event Group
RETURN_IN_PROGRESS	shipments/returned/RETURN_IN_PROGRESS	shipment_failed_returned
RETURN_TO_SENDER_COMPLETED	shipments/returned/RETURN_TO_SENDER_COMPLETED	shipment_failed_returned
SHIPMENT_RETURNED_TO_SENDER	shipments/returned/SHIPMENT_RETURNED_TO_SENDER	shipment_failed_returned

See all returned events (7 total)

Event Name	Ref	Event Group
RETURN_IN_PROGRESS	shipments/returned/RETURN_IN_PROGRESS	shipment_failed_returned
RETURN_TO_SENDER_COMPLETED	shipments/returned/RETURN_TO_SENDER_COMPLETED	shipment_failed_returned
RETURN_TO_SENDER_FAILED	shipments/returned/RETURN_TO_SENDER_FAILED	shipment_failed_returned
SHIPMENT_REJECTED_RETURNING_TO_SENDER	shipments/returned/SHIPMENT_REJECTED_RETURNING_TO_SENDER	shipment_failed_returned
SHIPMENT_RETURNED_TO_SENDER	shipments/returned/SHIPMENT_RETURNED_TO_SENDER	shipment_failed_returned
SHIPMENT_RETURNING_TO_SENDER	shipments/returned/SHIPMENT_RETURNING_TO_SENDER	shipment_failed_returned
SHIPMENT_SUCCESSFULLY_RETURNED_TO_SENDER	shipments/returned/SHIPMENT_SUCCESSFULLY_RETURNED_TO_SENDER	shipment_failed_returned

Return Failed (return_failed)

Events when return shipments fail (1 event total):

Event Name	Ref	Event Group
DELIVERY_FAILED_SHIPMENT_DESTROYED	shipments/return_failed/DELIVERY_FAILED_SHIPMENT_DESTROYED	shipment_failed_returned

Missing/Lost Events

These events can occur in any phase when packages go missing:

Event Name	Ref	Event Group
SHIPMENT_LOST_IN_DELIVERY	shipments/{phase}/SHIPMENT_LOST_IN_DELIVERY	shipment_lost
SHIPMENT_LOST_IN_TRANSIT	shipments/{phase}/SHIPMENT_LOST_IN_TRANSIT	shipment_lost
SHIPMENT_LOST	shipments/{phase}/SHIPMENT_LOST	shipment_lost

Claim Events

Claim events are generated when customers create or update service requests.

Shipment Event Structure

Ref Pattern: claims/{event_name}

Event Name	Ref	Description
CLAIM_CREATED	claims/created	New claim submitted by customer
CLAIM_UPDATED	claims/updated	Claim status or details changed

Event Groups

Event groups provide business-friendly names for external tools. Each group may contain multiple event names:

Shipment Event Groups

Event Group	Description	Example Event Names
shipment_pre_transit	Package prepared for shipping	ORDER_PROCESSED, PICKUP_SUCCESSFUL
shipment_in_transit	Package moving through network	DISPATCHED_FROM_SORTING_CENTER, ARRIVAL_AT_FINAL_DELIVERY_CENTER
shipment_carrier_delay	Carrier-reported delays	DELAY_EXPECTED, DELAY_IN_TRANSPORT
shipment_damaged	Package damage reported	SHIPMENT_DAMAGED
shipment_out_for_delivery	Package out for delivery	OUT_FOR_DELIVERY, IN_DELIVERY
shipment_delivered	Successful delivery	SUCCESSFULLY_DELIVERED
shipment_delivered_all_events	All delivery variations	All delivered phase events
shipment_delivered_to_neighbour	Delivered to neighbor	SUCCESSFULLY_DELIVERED_TO_NEIGHBOR
shipment_delivered_to_letterbox	Delivered to letterbox	SUCCESSFULLY_DELIVERED_AND_LEFT_AT_LETTER_BOX
shipment_delivered_to_parcel_shop	Delivered to pickup point	ARRIVED_AT_PARCEL_SHOP, SUCCESSFULLY_COLLECTED_AT_PARCEL_SHOP
shipment_delivered_to_parcel_locker	Delivered to parcel locker	ARRIVED_AT_PARCEL_LOCKER, SUCCESSFULLY_COLLECTED_AT_PARCEL_LOCKER
shipment_delivery_failed	Delivery attempt failed	DELIVERY_ATTEMPTED, DELIVERY_LAPSED
shipment_delivery_failed_address_issue	Address problems	DELIVERY_ATTEMPTED_ADDRESS_COULD_NOT_BE_FOUND
shipment_delivery_failed_forwarded_to_parcel_shop	Forwarded to pickup	DELIVERY_ATTEMPTED_FORWARDING_TO_PICKUP_LOCATION
shipment_delivery_second_attempt	Reattempting delivery	DELIVERY_ATTEMPTED_FAILED_WILL_TRY_AGAIN
shipment_not_picked_up_then_returned	Not picked up, returned	SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_LOCKER_RETURNED_TO_BASE
shipment_refused_then_returned	Customer refused package	DELIVERY_ATTEMPTED_REJECTED_BY_ADDRESSEE
shipment_failed_returned	Package returned to sender	RETURN_TO_SENDER_COMPLETED
shipment_picked_up	Successfully picked up	SUCCESSFULLY_COLLECTED

Claim Event Groups

Event Group	Description
claim_created	New claim submitted
claim_updated	Claim status changed

Event Filtering

When listening to Karla events (e.g. webhooks), use the ref values in your enabled_events array:

All Events

{
  "enabled_events": ["*"]
}

Specific Sources

{
  "enabled_events": ["shipments", "claims"]
}

Phase-Based Filtering (Shipments Only)

{
  "enabled_events": ["shipments/delivered", "shipments/in_delivery"]
}

Granular Event Filtering

{
  "enabled_events": [
    "shipments/delivered/SUCCESSFULLY_DELIVERED",
    "shipments/in_delivery/OUT_FOR_DELIVERY",
    "claims/created"
  ]
}

Common Business Use Cases

{
  "enabled_events": [
    "shipments/delivered",
    "shipments/delivery_failed",
    "shipments/in_transit/DELAY_EXPECTED",
    "shipments/in_transit/SHIPMENT_DAMAGED",
    "claims"
  ]
}

Event payload

All Karla events follow a consistent structure:

Standard Event Structure

{
  "source": "shipments|campaigns",
  "ref": "{source}/{phase|action|event_name}[/{event_name}]?",
  "version": 1,
  "triggered_at": "2024-01-29T14:48:47+00:00",
  "event_data": {
    // Event-specific data
  },
  "context": {
    // Related entities and metadata
  },
  "shop_slug": "your-shop-slug",
  "shop_id": "your-shop-uuid"
}

Event payload examples

Real event payloads you'll receive from Karla (e.g. via webhooks), organized by event type. These examples include full context data to help you understand the complete structure.

Shipment event

{
  "source": "shipments",
  "ref": "shipments/delivered/DEPARTURE_FROM_TRANSPORT_HUB",
  "version": 1,
  "triggered_at": "2024-01-29T14:48:47+00:00",
  "event_data": {
    "shipment_id": "6be0ea64-fe5e-478e-aee5-f9f7bbc53804",
    "carrier_reference": "dhl",
    "event_name": "DEPARTURE_FROM_TRANSPORT_HUB",
    "phase": "delivered",
    "tracking_number": "0123456789",
    "tracking_url": "https://example.com/tracking",
    "updated_at": "2024-01-29T14:48:47+00:00"
  },
  "context": {
    "order": {
      "order_number": "0000001",
      "order_name": null,
      "order_placed_at": "2025-06-18T22:00:04.264555+00:00",
      "total_order_price": 123.456,
      "shipping_price": 4.99,
      "sub_total_price": 118.457,
      "discount_price": 30,
      "products": [
        {
          "title": "Delivery s*cks",
          "quantity": 2,
          "price": 1,
          "size": "S",
          "images": [
            {
              "src": "https://storage.googleapis.com/karla-merchants-metadata/gokarla/Karla_SINGLE_PRODUCT.png",
              "alt": "Delivery socks"
            }
          ],
          "sku": null,
          "weight": null,
          "tax_lines": [],
          "bundled_products": [],
          "shipment_id": null,
          "type": "product"
        },
        {
          "title": "Magic item",
          "quantity": 3,
          "price": 4,
          "size": null,
          "images": [],
          "sku": null,
          "weight": null,
          "tax_lines": [],
          "bundled_products": [],
          "shipment_id": null,
          "type": "product"
        }
      ],
      "discounts": [],
      "email_id": null,
      "address": {
        "address_line_1": "Gormannstr.",
        "address_line_2": "19a",
        "city": "Berlin",
        "country": "Germany",
        "country_code": null,
        "name": "John Doe",
        "phone": "123456789",
        "province": "Berlin",
        "province_code": null,
        "street": "Gormannstr. 19a",
        "zip_code": "01234",
        "company": null
      },
      "currency": "EUR",
      "segments": null,
      "weight": null,
      "external_customer_id": null,
      "order_status_url": null
    },
    "customer": {
      "external_id": null,
      "email": null,
      "first_name": null,
      "last_name": null,
      "full_name": "John Doe",
      "phone": "123456789"
    },
    "shipments": [
      {
        "uuid": "6be0ea64-fe5e-478e-aee5-f9f7bbc53804",
        "updated_at": "2024-01-29T14:48:47+00:00",
        "events": [
          {
            "event_key": "H20",
            "time": "2023-10-09T15:31:43+00:00",
            "timezone": "UTC",
            "location": null,
            "additional_info": null,
            "phase": "delivered",
            "event_name": "SUCCESSFULLY_COLLECTED",
            "event_strings": {
              "event_status": "Nice! You've collected your parcel.",
              "list_label": "Collected",
              "header_headline": "COLLECTED",
              "header_title": "Home sweet home",
              "header_subtitle": "You have picked it up."
            },
            "language": "en"
          },
          {
            "event_key": "G24",
            "time": "2023-10-09T08:20:20+00:00",
            "timezone": "UTC",
            "location": null,
            "additional_info": null,
            "phase": "in_delivery",
            "event_name": "IN_DELIVERY",
            "event_strings": {
              "event_status": "Get ready! Your package is about to arrive.",
              "list_label": "Arriving 25.09",
              "header_headline": "ARRIVING",
              "header_title": "25.09",
              "header_subtitle": ""
            },
            "language": "en"
          },
          {
            "event_key": "E23",
            "time": "2023-10-08T13:50:40+00:00",
            "timezone": "UTC",
            "location": null,
            "additional_info": null,
            "phase": "in_transit",
            "event_name": "DEPARTURE_FROM_TRANSPORT_HUB",
            "event_strings": {
              "event_status": "Moving on! Your parcel has left the transport hub.",
              "list_label": "Arriving 25.09",
              "header_headline": "IN TRANSIT",
              "header_title": "25.09",
              "header_subtitle": ""
            },
            "language": "en"
          },
          {
            "event_key": "E21",
            "time": "2023-10-08T10:45:30+00:00",
            "timezone": "UTC",
            "location": null,
            "additional_info": null,
            "phase": "in_transit",
            "event_name": "ARRIVAL_AT_TRANSPORT_HUB",
            "event_strings": {
              "event_status": "Your parcel arrived at the transport hub and is getting ready for the next leg.",
              "list_label": "Arriving 25.09",
              "header_headline": "IN TRANSIT",
              "header_title": "25.09",
              "header_subtitle": ""
            },
            "language": "en"
          },
          {
            "event_key": "A12",
            "time": "2023-10-07T12:01:10+00:00",
            "timezone": "UTC",
            "location": null,
            "additional_info": null,
            "phase": "order_processed",
            "event_name": "ORDER_PROCESSED",
            "event_strings": {
              "event_status": "Your parcel has been packed and is ready to be shipped.",
              "list_label": "packed",
              "header_headline": "PACKED",
              "header_title": "Your parcel has been packed",
              "header_subtitle": ""
            },
            "language": "en"
          },
          {
            "event_key": "A10",
            "time": "2023-10-06T18:58:15+00:00",
            "timezone": "UTC",
            "location": null,
            "additional_info": null,
            "phase": "order_created",
            "event_name": "ORDER_CREATED",
            "event_strings": {
              "event_status": "You've placed an online order.",
              "list_label": "Order placed",
              "header_headline": "ORDER PLACED",
              "header_title": "Thanks for shopping!",
              "header_subtitle": ""
            },
            "language": "en"
          }
        ],
        "estimated_arrival": {
          "start": "2023-09-23T12:00:00+00:00",
          "end": "2023-09-25T12:00:00+00:00",
          "time_prediction": "25.09",
          "language": "en"
        },
        "carrier": {
          "tracking_number": "0123456789",
          "carrier_reference": "dhl",
          "tracking_url": null
        },
        "flag": "normal",
        "pickup": {
          "type": "neighbor",
          "name": "pickup_name",
          "address": {
            "address_line_1": "Gormannstr. 19a 01234 Berlin",
            "address_line_2": null,
            "city": null,
            "country": null,
            "country_code": null,
            "name": null,
            "phone": null,
            "province": null,
            "province_code": null,
            "street": "Gormannstr. 19a 01234 Berlin",
            "zip_code": null,
            "company": null
          },
          "url": "pickup_url",
          "opening_hours": "opening_hours",
          "date_to": "2023-09-26T12:00:00+00:00"
        },
        "products": [
          {
            "title": "Delivery s*cks",
            "quantity": 2,
            "price": 1,
            "size": "S",
            "images": [
              {
                "src": "https://storage.googleapis.com/karla-merchants-metadata/gokarla/Karla_SINGLE_PRODUCT.png",
                "alt": "Delivery socks"
              }
            ],
            "sku": null,
            "weight": null,
            "tax_lines": [],
            "bundled_products": []
          },
          {
            "title": "Magic item",
            "quantity": 3,
            "price": 4,
            "size": null,
            "images": [],
            "sku": null,
            "weight": null,
            "tax_lines": [],
            "bundled_products": []
          }
        ]
      }
    ],
    "claims": []
  },
  "shop_slug": "gokarla",
  "shop_id": "7af5390b-1425-4af6-a00d-e5f5184a7b51"
}

Claim Event

{
  "source": "claims",
  "ref": "claims/created",
  "version": 1,
  "triggered_at": "2023-09-23T12:00:00+00:00",
  "event_data": {
    "resolution_preference": "refund",
    "reason": "partial_damage",
    "status": "pending",
    "description": "Package was damaged on the right side",
    "customer_signature_image_url": "https://cdn.gokarla.io/12d6cceb-efa5-4bbc-a557-a6d31ed9f68b/df4f85de-1580-4c33-9178-cee6729e010a.png",
    "selected_items": [
      {
        "sku": "ABCD3",
        "title": "Product Title",
        "quantity": 1,
        "image_urls": []
      }
    ],
    "image_urls": [
      "https://cdn.gokarla.io/cdn-cgi/imagedelivery/dXeULRC3hlKS2IJjZmVx9Q/74c5c049-79b5-44b9-7972-672af41e8e00/claim"
    ],
    "claim_id": "38fdc365-7de9-4313-afbd-0ed23717c5e0",
    "event_name": "created",
    "created_at": "2023-09-23T12:00:00+00:00",
    "updated_at": "2023-09-23T12:00:00+00:00",
    "event_group": "claim_created"
  },
  "context": {
    "order": {
      "order_number": "0000001",
      "order_name": null,
      "order_placed_at": "2023-03-17T09:51:41+00:00",
      "total_order_price": 123.456,
      "shipping_price": 4.99,
      "sub_total_price": 118.457,
      "discount_price": 30,
      "products": [
        {
          "title": "Delivery s*cks",
          "variant_title": null,
          "quantity": 2,
          "price": 1,
          "size": "S",
          "images": [
            {
              "src": "https://storage.googleapis.com/karla-merchants-metadata/gokarla/Karla_SINGLE_PRODUCT.png",
              "alt": "Delivery socks"
            }
          ],
          "sku": null,
          "weight": null,
          "tax_lines": [],
          "bundled_products": [],
          "shipment_id": null,
          "type": "product"
        },
        {
          "title": "Magic item",
          "variant_title": null,
          "quantity": 3,
          "price": 4,
          "size": null,
          "images": [],
          "sku": null,
          "weight": null,
          "tax_lines": [],
          "bundled_products": [],
          "shipment_id": null,
          "type": "product"
        }
      ],
      "discounts": [],
      "email_id": "[email protected]",
      "address": {
        "address_line_1": "Gormanstr.",
        "address_line_2": "19a",
        "city": "Berlin",
        "country": "Germany",
        "country_code": "DE",
        "name": null,
        "phone": null,
        "province": null,
        "province_code": null,
        "street": null,
        "zip_code": "10119",
        "company": null
      },
      "currency": "EUR",
      "segments": null,
      "weight": null,
      "external_customer_id": "123456789",
      "order_status_url": "https://shop.gokarla.io/1234067358984/orders/aabbcc/authenticate?key=secret"
    },
    "customer": {
      "external_id": "123456789",
      "email": "[email protected]",
      "first_name": null,
      "last_name": null,
      "full_name": null,
      "phone": null
    },
    "shipments": [
      {
        "uuid": "6be0ea64-fe5e-478e-aee5-f9f7bbc53804",
        "updated_at": "2024-01-29T14:48:47+00:00",
        "events": [
          {
            "event_key": "H20",
            "time": "2023-10-09T15:31:43+00:00",
            "timezone": "UTC",
            "location": null,
            "additional_info": null,
            "phase": "delivered",
            "event_name": "SUCCESSFULLY_COLLECTED",
            "event_strings": {
              "event_status": "Nice! You've collected your parcel.",
              "list_label": "Collected",
              "header_headline": "COLLECTED",
              "header_title": "Home sweet home",
              "header_subtitle": "You have picked it up."
            },
            "language": "en"
          },
          {
            "event_key": "G24",
            "time": "2023-10-09T08:20:20+00:00",
            "timezone": "UTC",
            "location": null,
            "additional_info": null,
            "phase": "in_delivery",
            "event_name": "IN_DELIVERY",
            "event_strings": {
              "event_status": "Get ready! Your package is about to arrive.",
              "list_label": "Arriving 25.09",
              "header_headline": "ARRIVING",
              "header_title": "25.09",
              "header_subtitle": ""
            },
            "language": "en"
          },
          {
            "event_key": "E23",
            "time": "2023-10-08T13:50:40+00:00",
            "timezone": "UTC",
            "location": null,
            "additional_info": null,
            "phase": "in_transit",
            "event_name": "DEPARTURE_FROM_TRANSPORT_HUB",
            "event_strings": {
              "event_status": "Moving on! Your parcel has left the transport hub.",
              "list_label": "Arriving 25.09",
              "header_headline": "IN TRANSIT",
              "header_title": "25.09",
              "header_subtitle": ""
            },
            "language": "en"
          },
          {
            "event_key": "E21",
            "time": "2023-10-08T10:45:30+00:00",
            "timezone": "UTC",
            "location": null,
            "additional_info": null,
            "phase": "in_transit",
            "event_name": "ARRIVAL_AT_TRANSPORT_HUB",
            "event_strings": {
              "event_status": "Your parcel arrived at the transport hub and is getting ready for the next leg.",
              "list_label": "Arriving 25.09",
              "header_headline": "IN TRANSIT",
              "header_title": "25.09",
              "header_subtitle": ""
            },
            "language": "en"
          },
          {
            "event_key": "A12",
            "time": "2023-10-07T12:01:10+00:00",
            "timezone": "UTC",
            "location": null,
            "additional_info": null,
            "phase": "order_processed",
            "event_name": "ORDER_PROCESSED",
            "event_strings": {
              "event_status": "Your parcel has been packed and is ready to be shipped.",
              "list_label": "packed",
              "header_headline": "PACKED",
              "header_title": "Your parcel has been packed",
              "header_subtitle": ""
            },
            "language": "en"
          },
          {
            "event_key": "A10",
            "time": "2023-10-06T18:58:15+00:00",
            "timezone": "UTC",
            "location": null,
            "additional_info": null,
            "phase": "order_created",
            "event_name": "ORDER_CREATED",
            "event_strings": {
              "event_status": "You've placed an online order.",
              "list_label": "Order placed",
              "header_headline": "ORDER PLACED",
              "header_title": "Thanks for shopping!",
              "header_subtitle": ""
            },
            "language": "en"
          }
        ],
        "estimated_arrival": {
          "start": "2023-09-23T12:00:00+00:00",
          "end": "2023-09-25T12:00:00+00:00",
          "time_prediction": "25.09",
          "language": "en"
        },
        "carrier": {
          "tracking_number": "0123456789",
          "carrier_reference": "dhl",
          "tracking_url": "https://example.com/tracking"
        },
        "flag": "normal",
        "pickup": {
          "type": "neighbor",
          "name": "pickup_name",
          "address": {
            "address_line_1": "Gormannstr. 19a 01234 Berlin",
            "address_line_2": null,
            "city": null,
            "country": null,
            "country_code": null,
            "name": null,
            "phone": null,
            "province": null,
            "province_code": null,
            "street": "Gormannstr. 19a 01234 Berlin",
            "zip_code": null,
            "company": null
          },
          "url": "pickup_url",
          "opening_hours": "opening_hours",
          "date_to": "2023-09-26T12:00:00+00:00"
        },
        "products": [
          {
            "title": "Delivery s*cks",
            "variant_title": null,
            "quantity": 2,
            "price": 1,
            "size": "S",
            "images": [
              {
                "src": "https://storage.googleapis.com/karla-merchants-metadata/gokarla/Karla_SINGLE_PRODUCT.png",
                "alt": "Delivery socks"
              }
            ],
            "sku": null,
            "weight": null,
            "tax_lines": [],
            "bundled_products": []
          },
          {
            "title": "Magic item",
            "variant_title": null,
            "quantity": 3,
            "price": 4,
            "size": null,
            "images": [],
            "sku": null,
            "weight": null,
            "tax_lines": [],
            "bundled_products": []
          }
        ]
      }
    ],
    "claims": []
  },
  "shop_slug": "gokarla",
  "shop_id": "7af5390b-1425-4af6-a00d-e5f5184a7b51"
}

Related Resources

• Webhook Setup Guide - Configure webhook endpoints
• Shipment Entity - Complete shipment API reference
• Klaviyo Integration - Event group usage in Klaviyo flows