# Overview

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

# Orders

The `Order` entity represents a customer purchase in your shop. It is the
foundation for post-purchase tracking, campaigns, claims, and analytics in
Karla.

This page documents the **entity model** — states, relationships, and the
events an order generates. For request/response shapes and live code
samples, see the [API reference](/docs/api-reference).

## System integration

```mermaid
flowchart TD
    A[Customer] -->|places| B[Order]

    B -->|initial state| D[Placed Order]
    D -->|fulfillment| E[Fulfilled Order]

    D -->|contains| F[Draft Shipments]
    E -->|contains| G[Fulfilled Shipments]

    F -->|no tracking yet| H[Expected Packages]
    G -->|with tracking| I[Active Tracking]

    I -->|generates| J[Shipment Events]
    J -->|enables| L[Claims]

    B -->|used for| M[Tracking Pages]
    B -->|contains| N[Products]
    B -->|ships to| O[Address]
```

## Order states

### Placed

- **When**: the order has been accepted and paid, but not yet shipped.
- **Shipments**: contains **Draft Shipments** (no tracking numbers).
- **Customer experience**: shows expected packages and estimated delivery.
- **Event generation**: order-level events only.

### Fulfilled

- **When**: at least one shipment has been dispatched to a carrier.
- **Shipments**: contains **Fulfilled Shipments** (with tracking numbers).
- **Customer experience**: real-time tracking and delivery updates, access
  to resolve flows.
- **Event generation**: full carrier event catalog per shipment.

### Partial fulfillment

Orders with multiple expected shipments can be fulfilled incrementally —
some shipments stay as drafts while others become fulfilled. Customers see
tracking for the fulfilled packages and expectations for the pending ones.

:::info
Partial fulfillment only applies in multi-shipment scenarios where the order
was placed with `expected_number_of_shipments > 1`.
:::

## Relationships

- **Shipments** — one order contains one or more shipments; each shipment
  carries products from the order. See
  [Shipments](/docs/platform/shipments).
- **Products** — line items with images, price, quantity, tax, and optional
  bundled products.
- **Address** — the shipping destination.
- **Discounts** — codes, amounts, and types attached to the order.
- **Claims** — customer-initiated issues (damaged, not received, return).
  Claims reference the order. See [Resolve](/docs/guides/resolve/overview).
- **Campaigns** — the order's segments and attribution data drive which
  campaigns render on the tracking page. See
  [Portal — Campaigns](/docs/guides/portal/campaigns).
- **Tracking summary** — the order object includes a simplified `trackings`
  array with tracking number, carrier reference, tracking URL, phase, and
  ETA for each associated shipment.

## Events

A fulfilled order automatically generates events as the carrier updates the
shipment. Claims emit their own events.

- See [Events](/docs/platform/events/overview) for the full catalog and
  payload structure.
- Subscribe via [Webhooks](/docs/guides/notify/webhooks) to react to them in
  your own systems.

## Creating and managing orders

The canonical how-to guide lives in
[Headless](/docs/guides/shops/headless), which walks through the
order → fulfillment → events → claims sequence. For endpoint specs, see the
[API reference](/docs/api-reference) directly — every code sample below is
generated live from the OpenAPI spec.

In brief:

- **Upsert Order** — create, update, or re-fulfill by order number or
  external ID. Recommended over the narrower Place Order endpoint.
- **Update Order** — change the address or `expected_number_of_shipments`.
- **Update Shipment** — change tracking URL or per-shipment products.
- **Bulk Fulfillment** — attach tracking numbers to many orders in one call.
- **Upsert Order Analytics** — attach or update attribution data after order
  creation.

## Attribution

Order attribution (campaign / source / medium) is stored on the order via
`order_analytics` and drives per-campaign performance in the portal. See
[Campaign attribution](/docs/guides/tracking-page/attribution) for the
methods, trade-offs, and the three ways to populate this data.

## Related

- [Shipments](/docs/platform/shipments) — entity detail for the
  contained shipments.
- [Events](/docs/platform/events/overview) — event payload and filtering.
- [Headless](/docs/guides/shops/headless) — build on the API
  directly.
- [Portal](https://portal.gokarla.io) — merchant interface.