Skip to content
hidden

API 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.

10 endpointsorders:readorders:write

Endpoints

Base URL https://api.sellhidden.com/v1Authorization: Bearer120/min per keycursor paginationIdempotency-Key on POSTNo test mode

GET/ordersorders:read

List orders.

Query parameters
Query parametersTypeDescription
statusType: stringpending, awaiting_verification, paid, delivered, cancelled, underpaid, oversold, expired, failed, refunded.
kindType: product | topupProduct orders or buyer balance top-ups.
emailType: stringBuyer email contains this text.
sinceType: ISO dateCreated at or after.
untilType: ISO dateCreated before.
limitType: 1..100Page size. Default 25.
cursorType: stringnextCursor from the previous page.
curl https://api.sellhidden.com/v1/orders \
  -H "Authorization: Bearer hsk_live_…"

GET/orders/{id}orders:read

Get an order. {id} is the order's publicRef (any case, hyphen optional) or its long id.

curl https://api.sellhidden.com/v1/orders/ID \
  -H "Authorization: Bearer hsk_live_…"
200 OKjson
{ "order": { "id": "clx…", "publicRef": "7K2Q-9XHD", "status": "delivered", … } }

POST/orders/{id}/approveorders:writeIdempotency-Key

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).

Body
BodyTypeDescription
confirmOutsidePlatformType: booleanThe buyer paid you directly, outside the platform.
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 '{}'
200 OKjson
{ "ok": true, "credited": 0, "feeDebited": 0.95, "warning": null, "order": { "id": "clx…", "status": "delivered", … } }

POST/orders/{id}/rejectorders:writeIdempotency-Key

Reject a manual payment. Cancels a manual-method order with the reason; the buyer is emailed.

Body
BodyTypeDescription
reasonType: stringUp to 500 characters, shown to the buyer.
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}/cancelorders:writeIdempotency-Key

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.

Body
BodyTypeDescription
reasonType: stringPrivate, up to 500 characters.
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}/redeliverorders:writeIdempotency-Key

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.

curl -X POST \
  https://api.sellhidden.com/v1/orders/ID/redeliver \
  -H "Authorization: Bearer hsk_live_…" \
  -H "Idempotency-Key: $(uuidgen)"
200 OKjson
{ "ok": true, "delivered": 2, "failed": 0, "order": { … } }

POST/orders/{id}/resend-receiptorders:writeIdempotency-Key

Resend the receipt. Emails the buyer their receipt and items again. Paid orders only; 3 per order and 60 per store per hour.

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

POST/orders/{id}/refundorders:writeIdempotency-Key

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.

Body
BodyTypeDescription
amountUsdType: numberPartial refund of a paid order; default: the full amount.
reasonType: stringUp to 500 characters.
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."}'
200 OKjson
{ "ok": true, "creditedUsd": 29, "order": { "id": "clx…", "status": "refunded", … } }

PUT/orders/{id}/noteorders:write

Write the private note. A note only you see (API and dashboard, as order.note). POST works the same.

Body
BodyTypeDescription
noterequiredType: stringUp to 2,000 characters.
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}/noteorders:write

Remove the private note. 

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

Get help

Send us the endpoint, the request or delivery id and the response you got. Security findings go through responsible disclosure. Live platform status is on the support page.

Developer supportSystem status

See also