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 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 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 (campaign / source / medium) is stored on the order via order_analytics and drives per-campaign performance in the portal. See Campaign attribution for the methods, trade-offs, and the three ways to populate this data.

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