> Documentation index: https://docs.sellhidden.com/llms.txt

# Orders

Source: https://docs.sellhidden.com/reference/orders

Orders are created by buyers at checkout. The API reads them and runs the same actions as the dashboard: approve or reject a manual payment, cancel, redeliver, resend the receipt, refund to store balance, keep a private note. Every order has a short reference in `publicRef` (for example `7K2Q-9XHD`, or `NOVA-7K2Q-9XHD` when the store has an order ID prefix): it is what buyers see on their order page and receipts, and it works wherever `{id}` appears in an order path, next to the long `id`.

## Endpoints

10 endpoints · [orders:read](https://docs.sellhidden.com/start?scope=orders%3Aread#scopes) · [orders:write](https://docs.sellhidden.com/start?scope=orders%3Awrite#scopes)

Base URL https://api.sellhidden.com/v1 · Authorization: Bearer · 120/min per key · cursor pagination · Idempotency-Key on POST · No test mode

### GET /orders — List orders

Scope `orders:read`.

**Query parameters**

| Query parameters | Type | Description |
| --- | --- | --- |
| `status` | string | pending, awaiting_verification, paid, delivered, cancelled, underpaid, oversold, expired, failed, refunded. |
| `kind` | product \| topup | Product orders or buyer balance top-ups. |
| `email` | string | Buyer email contains this text. |
| `since` | ISO date | Created at or after. |
| `until` | ISO date | Created before. |
| `limit` | 1..100 | Page size. Default 25. |
| `cursor` | string | nextCursor from the previous page. |

```bash
curl https://api.sellhidden.com/v1/orders \
  -H "Authorization: Bearer hsk_live_…"
```

### GET /orders/{id} — Get an order

{id} is the order's `publicRef` (any case, hyphen optional) or its long id. Scope `orders:read`.

```bash
curl https://api.sellhidden.com/v1/orders/ID \
  -H "Authorization: Bearer hsk_live_…"
```

Response (200):

```json
{ "order": { "id": "clx…", "publicRef": "7K2Q-9XHD", "status": "delivered", … } }
```

### POST /orders/{id}/approve — Approve a manual payment

Marks the order as paid and delivers it. A manual-method claim is verified (the platform fee is debited from your balance); a crypto order that received part of its total is settled on what arrived; any other payable order is settled as paid outside the platform, which needs `confirmOutsidePlatform: true` while its invoice is still open (409 invoice_open otherwise). Scope `orders:write`. Accepts `Idempotency-Key`.

**Body**

| Body | Type | Description |
| --- | --- | --- |
| `confirmOutsidePlatform` | boolean | The buyer paid you directly, outside the platform. |

```bash
curl -X POST \
  https://api.sellhidden.com/v1/orders/ID/approve \
  -H "Authorization: Bearer hsk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'
```

Response (200):

```json
{ "ok": true, "credited": 0, "feeDebited": 0.95, "warning": null, "order": { "id": "clx…", "status": "delivered", … } }
```

### POST /orders/{id}/reject — Reject a manual payment

Cancels a manual-method order with the reason; the buyer is emailed. Scope `orders:write`. Accepts `Idempotency-Key`.

**Body**

| Body | Type | Description |
| --- | --- | --- |
| `reason` | string | Up to 500 characters, shown to the buyer. |

```bash
curl -X POST \
  https://api.sellhidden.com/v1/orders/ID/reject \
  -H "Authorization: Bearer hsk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"reason":"No payment received."}'
```

### POST /orders/{id}/cancel — Cancel an order

Pending, awaiting-verification, underpaid or expired orders. An order holding a partial crypto payment answers 409 partial_payment: approve or refund it instead. Scope `orders:write`. Accepts `Idempotency-Key`.

**Body**

| Body | Type | Description |
| --- | --- | --- |
| `reason` | string | Private, up to 500 characters. |

```bash
curl -X POST \
  https://api.sellhidden.com/v1/orders/ID/cancel \
  -H "Authorization: Bearer hsk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'
```

### POST /orders/{id}/redeliver — Run delivery again

For a paid order with items still not delivered (oversold, failed). 409 already_delivered when everything was delivered: resend the receipt instead. Scope `orders:write`. Accepts `Idempotency-Key`.

```bash
curl -X POST \
  https://api.sellhidden.com/v1/orders/ID/redeliver \
  -H "Authorization: Bearer hsk_live_…" \
  -H "Idempotency-Key: $(uuidgen)"
```

Response (200):

```json
{ "ok": true, "delivered": 2, "failed": 0, "order": { … } }
```

### POST /orders/{id}/resend-receipt — Resend the receipt

Emails the buyer their receipt and items again. Paid orders only; 3 per order and 60 per store per hour. Scope `orders:write`. Accepts `Idempotency-Key`.

```bash
curl -X POST \
  https://api.sellhidden.com/v1/orders/ID/resend-receipt \
  -H "Authorization: Bearer hsk_live_…" \
  -H "Idempotency-Key: $(uuidgen)"
```

### POST /orders/{id}/refund — Refund to store balance

The buyer receives store credit. A paid order is refunded in full or for `amountUsd`; an underpaid or expired order with a partial crypto payment hands over everything that arrived. Scope `orders:write`. Accepts `Idempotency-Key`.

**Body**

| Body | Type | Description |
| --- | --- | --- |
| `amountUsd` | number | Partial refund of a paid order; default: the full amount. |
| `reason` | string | Up to 500 characters. |

```bash
curl -X POST \
  https://api.sellhidden.com/v1/orders/ID/refund \
  -H "Authorization: Bearer hsk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"reason":"Duplicate purchase."}'
```

Response (200):

```json
{ "ok": true, "creditedUsd": 29, "order": { "id": "clx…", "status": "refunded", … } }
```

### PUT /orders/{id}/note — Write the private note

A note only you see (API and dashboard, as `order.note`). POST works the same. Scope `orders:write`.

**Body**

| Body | Type | Description |
| --- | --- | --- |
| `note` (required) | string | Up to 2,000 characters. |

```bash
curl -X PUT https://api.sellhidden.com/v1/orders/ID/note \
  -H "Authorization: Bearer hsk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"note":"Verified by hand on 2026-10-01."}'
```

### DELETE /orders/{id}/note — Remove the private note

Scope `orders:write`.

```bash
curl -X DELETE \
  https://api.sellhidden.com/v1/orders/ID/note \
  -H "Authorization: Bearer hsk_live_…"
```