Pre-orders

When a product is sold out, add preorder=1 to the buy. You pay now, the order is filled oldest first when stock returns, and until then you can cancel it for a full refund.

Place one

curl -X POST \  "https://www.nfa.pub/api/v1/cs2?type=prime&quantity=2&preorder=1&result=json" \  -H "X-Api-Key: rsk_..." \  -H "Idempotency-Key: order-1182"

{  "ok": true,  "order_id": "4b53000e7b4677d2-c69a8e94132d75e8",  "state": "preorder",  "preorder": true,  "quantity": 2,  "accounts": [],  "count": 0,  "charged_eur": 0.9,  "deliveryWindow": null,  "cached": false}

• It only becomes a pre-order when the shelf is empty. With any stock, preorder=1 changes nothing: you get accounts, or E1501 if you asked for more than there is.
• charged_eur is taken now, at the price a normal buy charges.
• In text the body is the word preorder, and the order id is in the X-Order-Id header.
• At most 10 accounts and one product per pre-order (E1505), and only while pre-orders are switched on (E1504).
• Everything that protects a normal buy applies: your balance (E1401), your API protection limits and Idempotency-Key. Read-only keys cannot place one.

Delivery hours

Add deliver_from, deliver_to and tz to be filled only inside those hours. The warranty starts at delivery, so this keeps a pre-order from landing while you sleep.

curl -X POST \  "https://www.nfa.pub/api/v1/cs2?type=prime&quantity=2&preorder=1&deliver_from=09:00&deliver_to=23:00&tz=Europe/Berlin" \  -H "X-Api-Key: rsk_..." \  -H "Idempotency-Key: order-1183"

• HH:MM, 24-hour, at least 2 hours apart. An end before the start runs past midnight, so 22:00 to 02:00 works.
• tz is an IANA time zone such as Europe/Berlin.
• All three or none. Anything else is refused with E1105 before anything is charged.
• Change or clear them later with POST /preorder/hours.

How they are filled

• The queue runs every few minutes and serves whoever has waited longest first, website and API pre-orders alike.
• With hours set, an order is only filled while they are open. Outside them it keeps its place.
• If only part of it comes back in stock, you get that part, and the order stays a pre-order (state partial) until the rest arrives or you cancel.
• A pre-order is never given up on. If the supplier fails when its turn comes, it stays paid and waiting for the next run.
• Rarely, preorder=1 still ends in E1501: stock looked available, so it was bought as a normal order, but the supplier had nothing. The charge is reversed in full.

Supplier checks paused

When the supplier's account checks are down for a product, /stock shows it as paused. A buy without preorder=1 is refused with E1506 and a Retry-After header, before anything is charged. With preorder=1 it becomes a pre-order, exactly as if it were sold out.

Follow it

• GET /order shows its state. The accounts appear once it is delivered.
• GET /orders?state=preorder lists the ones still waiting.
• Webhooks: preorder.created, preorder.delivered and order.refunded.

Cancel

POST /preorder/cancel refunds what was not delivered to the balance it was paid from, at once. It is safe to retry: a pre-order is refunded once, and a second cancel gets E1623.

curl -X POST "https://www.nfa.pub/api/v1/preorder/cancel" \  -H "X-Api-Key: rsk_..." \  -H "Content-Type: application/json" \  -d '{"order":"4b53000e7b4677d2-c69a8e94132d75e8"}'

{  "ok": true,  "order_id": "4b53000e7b4677d2-c69a8e94132d75e8",  "state": "refunded",  "refunded_eur": 0.9}