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​

Business-friendly groupings that determine which notification is triggered. Event groups are what third-party integrations (Klaviyo, Brevo, Braze, Emarsys, webhooks, etc.) receive. Only events with an event group mapping will trigger notifications.

Shipment Event Groups​

Events are organized by event group — the value that determines which notification flow fires. Each event group can contain events from different shipment phases, since the same notification may apply across multiple stages of the delivery journey. Only events with a group mapping trigger notifications.

Draft vs Fulfilled Events
  • Draft shipments: Only generate pre-transit events like ORDER_CREATED or ORDER_CANCELLED (no tracking number yet)
  • Fulfilled shipments: Generate all tracking events below
108 events in 21 groups

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

Shipment Events API​

You can programmatically trigger events on shipments using the Shipment Events API. This is useful for triggering notification flows or webhooks for orders that don't have tracking (draft shipments).

Lookup by order number​

curl -X POST "https://api.gokarla.io/v1/shop/{slug}/shipment-events?notify=true" \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "1001",
    "id_type": "order_number",
    "event_name": "ORDER_PROCESSED"
  }'

Lookup by external order ID​

curl -X POST "https://api.gokarla.io/v1/shop/{slug}/shipment-events?notify=true" \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "5512345678901",
    "id_type": "external_order_id",
    "event_name": "SUCCESSFULLY_DELIVERED"
  }'
Single-shipment orders only

When using order_number or external_order_id as id_type, the order must have exactly one shipment. If the order has multiple shipments, the API will return an error — use shipment_uuid or tracking_number instead.

The notify=true query parameter triggers the event group notification (webhook, email flow, etc.). Without it, the event is recorded but no notification is sent.

Event payload​

All Karla events follow a consistent structure:

Standard Event Structure
{
  "source": "shipments|claims",
  "ref": "{source}/{phase|action|event_name}[/{event_name}]?",
  "version": 1,
  "triggered_at": "2024-01-29T14:48:47+00:00",
  "event_group": "shipment_in_transit|claim_created|...", // See Event Groups
  "event_data": {
    // Event-specific data: different payload depending on source
  },
  "context": {
    // Related entities and metadata: order, shipments and claims
  },
  "shop_slug": "your-shop-slug",
  "shop_id": "your-shop-uuid"
}

Event-specific Data​

Variables within event_data is what we typically expose into your email templates when working with native integrations (Klaviyo, Emarsys, Brevo, Braze, HubSpot, etc...), unless documented otherwise.

Shipment Event 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",
    "order_number": "ORD-2024-001",

    // Optional fields that may be present depending on the event type or data source (e.g. data sent by your shop)
    "order_name": "ORD-2024-001",
    "zip_code": "10115",
    "shipping_address": "123 Main St, Berlin, 10115, Germany",
    "total_order_value": 49.99,
    "order_currency": "EUR",
    "order_status_url": "https://shop.example.com/orders/status/123",
    "external_customer_id": "CUST-98765",
    "external_order_id": "shopify-order-123",
    "preferred_delivery_date": "15.01.2024",
    "customer_first_name": "John",
    "customer_last_name": "Doe",
    "customer_country": "Germany",

    // Optional fields for specific event groups
    "expected_delivery_date": "20.01.2024",
    "pick_up_address": "Parcel Shop, 456 Store St, Berlin",
    "pick_up_until": "25.01.2024",
    "neighbour_name": "Jane Smith",
    "requested_delivery_date": "30.01.2024",

    // Optional fields for multi-shipment orders (IN_TRANSIT events)
    "number_of_shipments": 3,
    "other_tracking_numbers": ["1234567890", "0987654321"]
  }
  ...
}

Claim Event Data​

Claim event data
{
  ...
  "event_data": {
    "claim_id": "7022541c-62cd-4de3-9fb2-bfdc74bf7834",
    "event_name": "created",
    "created_at": "2021-09-01T00:00:00Z",
    "updated_at": "2021-09-01T00:00:00Z",
    "event_group": "claim_created",
    "resolution_preference": "refund",
    "reason": "damage",
    "description": "Package was damaged during shipping",
    "selected_items": [],
    "image_urls": [],
    "optional_image_urls": []
  }
  ...
}

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/in_transit/DEPARTURE_FROM_TRANSPORT_HUB",
  "version": 1,
  "triggered_at": "2024-01-29T14:48:47+00:00",
  "event_group": "shipment_in_transit",
  "event_data": {
    "shipment_id": "6be0ea64-fe5e-478e-aee5-f9f7bbc53804",
    "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"
  },
  "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 socks",
          "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"
        }
      ],
      "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": "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": "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": null,
        "products": [
          {
            "title": "Delivery socks",
            "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": []
          }
        ]
      }
    ],
    "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_group": "claim_created",
  "event_data": {
    "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",
    "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"
    ],
    "optional_image_urls": []
  },
  "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 socks",
          "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"
        }
      ],
      "discounts": [],
      "email_id": "email_test@gokarla.io",
      "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_test@gokarla.io",
      "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": "H10",
            "time": "2023-10-09T15:31:43+00:00",
            "timezone": "UTC",
            "location": null,
            "additional_info": null,
            "phase": "delivered",
            "event_name": "SUCCESSFULLY_DELIVERED",
            "event_strings": {
              "event_status": "Your parcel has been delivered.",
              "list_label": "Delivered",
              "header_headline": "DELIVERED",
              "header_title": "Home sweet home",
              "header_subtitle": "Enjoy your purchase!"
            },
            "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": null,
        "products": [
          {
            "title": "Delivery socks",
            "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": []
          }
        ]
      }
    ],
    "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