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; ~160 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.

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

One notification per group#

Karla fires at most one notification per event_group, per shipment, per channel (webhook, Klaviyo, Brevo, etc.). Notifications follow the shipment forward through its lifecycle: a group notifies the first time it is reached and never again — so several events that map to the same group produce a single notification, and once a later stage is reached, earlier groups don't re-fire. You get one message per meaningful state change, and you don't need to deduplicate on your side.

A few merchant-facing groups are designed to repeat and bypass this rule:

shipment_carrier_delay, shipment_damaged, and shipment_delayed_due_to_customer_request.
shipment_eta_updated — fired whenever Karla recomputes the shipment's estimated arrival (via the SHIPMENT_UPDATED_ETA event), so it can notify several times as the ETA moves. It isn't tied to a lifecycle phase, so it's not shown in the catalogue above.

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 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··

Returns to sender (RTS)#

A return to sender happens when a forward shipment (merchant_customer) can't be delivered and the carrier sends it back. It plays out on the same forward shipment, which moves into the returned phase — it is not a separate customer_merchant return shipment (a customer shipping a product back), which uses the return_shipment_* groups described above.

Karla splits RTS into three groups by cause:

shipment_failed_returned — delivery was attempted but failed (undeliverable, or attempts exhausted).
shipment_refused_then_returned — the recipient refused the parcel.
shipment_not_picked_up_then_returned — the recipient never collected it from a pickup point.

This section covers shipment_failed_returned, which bundles four events:

Event	Meaning
`RETURN_IN_PROGRESS`	Parcel is moving back through the carrier network toward the sender.
`SHIPMENT_RETURNING_TO_SENDER`	Parcel is on its final leg back — out for delivery to, or waiting at a pickup point for, the sender.
`SHIPMENT_SUCCESSFULLY_RETURNED_TO_SENDER`	Karla-confirmed success: the parcel was delivered or collected back at the sender.
`SHIPMENT_RETURNED_TO_SENDER`	The carrier's own native "returned" status, passed through as-is.

Typical order#

When a carrier reports the full journey, the events fire in this order:

RETURN_IN_PROGRESS → SHIPMENT_RETURNING_TO_SENDER → a terminal event (SHIPMENT_SUCCESSFULLY_RETURNED_TO_SENDER or SHIPMENT_RETURNED_TO_SENDER).

This ordering describes the recorded event history — every event that arrives appears in a webhook's context.shipments[].events[] and in the portal timeline. It does not mean several notifications: the whole group still fires a single notification (see One notification per group above).

These events are derived from the carrier's return-leg scans, so which ones fire — and in what order — depends entirely on the carrier. Many carriers skip the intermediate steps and report only a single terminal event. In particular, RETURN_IN_PROGRESS is not guaranteed for every return: a carrier that doesn't emit in-transit scans on the return leg will never produce it.

`SHIPMENT_RETURNED_TO_SENDER` vs `SHIPMENT_SUCCESSFULLY_RETURNED_TO_SENDER`#

Both are terminal returned-phase events meaning the parcel is back with the sender, but they come from different sources:

SHIPMENT_SUCCESSFULLY_RETURNED_TO_SENDER is Karla-derived: it fires when a successful delivery / collection scan arrives while the parcel is on the return leg. It is the most reliable confirmation that a return actually completed.
SHIPMENT_RETURNED_TO_SENDER is a carrier's native "returned to sender" status, passed through as-is. It reflects whatever the carrier reports rather than a confirmed delivery scan.

Which of the two you receive depends on the carrier's own event vocabulary. A shipment usually gets one or the other; occasionally both.

Triggering a workflow (RTS)#

Karla sends only one notification per group (see One notification per group above), so a shipment produces a single shipment_failed_returned notification — the first return event to arrive fires it, and the rest are suppressed. Bind your RTS workflow (e.g. notifying a warehouse) to the group rather than a specific event name: which of the four events triggers the notification is carrier-dependent, but you'll only ever receive one, so no client-side deduplication is needed. In that notification, event_group is shipment_failed_returned and event_data.event_name tells you which event fired.

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/shops/{slug}/shipments/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/shops/{slug}/shipments/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"
  }'

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",
    "direction": "merchant_customer",
    "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",
    "direction": "merchant_customer"
  },
  "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.