Orders: Creation, Idempotency, Status & Delivery

Creating an order

POST /api/v1/reseller/orders
Idempotency-Key: <a unique string you generate>
Content-Type: application/json

{
  "package_id": "...",
  "quantity": 1
}

Scope required: orders:write. The order debits your account's existing Brenoz wallet balance — there is no separate reseller billing relationship. Insufficient balance fails the same way it would for any other order.

Idempotency

Idempotency-Key is required, not optional. Replaying the exact same key with the exact same request body returns the original order unchanged — safe to retry after a network timeout. Replaying it with a different body (different package_id/quantity) is rejected with 409 orders.idempotency_payload_mismatch: the key identifies one order attempt, not a request-body cache.

A `201` response does not guarantee fulfillment

Order creation still goes through Brenoz's own live supplier availability check before it settles. A terminal failed status is itself returned as a normal 201 — the order resource genuinely exists and was billed even if it later fails; a refund is handled automatically by Brenoz's existing wallet-safety sweep. Poll the order or register a webhook to find out what actually happened.

Reading order status

GET /api/v1/reseller/orders                  # your own orders, cursor-paginated
GET /api/v1/reseller/orders/{order_id}
GET /api/v1/reseller/orders/{order_id}/delivery

Scope required: orders:read.

Delivery states

The delivery endpoint returns one of three mutually exclusive states — never collapsed into an empty 200 or a 404:

State	Meaning
`available`	Sanitized delivery content is ready
`pending`	No delivery yet — not an error, keep polling within the rate limit
`pending_manual_review`	A human must resolve this; polling alone will not change it