Orders

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

• GET /api/v1/orders — list

• POST /api/v1/orders — create

• GET /api/v1/orders/{id} — retrieve

• PATCH /api/v1/orders/{id} — update

---

GET /api/v1/orders

List orders in this tenant.

• Auth scope: read

Response 200

{
  "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

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

{
  "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

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

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

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

Errors

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

cURL

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

• Payments

• Pricing previews