DocsDocsStart

Orders and order lines

Learn which surface owns order records, order lines, status changes, customer order lookup, sales metrics, and order events.

Start here when your integration touches orders and you need to know whether the job belongs to trusted back-office order operations, customer account reads, or event-driven downstream work.

The short model

An order is the placed commerce record. It carries the customer, addresses, totals, payment and shipping context, order status, merchant context, and the order lines that explain what was bought.

An order line is one purchased item inside the order. Line operations are for changing the contents of an order after the order record exists.

An order status is the lifecycle state of the order. Status changes are separate from editing addresses, totals, line contents, or merchant metadata.

Use the surface that matches the change:

  • Use the order record when the whole order changes or needs to be inspected.
  • Use order-line operations when the contents of an existing order change.
  • Use order-status operations when the fulfillment or lifecycle state changes.
  • Use order events when another system needs to react after the order changes.

Choose the right surface

Order work can run in several places. Choose the route by job:

JobUseWhy
Create an order from a trusted integrationCreate orderManagement API owns back-office order creation and requires initial line data.
Edit order-level fieldsUpdate orderManagement API owns trusted order updates. Omitted fields stay unchanged.
Cancel an orderCancel orderManagement API owns cancellation.
Add, update, or delete one lineCreate order line, Update order line, or Delete order lineLine operations change order contents without treating the whole order as a new record.
Change lifecycle stateUpdate order statusStatus changes have their own operation.
Read order history or linesGet order history or Get order linesThese are trusted Management API inspection routes.
Review orders by operator contextList orders by merchant userManagement API can filter orders by merchant user.
Read sales metricsGet sales metricsMetrics belong to Management API reporting by date range and granularity.
Let a signed-in customer read their ordersList orders for authenticated user, Get order by ID for authenticated user, or Get order by reference for authenticated userAuth API owns account-scoped customer order reads for the bearer user.
Let a service-token app look up an orderList all orders for an app, Get order by ID for an app, or Get order by reference for an appAuth API exposes read-only app lookup routes for service-token workflows.

For exact methods, paths, request bodies, response fields, enum values, and status codes, use the Orders reference.

How to choose order routes

Order work falls into two common caller models:

  • Management API handles trusted order creation, order updates, cancellation, line changes, order history, order-line reads, merchant-user filtering, and sales metrics.
  • Auth API handles read-only order lookup for the signed-in customer or an app-scoped service token.

Do not use Auth order reads to perform back-office order mutation. Do not expose Management API keys to browser-only customer account flows.

Behavior to know

Management order operations own trusted order writes. Create requires source, country_code, currency_code, language_code, grand_total, reference, status, and at least one line. Each line must carry a product ID, variant ID, quantity of at least 1, currency code, base price amount, and total price amount. Product and variant IDs are validated before the order line is stored.

Order status values are limited to placed, refunded, compensated, released, delivered, and cancelled. Order creation, order updates, cancellation, line writes, and status updates record history entries and publish order update events after the write path completes.

Create order currently upserts by app and order reference. If the same reference is submitted again for the same app, the order row is updated rather than creating a second order with that reference. Treat reference as the idempotency boundary for trusted order ingestion.

Order update accepts order-level fields independently from line changes. Omitted order-level fields stay unchanged. If lines is supplied on Management order update, the write replaces the order's line set: it deletes the existing lines and writes the supplied lines. Omit lines when changing only order-level fields, or use the order-line endpoints for targeted line changes.

Cancel order is a lifecycle change, not a hard delete. It sets the order status to cancelled, writes a cancellation history entry, publishes the order event, and leaves the order retrievable.

Management sales metrics require start_date and end_date in YYYY-MM-DD form. Metrics default to hourly buckets; use granularity=day when reporting should group by day.

Auth API order reads are read-only. Authenticated customer reads are scoped to the current user and cap limit at 20. App lookup reads are app-scoped, cap limit at 50, and support email, reference, product_sku, variant_sku, and RFC3339 created_after filters.

Order events

Use Events when another system needs to react after order data changes. The Event catalog exposes two order event types:

  • order.updated
  • order.deleted

order.updated uses the Order Payload schema. Its top-level required fields include order status, ID, source, order date, currency and language context, session and country context, totals, reference, payment method fields, shipping methods, billing and shipping addresses, discounts, order lines, created time, and merchant information.

order.deleted uses the Order Deleted Payload schema and carries the required order_id field.

Use the Event catalog for exact event type strings, payload schema IDs, required fields, and top-level payload fields. Use the Events guide for delivery, retry, and receiver-authentication behavior.

Route selection

Create or change an order through Management API, then open Orders reference.

Show a signed-in customer their order history through Auth API and the Auth-owned read operations in Orders reference.

Add, update, or delete a line with the order-line operations under Orders reference. Move an order through fulfillment with Update order status.

React in another system after an order changes with Events and Event catalog.

Where to go next

Orders and order lines

