# Orders (/docs/api-reference/orders)

## List orders [#list-orders]

<EndpointHeader method="GET" path="/api/v5/merchant/orders" />

Scope: **`commerce.read`**

Returns orders where **you are the seller**, newest first. Buyer identity is deliberately left out; use the [`checkout.paid`](/docs/webhooks/events) webhook for shipping details.

### Query parameters [#query-parameters]

| Parameter | Type | Default | Notes |
|---|---|---|---|
| `limit` | integer | `25` | 1 to 100 |
| `before` | ISO 8601 | none | Return orders created before this time. Pass the previous response's `nextBefore`. |

```bash tab="curl"
curl "https://apps.apiswop.co/api/v5/merchant/orders?limit=25" \
  -H "Authorization: Bearer $SWOP_MERCHANT_KEY"
```

```js tab="Node"
const res = await fetch('https://apps.apiswop.co/api/v5/merchant/orders?limit=25', {
  headers: { Authorization: `Bearer ${process.env.SWOP_MERCHANT_KEY}` },
});
const { data } = await res.json(); // { orders, nextBefore }
```

```python tab="Python"
import os, requests

r = requests.get(
    "https://apps.apiswop.co/api/v5/merchant/orders",
    params={"limit": 25},
    headers={"Authorization": f"Bearer {os.environ['SWOP_MERCHANT_KEY']}"},
)
data = r.json()["data"]  # orders, nextBefore
```

### Response [#response]

```json
{
  "state": "success",
  "data": {
    "orders": [
      {
        "orderId": "ORD-…",
        "status": "paid",
        "orderType": "physical",
        "lineItems": [ { "productId": "66a1…", "name": "Swop Classic Card", "quantity": 1, "unitAmount": 25, "totalAmount": 25 } ],
        "financial": { "subtotal": 25, "shippingCost": 5, "totalCost": 30, "currency": "USDC" },
        "payment": {
          "status": "completed",
          "paidAt": "2026-10-29T18:01:05.000Z",
          "amount": 30,
          "validation": { "details": { "receivedAmount": 30 } }
        },
        "settlement": { "status": "held" },
        "fulfillment": {
          "status": "pending",
          "requiresShipping": true,
          "shippedAt": null,
          "trackingNumber": "",
          "carrier": "",
          "estimatedDeliveryDate": null
        },
        "createdAt": "2026-10-29T18:01:05.000Z"
      }
    ],
    "nextBefore": "2026-10-29T18:01:05.000Z"
  }
}
```

{/* TODO(review): example values illustrative; lineItems and financial objects are returned whole from the order model and may carry more fields than shown. */}

### Fields [#fields]

| Field | Meaning |
|---|---|
| `orderId` | Swop's order ID |
| `status` | `created`, `paid`, `fulfilling`, `completed`, `cancelled`, `failed` |
| `orderType` | `digital`, `physical`, `in_person_checkout`, `mixed` |
| `lineItems[]` | What was bought |
| `financial` | `subtotal`, `shippingCost`, `totalCost`, `currency` (USDC) |
| `payment.status` | `pending`, `completed`, `failed`, `refunded`, `cancelled` |
| `payment.paidAt`, `payment.amount` | When and how much the buyer paid |
| `payment.validation.details.receivedAmount` | The amount that actually arrived on-chain |
| `settlement.status` | Your payout: `pending`, `held`, `release_pending`, `releasing`, `released`, `failed`, `refunded` |
| `fulfillment.*` | Shipping status and tracking |
| `nextBefore` | Cursor for the next page, or `null` at the end |
