# Overview

Source: https://gokarla.io/docs/platform/shipments

# 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](/docs/api-reference). For the full event catalog, see
[Events](/docs/platform/events/overview).

## 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.

```mermaid
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:

```mermaid
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](/docs/platform/events/overview).

## Events and webhooks

Fulfilled shipments emit events as the carrier progresses the package.
Subscribe via the [Webhooks](/docs/guides/notify/webhooks) API to react to
them in your own systems.

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

## Related

- [Orders](/docs/platform/orders) — the parent entity that owns
  shipments.
- [Events](/docs/platform/events/overview) — event catalog, `ref`
  patterns, payload structure, filtering.
- [Webhooks](/docs/guides/notify/webhooks) — subscribe to shipment events.
- [Headless](/docs/guides/shops/headless) — end-to-end
  integration guide.