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: order-stage events only — ORDER_CREATED at placement, ORDER_PROCESSED when the order is marked as processed, and ORDER_CANCELLED if the order is cancelled.
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 — the view of the fulfilled shipment nested inside an Order response. Carries what a tracking page needs: carrier data (tracking number, carrier reference, tracking URL), the full events history (each event carries its phase), the estimated arrival window, flag, pickup data, products, and direction.

Both represent the same package, exposed from different angles.

Shipment phases#

A shipment moves through phases as the carrier reports scans:

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

    [*] --> 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
    returned --> return_failed : lost/damaged during return

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`	3
`order_cancelled`	`ORDER_CANCELLED`	1
`order_processed`	`PARCEL_DISPATCHED`, `PARCEL_DROPPED_OFF_AT_POST_OFFICE`, `CARRIER_UNKNOWN`	22
`in_transit`	`ARRIVED_AT_SORTING_CENTER`, `CUSTOMS_PROCESSING`, `SHIPMENT_EN_ROUTE`, `DELAY_EXPECTED`	63
`in_delivery`	`OUT_FOR_DELIVERY`, `DELIVERY_ATTEMPTED`, `DELIVERY_ATTEMPTED_RECIPIENT_NOT_AT_HOME`	21
`collect`	`ARRIVED_AT_PARCEL_SHOP`, `ARRIVED_AT_POST_OFFICE`	9
`delivered`	`SUCCESSFULLY_DELIVERED`, `SUCCESSFULLY_COLLECTED_AT_PARCEL_SHOP`	10
`delivery_failed`	`DELIVERY_ATTEMPTED_REJECTED_BY_ADDRESSEE`, `SHIPMENT_NOT_PICKED_UP_RETURNED_TO_ORIGIN_COUNTRY`	7
`returned`	`SHIPMENT_RETURNED_TO_SENDER`, `RETURN_TO_SENDER_COMPLETED`	10
`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.