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 and invoices: 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.

Endpoints

GET /api/v1/orders

List all orders for the tenant

get

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/orders

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Query parameters

limitinteger · min: 1 · max: 100Optional

Max items to return (1–100, default 20)

Default: 20

offsetintegerOptional

Number of items to skip (default 0)

Default: 0

sortstringOptional

Field to sort by

sortDirstring · enumOptional

Sort direction

Default: ascPossible values:

statusstringOptional

Filter by status

Responses

200

Paginated list of orders

401

API key missing or invalid

application/json

get/orders

HTTPcURLJavaScriptPython

GET /api/v1/orders HTTP/1.1
Host: peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

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

Create a new order

post

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/orders

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Header parameters

Idempotency-KeystringOptional

Idempotency key to safely retry without creating duplicates

Body

application/json

cartIdstringOptional

When set, the order is built from this cart and its offer discount is enforced against the tenant's discount_cap policy

contactIdstringOptional

organizationIdstringOptional

itemsarrayOptional

totalCentsintegerOptional

currencystringOptional

Responses

201

Order created

No content

400

Validation error

application/json

403

Policy violation (e.g. discount exceeds the tenant cap)

application/json

404

Cart not found

application/json

post/orders

HTTPcURLJavaScriptPython

POST /api/v1/orders HTTP/1.1
Host: peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 104

{
  "cartId": "text",
  "contactId": "text",
  "organizationId": "text",
  "items": [],
  "totalCents": 1,
  "currency": "text"
}

No content

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) and the API records the negotiated total verbatim.

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}

Get order details

get

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/orders/{id}

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Path parameters

idstringRequired

Responses

200

Order details

No content

get/orders/{id}

HTTPcURLJavaScriptPython

GET /api/v1/orders/{id} HTTP/1.1
Host: peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

200

Order details

No content

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}

Update order status or details

patch

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/orders/{id}

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Path parameters

idstringRequired

Body

application/json

statusstringOptional

itemsarrayOptional

totalCentsintegerOptional

Responses

200

Order updated

No content

patch/orders/{id}

HTTPcURLJavaScriptPython

PATCH /api/v1/orders/{id} HTTP/1.1
Host: peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 43

{
  "status": "text",
  "items": [],
  "totalCents": 1
}

200

Order updated

No content

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.