> ## Documentation Index
> Fetch the complete documentation index at: https://docs-alpha.pepay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Orders

> Order listing, retrieval, and cancellation endpoints.

## Overview

Orders represent the commerce purchase lifecycle after checkout. Use these endpoints to list orders, retrieve order snapshots, and cancel when supported.

## Authentication

Merchant endpoints (merchant backend, commerce scope):

* `x-commerce-api-key: ck_...`, or
* `Authorization: Bearer <jwt>` (dashboard/user context)

## Request

Merchant endpoints:

* `GET /api/commerce/merchant/orders`
* `GET /api/commerce/merchant/orders/{orderId}`
* `POST /api/commerce/merchant/orders/{orderId}/cancel`

Example (merchant list):

```bash theme={null}
BASE_URL=${PEPAY_API_URL}

curl "$BASE_URL/api/commerce/merchant/orders?limit=1&offset=0" \
  -H "x-commerce-api-key: ck_..."
```

## Response

Representative list response:

```json theme={null}
{
  "success": true,
  "data": {
    "orders": [
      {
        "orderId": "550e8400-e29b-41d4-a716-446655440111",
        "invoiceId": "550e8400-e29b-41d4-a716-446655440000",
        "networkEnvironment": "devnet",
        "status": "processing",
        "substatus": null,
        "actions": { "canCancel": false },
        "shipmentsSummary": { "hasTracking": false, "isDelivered": false, "lastTrackingAt": null, "shipmentCount": 0 },
        "retailer": "amazon",
        "walletAddress": "0x0000000000000000000000000000000000000001",
        "walletNetwork": "bsc",
        "customerId": "cust_123456",
        "total": 99.99,
        "createdAt": 1766320496,
        "updatedAt": 1766320496,
        "itemCount": 1
      }
    ],
    "pagination": { "limit": 1, "offset": 0, "count": 1 }
  }
}
```

## Errors

* `401` missing/invalid auth
* `404` order not found
* `400` cancellation not allowed or invalid request

## Examples

Example (retrieve order snapshot):

```bash theme={null}
BASE_URL=${PEPAY_API_URL}

curl "$BASE_URL/api/commerce/merchant/orders/550e8400-e29b-41d4-a716-446655440111" \
  -H "x-commerce-api-key: ck_..."
```

Next: [Payments](/api-spec/commerce/payments)