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

# Orders

> List and read orders for your merchant account

## GET /v1/orders

List orders for the organization the API key belongs to. Results are paginated and can be filtered by status, product, provider, and date range.

### Request

```bash theme={null}
curl "https://merchant-api-prod.anyway.sh/v1/orders?page=1&size=20&status=Paid" \
  -H "X-API-Key: ak_YOUR_API_KEY"
```

### Query Parameters

| Param                | Type    | Default | Description                                                                                                         |
| -------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| `page`               | integer | `1`     | Page number                                                                                                         |
| `size`               | integer | `20`    | Page size (max 100)                                                                                                 |
| `status`             | string  | —       | Filter by **display** status (e.g. `Paid`, `Pending`, `Refunded`) — matches the `displayStatus` field, not `status` |
| `product_id`         | string  | —       | Filter to a single product                                                                                          |
| `provider`           | string  | —       | Filter by payment provider: `STRIPE` or `CRYPTO`                                                                    |
| `from_address`       | string  | —       | Filter crypto orders by buyer wallet address                                                                        |
| `merchant_reference` | string  | —       | Filter by your correlation ID (contains-match)                                                                      |
| `date_from`          | integer | —       | Unix timestamp lower bound for `createdAt`                                                                          |
| `date_to`            | integer | —       | Unix timestamp upper bound for `createdAt`                                                                          |

### Response

```json theme={null}
{
  "success": true,
  "message": "Orders retrieved",
  "data": {
    "records": [
      {
        "id": "ORD25A7BK3NX9QRZ4",
        "status": "PAID",
        "displayStatus": "Paid",
        "amountCents": 1000,
        "currency": "USDC",
        "customerId": "CRYPTO_PAYER",
        "productId": "PRD25XWPQ8TN2VHK6",
        "productName": "API Credits — Starter",
        "disputed": false,
        "refunded": false,
        "txHash": "0xabc123def456abc123def456abc123def456abc123def456abc123def456abc1",
        "fromAddress": "0x1234567890abcdef1234567890abcdef12345678",
        "chain": "base",
        "paymentLinkId": "PL25GHI789RST345",
        "merchantReference": "cart_8842",
        "createdAt": "2026-05-12T10:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "size": 20,
    "pages": 1
  }
}
```

### Response Fields

| Field                            | Type    | Description                                                                                                                                                                                                                      |
| -------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                             | string  | Order ID — `ORD` + 2-digit year + 12 uppercase chars.                                                                                                                                                                            |
| `status`                         | string  | Canonical status: `PENDING`, `PAID`, `FAILED`, `CANCELED`, or `REFUNDED`.                                                                                                                                                        |
| `displayStatus`                  | string  | Human-facing status: `Pending`, `Paid`, `Processing`, `Failed`, `Canceled`, `Disputed`, `Refunded`, `Partially Refunded`, `Action Required`, `Authorized`, `Incomplete`. The `status` query parameter filters on **this** value. |
| `amountCents`                    | integer | Amount in minor units (cents). `1000` = 10.00 USDC.                                                                                                                                                                              |
| `currency`                       | string  | Settlement currency, e.g. `USDC`.                                                                                                                                                                                                |
| `customerId`                     | string  | Customer ID, or `CRYPTO_PAYER` / `X402_PAYER` / `CREDITS_PAYER` for crypto, on-chain x402, and credit-funded orders.                                                                                                             |
| `customerEmail`                  | string? | Buyer email when known; omitted otherwise.                                                                                                                                                                                       |
| `productId`                      | string? | Product ID (`PRD…`); omitted when unset.                                                                                                                                                                                         |
| `productName`                    | string? | Product name; omitted when unset.                                                                                                                                                                                                |
| `disputed`                       | boolean | Whether the order is under dispute.                                                                                                                                                                                              |
| `refunded`                       | boolean | Whether the order was refunded.                                                                                                                                                                                                  |
| `amountRefunded`                 | integer | Refunded amount in cents; omitted when `0`.                                                                                                                                                                                      |
| `txHash`, `fromAddress`, `chain` | string? | On-chain settlement details; populated only for crypto / x402 orders, omitted otherwise.                                                                                                                                         |
| `paymentLinkId`                  | string? | Originating payment link (`PL…`); omitted when unset.                                                                                                                                                                            |
| `merchantReference`              | string? | Your correlation ID, set when the order was created. Filterable via `merchant_reference`.                                                                                                                                        |
| `createdAt`                      | string  | RFC 3339 UTC timestamp.                                                                                                                                                                                                          |

List records do **not** include `provider`, `providerPaymentId`, or `providerStatus` — fetch a single order to get those.

***

## GET /v1/orders/:id

Get a single order, including the underlying provider payment details.

### Request

```bash theme={null}
curl https://merchant-api-prod.anyway.sh/v1/orders/ORD25A7BK3NX9QRZ4 \
  -H "X-API-Key: ak_YOUR_API_KEY"
```

### Path Parameters

| Param | Type   | Description              |
| ----- | ------ | ------------------------ |
| `id`  | string | The order ID to retrieve |

### Response

```json theme={null}
{
  "success": true,
  "message": "Order retrieved",
  "data": {
    "id": "ORD25A7BK3NX9QRZ4",
    "status": "PAID",
    "displayStatus": "Paid",
    "amountCents": 1000,
    "currency": "USDC",
    "customerId": "CRYPTO_PAYER",
    "productId": "PRD25XWPQ8TN2VHK6",
    "productName": "API Credits — Starter",
    "disputed": false,
    "refunded": false,
    "txHash": "0xabc123def456abc123def456abc123def456abc123def456abc123def456abc1",
    "fromAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "chain": "base",
    "paymentLinkId": "PL25GHI789RST345",
    "merchantReference": "cart_8842",
    "createdAt": "2026-05-12T10:00:00Z",
    "provider": "CRYPTO",
    "providerStatus": "confirmed"
  }
}
```

A single order returns every list field plus the upstream payment-provider details:

| Field               | Type    | Description                                                                                    |
| ------------------- | ------- | ---------------------------------------------------------------------------------------------- |
| `provider`          | string  | Payment provider: `STRIPE`, `CRYPTO`, `X402`, or `CREDITS`.                                    |
| `providerPaymentId` | string? | Upstream payment ID (e.g. Stripe `PaymentIntent`); omitted for on-chain orders.                |
| `providerStatus`    | string? | Upstream status — Stripe `PaymentIntent` status, or chain settlement status for crypto orders. |

### Errors

| Status | Description                                                   |
| ------ | ------------------------------------------------------------- |
| `401`  | API key missing or invalid.                                   |
| `404`  | Order does not exist or does not belong to your organization. |