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.

System integration#

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.

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.
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.
Campaigns — the order's segments and attribution data drive which campaigns render on the tracking page. See Portal — Campaigns.
Tracking view — order detail responses include a trackings array with the full tracking view of each shipment: carrier data (tracking number, carrier reference, tracking URL), the complete events history (each event carries its phase), the estimated arrival window, flag, pickup data, products, and direction.

Events#

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

See Events for the full catalog and payload structure.
Subscribe via Webhooks to react to them in your own systems.

Creating and managing orders#

The canonical how-to guide lives in Headless, which walks through the order → fulfillment → events → claims sequence. For endpoint specs, see the 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 is stored on the order as order_analytics — a free-form object with a canonical key set — and drives per-campaign performance in the portal. See Campaign attribution for the end-to-end story and the capture paths that populate it.

Key	Meaning
`source`	Where the click came from (e.g. `trackpages`). Required for attribution.
`campaign`	Campaign UUID — links the order to a specific campaign.
`medium`	Promotion type, e.g. `basic_promotion`, `product_promotion`, `banner_promotion`.
`landing_url`	Sanitized URL the customer landed on.
`landing_path`	Path portion of the landing URL.
`referrer`	Referring page, if any.
`captured_at`	ISO timestamp of when attribution was captured.

Two write behaviors to be aware of:

order.order_analytics (nested in the order object) is written only at order creation and ignored afterwards.
The top-level order_analytics field on fulfillment payloads is merged on every write — incoming keys overwrite same-named keys, other existing keys are preserved. Use it to attach or update attribution on an existing order.
The legacy alias keys affiliate_code and campaign_code are rewritten to source and campaign before storage.

Shipments — entity detail for the contained shipments.
Events — event payload and filtering.
Headless — build on the API directly.
Portal — merchant interface.