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

# Merchant orders

> List and update store orders with a Bearer API key.

All routes require:

```txt theme={null}
Authorization: Bearer mk_live_<your_key>
```

Paths are store-scoped. The key must include `order:read` or `order:update` **and** access to that shop. Dashboard permission ceilings still apply (`viewOrders` / `editOrders`).

## List

```http theme={null}
GET /api/merchant/v1/stores/{storeId}/orders
```

Scope: `order:read`

Query:

| Param | Description |
| - | - |
| `limit` | Page size, 1–100, default 50 |
| `cursor` | Opaque cursor from `nextCursor` |
| `status` | Exact status (`pending`, `paid`, `processing`, `completed`, …) |
| `from` | Created at ≥ ISO timestamp |
| `to` | Created at ≤ ISO timestamp |

```json theme={null}
{
  "orders": [
    {
      "id": "clxyz...",
      "orderId": "ORD-1001",
      "storeId": "cm...",
      "status": "pending",
      "productName": "Premium key",
      "price": 9.99,
      "paid": 0,
      "paymentMethod": "stripe",
      "customerEmail": "buyer@example.com",
      "country": "DE",
      "keyCount": 0,
      "createdAt": "2026-09-21T10:00:00.000Z",
      "completedAt": null,
      "updatedAt": "2026-09-21T10:00:00.000Z"
    }
  ],
  "limit": 50,
  "hasMore": false,
  "nextCursor": null
}
```

IP, user-agent, payment-provider secrets, and proof uploads are never returned.

```bash theme={null}
curl "https://dash.joinmarkt.com/api/merchant/v1/stores/{storeId}/orders?status=pending&limit=20" \
  -H "Authorization: Bearer mk_live_<your_key>" \
  -H "Accept: application/json"
```

## Get

```http theme={null}
GET /api/merchant/v1/stores/{storeId}/orders/{orderId}
```

Scope: `order:read`

`{orderId}` may be the cuid `id` or the public `ORD-…` value. An order that belongs to another shop returns `404`.

Detail adds seller `note` (human-readable only) and `customFieldResponses`. License key strings are not included — use dashboard fulfillment for that.

## Update

```http theme={null}
PATCH /api/merchant/v1/stores/{storeId}/orders/{orderId}
```

Scope: `order:update`

Only the mutations the dashboard already supports:

```json theme={null}
{
  "note": "Follow up with the buyer"
}
```

```bash theme={null}
curl -X PATCH "https://dash.joinmarkt.com/api/merchant/v1/stores/{storeId}/orders/{orderId}" \
  -H "Authorization: Bearer mk_live_<your_key>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d "{\"note\":\"Follow up with the buyer\"}"
```

* `note` — same as dashboard order note (`updateOrderNote`)
* `markDelivered: true` — same as fulfillment “mark delivered” (`paid` / `processing` / `completed` with deliverable content)

Arbitrary `status` values are rejected (`400`). Pending orders cannot be marked delivered. `markDelivered: false` is ignored as a no-op and returns `400`.

## Errors

| Status | Meaning |
| - | - |
| 400 | Invalid query, JSON, unsupported field, or fulfillment rules |
| 401 | Missing, invalid, expired, or revoked token |
| 403 | Scope or shop not allowed for this key |
| 404 | Order not in this store |
| 429 | Rate limit exceeded |

## Related

* [API keys](/developers/api-keys)
* [Merchant products](/api/merchant-products)
* [Merchant webhooks](/api/merchant-webhooks)
* [Orders](/api-reference/orders)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.