> 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/reference-pages/orders.md).

# Orders

Orders capture commerce transactions — purchases, plan changes, add-on attaches.

* [`GET /api/v1/orders`](#get-apiv1orders) — list
* [`POST /api/v1/orders`](#post-apiv1orders) — create
* [`GET /api/v1/orders/{id}`](#get-apiv1ordersid) — retrieve
* [`PATCH /api/v1/orders/{id}`](#patch-apiv1ordersid) — update

***

## `GET /api/v1/orders`

List orders in this tenant.

* **Auth scope:** `read`

### Response `200`

```json
{
  "data": [
    {
      "id": "ord_01H...",
      "tenantId": "ten_01H...",
      "orderNumber": "ORD-1714672883000",
      "status": "draft",
      "items": [{ "productId": "prod_01H...", "quantity": 2 }],
      "totalCents": 9800,
      "currency": "USD",
      "createdAt": "2026-05-02T14:01:23Z"
    }
  ],
  "nextActions": [
    { "rel": "createOrder", "method": "POST", "href": "/api/v1/orders" }
  ]
}
```

### cURL

```bash
curl -H "Authorization: Bearer $PEAK_API_KEY" \
  https://api.example.com/api/v1/orders
```

***

## `POST /api/v1/orders`

Create an order. The platform:

1. Evaluates `order_create` policies. Any blocking policy returns `403`.
2. Resolves prices through the pricing engine for each line item with a modeled product.
3. If any line references a product with non-modeled (passthrough) charges, calls the active billing adapter's `quoteCart` to get an authoritative live quote. If the adapter lacks `quoteCart`, returns `502`.
4. Persists the order with the authoritative total (mixed-cart safe).

* **Auth scope:** `commerce`

### Body

| Field             | Type         | Required | Description                                                    |
| ----------------- | ------------ | -------- | -------------------------------------------------------------- |
| `contactId`       | UUID         | no       | Contact placing the order                                      |
| `organizationId`  | UUID         | no       | Account                                                        |
| `items`           | array        | no       | Line items (default `[]`)                                      |
| `totalCents`      | integer      | no       | Hint total (defaults to `0`); ignored when pricing rules apply |
| `currency`        | string (≤10) | no       | Defaults to `USD`                                              |
| `customerContext` | object       | no       | Passed to the pricing engine (segment, locale, partner)        |
| `journeyId`       | UUID         | no       | Journey that produced the order                                |

### Item shape

| Field        | Type    | Description                     |
| ------------ | ------- | ------------------------------- |
| `productId`  | UUID    | Product reference (recommended) |
| `quantity`   | integer | Defaults to `1`                 |
| `priceCents` | integer | Hint; resolved at server-side   |

### Response `201`

```json
{
  "data": {
    "id": "ord_01H...",
    "orderNumber": "ORD-1714672883000",
    "status": "draft",
    "items": [{ "productId": "prod_01H...", "quantity": 2 }],
    "totalCents": 9800,
    "currency": "USD",
    "metadata": {
      "source": "agent-api-v1",
      "pricingBreakdown": [
        {
          "productId": "prod_01H...",
          "listPriceCents": 4900,
          "resolvedPriceCents": 4900,
          "quantity": 2,
          "appliedRules": []
        }
      ]
    },
    "createdAt": "2026-05-02T14:01:23Z",
    "rulesApplied": {
      "policyEvaluations": [
        {
          "policyId": "pol_01H...",
          "policyName": "Max order amount",
          "policyType": "order_create",
          "result": "allow"
        }
      ],
      "pricingBreakdown": [/* same as above */],
      "applicableBusinessRules": [
        {
          "ruleId": "br_01H...",
          "ruleName": "Default upgrade",
          "direction": "upgrade",
          "changeTiming": "immediate",
          "prorationType": "prorated"
        }
      ],
      "note": "policyEvaluations were enforced during order creation; ..."
    }
  },
  "nextActions": [
    { "rel": "self", "method": "GET", "href": "/api/v1/orders/ord_01H..." },
    { "rel": "updateStatus", "method": "PATCH", "href": "/api/v1/orders/ord_01H..." }
  ]
}
```

### Errors

| Status | When                                                                  |
| ------ | --------------------------------------------------------------------- |
| `400`  | Validation failed                                                     |
| `403`  | Blocked by an `order_create` policy                                   |
| `502`  | Order needs a live billing-system quote and adapter cannot fulfill it |

### cURL

```bash
curl -X POST https://api.example.com/api/v1/orders \
  -H "Authorization: Bearer $PEAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_uuid",
    "items": [
      { "productId": "5f1c2d34-3b1f-4f9a-8c7c-2c3a4d5e6f70", "quantity": 2 }
    ],
    "currency": "USD"
  }'
```

***

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

Retrieve an order.

* **Auth scope:** `read`

### Response `200`

Same shape as `data` from `POST`, minus `rulesApplied` (the rules block is recorded at creation time only).

### Errors

| Status | When            |
| ------ | --------------- |
| `404`  | Order not found |

### cURL

```bash
curl -H "Authorization: Bearer $PEAK_API_KEY" \
  https://api.example.com/api/v1/orders/ord_01H...
```

***

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

Update an order's status, items, or total. Evaluates `order_update` policies first.

* **Auth scope:** `commerce`

### Body (all optional)

| Field        | Type         |
| ------------ | ------------ |
| `status`     | string (≤50) |
| `items`      | array        |
| `totalCents` | integer      |

### Response `200`

```json
{
  "data": { "id": "ord_01H...", "status": "completed", ... },
  "nextActions": [ /* order nextActions */ ]
}
```

### Errors

| Status | When                                |
| ------ | ----------------------------------- |
| `403`  | Blocked by an `order_update` policy |
| `404`  | Order not found                     |

### cURL

```bash
curl -X PATCH https://api.example.com/api/v1/orders/ord_01H... \
  -H "Authorization: Bearer $PEAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "completed" }'
```

***

## Related

* [Subscriptions](/developers/reference-pages/subscriptions.md)
* [Payments](/developers/reference-pages/payments.md)
* [Pricing previews](/developers/reference-pages/pricing-previews.md)


---

# 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/reference-pages/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.