> ## 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

> List, retrieve, and cancel merchant orders.

## Overview

Orders represent the commerce lifecycle (placed/shipped/delivered/cancelled). Use these endpoints for merchant dashboards and operational tooling.

## Authentication

Requires `x-commerce-api-key`.

## Request

### List merchant orders

```ts theme={null}
const orders = await pepay.commerce.orders.list({ limit: 10 });
```

### Retrieve an order

```ts theme={null}
const order = await pepay.commerce.orders.retrieve('order_123');
```

### Cancel an order

```ts theme={null}
await pepay.commerce.orders.cancel(
  'order_123',
  { refundDestinationWalletAddressBsc: '0x1111111111111111111111111111111111111111' },
  { idempotencyKey: '123e4567-e89b-42d3-a456-556642440000' }
);
```

### Devnet order simulation (devnet only)

Use this to advance a devnet order through its lifecycle for integration testing and to trigger the same webhook + event stream updates you will receive in production.

```ts theme={null}
await pepay.commerce.devnet.simulateOrder('order_123', {
  transitionTo: 'payment_confirmed',
  walletNetwork: 'bsc',
  walletAddress: '0x0000000000000000000000000000000000000001'
});
```

#### How it works

* Requires a devnet commerce API key and only operates on orders created in `devnet`.
* Each simulation emits a `commerce.order.updated` merchant webhook event and a matching event on the commerce WebSocket stream.
* If the simulated transition changes the linked invoice state, corresponding `invoice.*` events are emitted as well.

#### Suggested end-to-end test flow

1. Create a devnet order + invoice via `commerce.checkout.createInvoice` (save `orderId` and `invoiceId`).
2. Configure webhooks or connect a WebSocket listener (examples below).
3. Simulate the happy path sequence:
   * `payment_confirmed`
   * `payment_settled`
   * `placed`
   * `shipped` (include `tracking`)
   * `delivery_confirmed`
4. Optionally test failure paths:
   * `failed` (only valid from `status=processing`)
   * `cancelled` (only valid from `status=placed`)
   * `refunded` (requires a valid BSC refund destination)

#### Webhook setup (merchant)

Configure webhooks in the dashboard (or via `/api/v1/webhooks/*`) to receive:

* `X-Pepay-Event: commerce.order.updated`
* `data.object.id` set to the orderId you simulated

#### WebSocket updates (commerce stream)

```ts theme={null}
const token = await pepay.ws.token.mint({ scope: 'commerce', ttlSeconds: 300 });
const stream = pepay.ws.connectCommerceEvents({
  token: String(token?.data?.token),
  format: 'event_v1',
  types: 'commerce.order.*'
});

stream.on('event', (event) => {
  if (event.type !== 'commerce.order.updated') return;
  if (event.data?.object?.id !== 'order_123') return;
  console.log('order update', event.data?.object);
});
```

## Response

Example merchant order snapshot (truncated):

```json theme={null}
{
  "success": true,
  "data": {
    "orderId": "550e8400-e29b-41d4-a716-446655440000",
    "invoiceId": "550e8400-e29b-41d4-a716-446655440111",
    "networkEnvironment": "devnet",
    "status": "placed",
    "substatus": "AWAITING_TRACKING",
    "actions": { "canCancel": true }
  }
}
```

## Errors

* `401` missing/invalid commerce API key
* `404` order not found
* `400` missing `Idempotency-Key` on cancel

## Examples

* When building an order dashboard, combine:
  * order snapshot (`orders.retrieve`)
  * payment status (`payments.status`)
  * invoice reconciliation (`merchantInvoices.status`)
    Next: [Payments](/sdk/commerce/payments)