> For the complete documentation index, see [llms.txt](https://docs.peakcommerce.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.peakcommerce.com/developers/api-groups/orders.md).

# Orders

The **Orders API** exposes the platform's local order ledger — the row that records "this customer agreed to buy these items at this total, on this date." Orders sit *upstream* of [subscriptions](/developers/api-groups/subscriptions.md) and [invoices](/developers/api-groups/invoices.md): a checkout flow typically writes an order first, then provisions the resulting subscription and emits the first invoice through the active billing adapter.

Orders are first-class platform records, not adapter pass-throughs. They are filed against either a `contactId` (individual buyer) or an `organizationId` (B2B account). The `items` array carries one entry per line item with `productId`, `quantity`, and `priceCents`. `status` is a free-form string driven by the order workflow (`draft`, `pending`, `confirmed`, `fulfilled`, `cancelled`, …); the API does not enforce a state machine, so callers and downstream consumers must agree on the vocabulary.

Writes require the `commerce` scope; reads require `read`. Every mutation (`order.create`, `order.update`) is recorded in the audit log and emits an event for subscribed [webhooks](/developers/api-groups/webhooks.md).

## Endpoints

### `GET /api/v1/orders`

{% openapi src="<https://api.peakcommerce.com/api/v1/openapi.json>" path="/orders" method="get" %}
<https://api.peakcommerce.com/api/v1/openapi.json>
{% endopenapi %}

Returns every order for the calling tenant in a single response (no cursor pagination yet). Suitable for back-office reconciliation and exports; for customer-facing lists, filter by `contactId` / `organizationId` client-side.

Requires the `read` scope.

### `POST /api/v1/orders`

{% openapi src="<https://api.peakcommerce.com/api/v1/openapi.json>" path="/orders" method="post" %}
<https://api.peakcommerce.com/api/v1/openapi.json>
{% endopenapi %}

Creates a local order row. Either `contactId` or `organizationId` should be set so the order is owned by an account; both are technically optional to support draft orders, but downstream consumers (commissions, reporting) assume one is present.

`items` is an array of `{ productId, quantity, priceCents }`. `totalCents` is **not** computed for you — it is whatever the caller submits. This is intentional: callers run their own pricing pipeline (often via [`GET /pricing/resolve`](/developers/api-groups/pricing.md)) and the API records the negotiated total verbatim.

When the body carries a `cartId`, the referenced cart is converted: the cart is marked `checked_out` and the resulting order completes immediately. A completed order also feeds platform usage metering (executed commerce value) asynchronously after the response is written; metering is opt-in per tenant and never affects the API result.

Requires the `commerce` scope. Returns `201` plus a `nextActions` hint pointing at `POST /subscriptions` (when the items include a subscription product) or `POST /payments` (for one-shot purchases).

### `GET /api/v1/orders/{id}`

{% openapi src="<https://api.peakcommerce.com/api/v1/openapi.json>" path="/orders/{id}" method="get" %}
<https://api.peakcommerce.com/api/v1/openapi.json>
{% endopenapi %}

Returns the full order row including `items`, totals, status, owner ids, and audit timestamps. Requires the `read` scope. Returns `404` when the id is not owned by the calling tenant.

### `PATCH /api/v1/orders/{id}`

{% openapi src="<https://api.peakcommerce.com/api/v1/openapi.json>" path="/orders/{id}" method="patch" %}
<https://api.peakcommerce.com/api/v1/openapi.json>
{% endopenapi %}

Partial-update; only fields supplied in the body are written. The most common use is advancing `status` (`pending` → `confirmed` → `fulfilled`). Updating `items` or `totalCents` after the order has been used to provision a subscription or invoice will *not* propagate the change to those downstream records — issue a credit note or compensating order instead.

Requires the `commerce` scope. Writes `order.update` to the audit log with a `before`/`after` diff in `details`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.peakcommerce.com/developers/api-groups/orders.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.