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.
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 eventsclaims
- Customer service request 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
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 mainly by fulfilled shipments (those with tracking numbers). Draft shipments only generate pre-transit events.
- Draft shipments: Only generate pre-transit events like
ORDER_CREATED
orORDER_CANCELLED
events (no tracking number yet) - Fulfilled shipments: Generate all other tracking events
Event Structure
Ref Pattern: shipments/{phase}/{event_name}
By Phase
- Pre-Transit Phase:
order_created
,order_processed
... - Events when order is placed but before carrier pickup - In-Transit Phase:
in_transit
,in_delivery
... - Package moving through carrier network - Out for Delivery Phase:
out_for_delivery
,collect
... - Final mile delivery events - Delivered Phase: e.g.
delivered
- Successful delivery confirmations - Failed Delivery Phase: e.g.
delivery_failed
- Unsuccessful delivery attempts - Carrier Delay Phase: e.g.
carrier_delay
- Delays and issues during transport - Returned Phase:
returned
,return_failed
... - Return to sender events
Event Catalog
Full shipment event catalog with their respective event name (most granular), ref (for webhooks) and event group (exposed to third-parties like Klaviyo).
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.
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.
- Delivery Events
- Transit Events
- Issue Events
- Return Events
- Claim Events
Event Group | Description | Example Event Names |
---|---|---|
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_picked_up | Successfully picked up | SUCCESSFULLY_COLLECTED |
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_out_for_delivery | Package out for delivery | OUT_FOR_DELIVERY , IN_DELIVERY |
Event Group | Description | Example Event Names |
---|---|---|
shipment_carrier_delay | Carrier-reported delays | DELAY_EXPECTED , DELAY_IN_TRANSPORT |
shipment_damaged | Package damage reported | SHIPMENT_DAMAGED |
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 |
Event Group | Description | Example Event Names |
---|---|---|
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 |
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:
{
"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-specific Data
{
...
"event_data": {
"shipment_id": "abc65a96-0871-452a-a506-c644e2012123",
"carrier_reference": "dhl",
"event_name": "DEPARTURE_FROM_TRANSPORT_HUB",
"phase": "in_transit",
"tracking_number": "0123456789",
"tracking_url": "https://example.com/tracking",
"updated_at": "2024-01-29T14:48:47+00:00",
"event_group": "shipment_in_transit"
}
...
}
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
- Klaviyo Integration - Event group usage in Klaviyo flows
- Webhook Setup - Event subscription guide
- Merchant Portal - Order management interface