Skip to main content

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

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 mainly by fulfilled shipments (those with tracking numbers). Draft shipments only generate pre-transit events.

Draft vs Fulfilled Events
  • Draft shipments: Only generate pre-transit events like ORDER_CREATED or ORDER_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 NameRefEvent Group
SHIPMENT_LOST_IN_DELIVERYshipments/{phase}/SHIPMENT_LOST_IN_DELIVERYshipment_lost
SHIPMENT_LOST_IN_TRANSITshipments/{phase}/SHIPMENT_LOST_IN_TRANSITshipment_lost
SHIPMENT_LOSTshipments/{phase}/SHIPMENT_LOSTshipment_lost

Claim Events

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

Ref Pattern: claims/{event_name}

Event NameRefDescription
CLAIM_CREATEDclaims/createdNew claim submitted by customer
CLAIM_UPDATEDclaims/updatedClaim status or details changed

Event Groups

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

Event GroupDescriptionExample Event Names
shipment_deliveredSuccessful deliverySUCCESSFULLY_DELIVERED
shipment_delivered_all_eventsAll delivery variationsAll delivered phase events
shipment_delivered_to_neighbourDelivered to neighborSUCCESSFULLY_DELIVERED_TO_NEIGHBOR
shipment_delivered_to_letterboxDelivered to letterboxSUCCESSFULLY_DELIVERED_AND_LEFT_AT_LETTER_BOX
shipment_delivered_to_parcel_shopDelivered to pickup pointARRIVED_AT_PARCEL_SHOP, SUCCESSFULLY_COLLECTED_AT_PARCEL_SHOP
shipment_delivered_to_parcel_lockerDelivered to parcel lockerARRIVED_AT_PARCEL_LOCKER, SUCCESSFULLY_COLLECTED_AT_PARCEL_LOCKER
shipment_picked_upSuccessfully picked upSUCCESSFULLY_COLLECTED

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-specific Data

Shipment event 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"
}

API Reference

  • Claim - Customer service and resolve flows
  • Shipment - Detailed shipment and tracking information