Shipment events#

Shipment events are generated by carrier scans as a parcel moves through its lifecycle, plus any custom events you emit yourself. Use the catalogue below to find the event you care about, then wire the event group into your notification flow.

Key concepts#

Four fields describe every shipment event. Understanding how they relate is the fastest way to wire notifications correctly.

Field	What it is	Example
`event_name`	The specific carrier scan. One per physical checkpoint; ~80 distinct values.	`DEPARTURE_FROM_TRANSPORT_HUB`
`phase`	The lifecycle stage the parcel is in. ~10 values; think of it as a progress bar.	`in_transit`
`event_group`	The notification bucket. This is what fires your Klaviyo/webhook/email flow.	`shipment_in_transit`
`direction`	Whether the parcel is going to the customer or back to the merchant.	`merchant_customer`

How they combine: one event_name always maps to exactly one phase and (when notifying) to one event_group. The same event_name can belong to different event_groups depending on direction — see below.

Ref pattern: shipments/{phase}/{event_name} — e.g. shipments/delivered/SUCCESSFULLY_DELIVERED.

Wire notifications to groups, not names

Filter on event_group when subscribing to webhooks or building Klaviyo flows — there are ~20 groups vs ~80 event names, and the groups already bundle events that should trigger the same customer message.

Forward vs return direction#

Every shipment has a direction:

merchant_customer (forward) — the default; merchant ships to customer. Groups prefixed shipment_* apply.
customer_merchant (return) — customer ships back to merchant. Karla collapses the forward groups into 5 return_shipment_* buckets so you can wire a separate template for "your return is on its way" vs "your order is on its way".

The underlying carrier events (OUT_FOR_DELIVERY, SUCCESSFULLY_DELIVERED, etc.) are identical — only the group assignment differs.

Draft vs fulfilled

Draft shipments (no tracking number yet) only notify on ORDER_PROCESSED and ORDER_CANCELLED.
Fulfilled shipments (tracking number attached) generate the full set of carrier tracking events below.

Event catalogue#

Browse every shipment event Karla emits. Toggle Forward / Return to switch direction, and By group / By event to pivot between notification buckets and individual event names. Use search to filter by any text.

111 events in 20 groups··

Shipment Events API#

You can programmatically trigger events on shipments via the API reference. This is useful for:

Firing notification flows or webhooks for draft shipments that don't yet have carrier tracking.
Injecting state from a logistics partner that doesn't integrate with Karla.
Recording internal QA or pre-handoff milestones.

Lookup by order number#

curl -X POST "https://api.gokarla.io/v1/shop/{slug}/shipment-events?notify=true" \
  -u your-username:your-private-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" \
  -u your-username:your-private-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. For multi-shipment orders, identify the specific shipment via 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 silently.

`event_data` shape#

Variables inside event_data are what Karla exposes to native integration templates (Klaviyo, Emarsys, Brevo, Braze, HubSpot, etc.) unless documented otherwise.

{
  ...
  "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 present depending on event type or shop-provided data
    "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"]
  }
  ...
}

Full payload example#

A real shipment event as you'd receive it via webhook, including the context block with the full order, customer, and shipment data:

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

Events overview — hierarchy, envelope, and filtering syntax.
Claim events — Resolve-side events.
Shipments — entity, state machine, and phases.
Webhooks — subscribe to shipment events.
Notify integrations — wire events into Klaviyo, Brevo, HubSpot, etc.