Shipments#

The Shipment entity represents a single package delivery. One order can contain multiple shipments. Each shipment moves through a lifecycle of phases and emits events as carriers report updates.

This page documents the entity and its state machine. For field shapes and live request/response samples, see the API reference. For the full event catalog, see Events.

States#

A shipment is always in one of two states:

Draft#

When: created alongside the order, before a carrier is involved.
Has tracking number: no.
Events: only pre-transit events (ORDER_CREATED, ORDER_IN_PROCESSING).
Use: show expected packages on the tracking page, enable pre-shipment campaigns.

Fulfilled#

When: created when a tracking number is attached to the order.
Has tracking number: yes.
Events: every carrier tracking event.
Use: real-time package tracking, delivery campaigns, claim flows.

erDiagram
    Shipment ||--|| DraftShipment : "is a"
    Shipment ||--|| FulfilledShipment : "is a"
    FulfilledShipment ||--|| Tracking : "exposes as"

Shipment vs. tracking#

In Karla's API, Shipment and Tracking refer to the same underlying entity, exposed two different ways:

Shipment — the full entity, used in shipment-specific endpoints and claim flows.
Tracking — a compact view of the fulfilled shipment nested inside an Order response. Contains just the fields a tracking page needs: tracking number, carrier reference, tracking URL, phase, and estimated arrival window.

Both represent the same package; Tracking is simply a subset.

Shipment phases#

A shipment moves through phases as the carrier reports scans:

stateDiagram-v2
    [*] --> order_created: placed
    order_created --> order_processed : fulfilled

    [*] --> order_processed: placed and fulfilled
    order_processed --> in_transit : handed to carrier

    in_transit --> in_delivery : out for delivery
    in_transit --> collect : arrived at pickup point

    collect --> delivered : picked up by customer
    in_delivery --> delivered : delivered to customer
    in_delivery --> delivery_failed : delivery attempt failed

    delivery_failed --> in_delivery : reattempt delivery
    delivery_failed --> returned : undeliverable

    return_created --> return_transit : started return
    return_transit --> return_received : received at return center
    return_received --> returned : successfully returned
    return_transit --> return_failed : lost/damaged

Each phase contains multiple event_name values that describe exactly what the carrier reported. For example:

Phase	Representative event names	Approx. count
`order_created`	`ORDER_CREATED`, `ORDER_IN_PROCESSING`	2
`order_processed`	`PARCEL_DISPATCHED`, `PARCEL_DROPPED_OFF_AT_POST_OFFICE`, `CARRIER_UNKNOWN`	~23
`in_transit`	`ARRIVED_AT_SORTING_CENTER`, `CUSTOMS_PROCESSING`, `SHIPMENT_EN_ROUTE`, `DELAY_EXPECTED`	~50+
`in_delivery`	`OUT_FOR_DELIVERY`, `DELIVERY_ATTEMPTED`, `DELIVERY_ATTEMPTED_RECIPIENT_NOT_AT_HOME`	~19
`collect`	`ARRIVED_AT_PARCEL_SHOP`, `ARRIVED_AT_POST_OFFICE`	6
`delivered`	`SUCCESSFULLY_DELIVERED`, `SUCCESSFULLY_COLLECTED_AT_PARCEL_SHOP`	10
`delivery_failed`	`DELIVERY_ATTEMPTED_REJECTED_BY_ADDRESSEE`, `SHIPMENT_NOT_PICKED_UP_RETURNED_TO_ORIGIN_COUNTRY`	6
`returned`	`SHIPMENT_RETURNED_TO_SENDER`, `RETURN_TO_SENDER_COMPLETED`	7
`return_failed`	`DELIVERY_FAILED_SHIPMENT_DESTROYED`	1

For the complete enumeration of event names per phase — plus their ref patterns, event groups, and payload shape — see Events.

Events and webhooks#

Fulfilled shipments emit events as the carrier progresses the package. Subscribe via the Webhooks API to react to them in your own systems.

You can also append custom events to a shipment when you observe state outside of carrier scans (internal pre-shipment QA, logistics partners that don't integrate with Karla, etc.).

Orders — the parent entity that owns shipments.
Events — event catalog, ref patterns, payload structure, filtering.
Webhooks — subscribe to shipment events.
Headless — end-to-end integration guide.