# Orders and order lines Start here when your integration touches orders and you need to know whether the job belongs to trusted back-office order operations, customer account reads, or event-driven downstream work. ## The short model An **order** is the placed commerce record. It carries the customer, addresses, totals, payment and shipping context, order status, merchant context, and the order lines that explain what was bought. An **order line** is one purchased item inside the order. Line operations are for changing the contents of an order after the order record exists. An **order status** is the lifecycle state of the order. Status changes are separate from editing addresses, totals, line contents, or merchant metadata. Use the surface that matches the change: - Use the order record when the whole order changes or needs to be inspected. - Use order-line operations when the contents of an existing order change. - Use order-status operations when the fulfillment or lifecycle state changes. - Use order events when another system needs to react after the order changes. ## Choose the right surface Order work can run in several places. Choose the route by job: | Job | Use | Why | | --- | --- | --- | | Create an order from a trusted integration | [Create order](/reference/orders/create-order) | Management API owns back-office order creation and requires initial line data. | | Edit order-level fields | [Update order](/reference/orders/update-order) | Management API owns trusted order updates. Omitted fields stay unchanged. | | Cancel an order | [Cancel order](/reference/orders/cancel-order) | Management API owns cancellation. | | Add, update, or delete one line | [Create order line](/reference/orders/create-order-line), [Update order line](/reference/orders/update-order-line), or [Delete order line](/reference/orders/delete-order-line) | Line operations change order contents without treating the whole order as a new record. | | Change lifecycle state | [Update order status](/reference/orders/update-order-status) | Status changes have their own operation. | | Read order history or lines | [Get order history](/reference/orders/get-order-history) or [Get order lines](/reference/orders/get-order-lines) | These are trusted Management API inspection routes. | | Review orders by operator context | [List orders by merchant user](/reference/orders/list-orders-by-merchant-user) | Management API can filter orders by merchant user. | | Read sales metrics | [Get sales metrics](/reference/orders/get-sales-metrics) | Metrics belong to Management API reporting by date range and granularity. | | Let a signed-in customer read their orders | [List orders for authenticated user](/reference/orders/list-orders-for-authenticated-user), [Get order by ID for authenticated user](/reference/orders/get-order-by-id-for-authenticated-user), or [Get order by reference for authenticated user](/reference/orders/get-order-by-reference-for-authenticated-user) | Auth API owns account-scoped customer order reads for the bearer user. | | Let a service-token app look up an order | [List all orders for an app](/reference/orders/list-all-orders-for-an-app), [Get order by ID for an app](/reference/orders/get-order-by-id-for-an-app), or [Get order by reference for an app](/reference/orders/get-order-by-reference-for-an-app) | Auth API exposes read-only app lookup routes for service-token workflows. | For exact methods, paths, request bodies, response fields, enum values, and status codes, use the [Orders reference](/reference/orders). ## How to choose order routes Order work falls into two common caller models: - **Management API** handles trusted order creation, order updates, cancellation, line changes, order history, order-line reads, merchant-user filtering, and sales metrics. - **Auth API** handles read-only order lookup for the signed-in customer or an app-scoped service token. Do not use Auth order reads to perform back-office order mutation. Do not expose Management API keys to browser-only customer account flows. ## Behavior to know Management order operations own trusted order writes. Create requires `source`, `country_code`, `currency_code`, `language_code`, `grand_total`, `reference`, `status`, and at least one line. Each line must carry a product ID, variant ID, quantity of at least 1, currency code, base price amount, and total price amount. Product and variant IDs are validated before the order line is stored. Order status values are limited to `placed`, `refunded`, `compensated`, `released`, `delivered`, and `cancelled`. Order creation, order updates, cancellation, line writes, and status updates record history entries and publish order update events after the write path completes. Create order currently upserts by app and order reference. If the same reference is submitted again for the same app, the order row is updated rather than creating a second order with that reference. Treat `reference` as the idempotency boundary for trusted order ingestion. Order update accepts order-level fields independently from line changes. Omitted order-level fields stay unchanged. If `lines` is supplied on Management order update, the write replaces the order's line set: it deletes the existing lines and writes the supplied lines. Omit `lines` when changing only order-level fields, or use the order-line endpoints for targeted line changes. Cancel order is a lifecycle change, not a hard delete. It sets the order status to `cancelled`, writes a cancellation history entry, publishes the order event, and leaves the order retrievable. Management sales metrics require `start_date` and `end_date` in `YYYY-MM-DD` form. Metrics default to hourly buckets; use `granularity=day` when reporting should group by day. Auth API order reads are read-only. Authenticated customer reads are scoped to the current user and cap `limit` at 20. App lookup reads are app-scoped, cap `limit` at 50, and support `email`, `reference`, `product_sku`, `variant_sku`, and RFC3339 `created_after` filters. ## Order events Use Events when another system needs to react after order data changes. The Event catalog exposes two order event types: - `order.updated` - `order.deleted` `order.updated` uses the Order Payload schema. Its top-level required fields include order status, ID, source, order date, currency and language context, session and country context, totals, reference, payment method fields, shipping methods, billing and shipping addresses, discounts, order lines, created time, and merchant information. `order.deleted` uses the Order Deleted Payload schema and carries the required `order_id` field. Use the [Event catalog](/events/catalog) for exact event type strings, payload schema IDs, required fields, and top-level payload fields. Use the [Events guide](/events/latest) for delivery, retry, and receiver-authentication behavior. ## Route selection Create or change an order through [Management API](/apis/management/latest), then open [Orders reference](/reference/orders). Show a signed-in customer their order history through [Auth API](/apis/auth/latest) and the Auth-owned read operations in [Orders reference](/reference/orders). Add, update, or delete a line with the order-line operations under [Orders reference](/reference/orders). Move an order through fulfillment with [Update order status](/reference/orders/update-order-status). React in another system after an order changes with [Events](/events) and [Event catalog](/events/catalog). ## Where to go next - Need exact order endpoints? Use [Orders reference](/reference/orders). - Need trusted API placement and API-key guidance? Read [Management API latest](/apis/management/latest). - Need customer/account order reads? Read [Auth API latest](/apis/auth/latest). - Need event delivery guidance? Read [Events latest](/events/latest).