Documentation Index
Fetch the complete documentation index at: /llms.txt
Use this file to discover all available pages before exploring further.
The happy path, recovering a lost response, and a short fulfilment
| # | Call | Result |
|---|---|---|
| 1 | GET /catalog/products?country=IN | Cache canonical_sku and its denominations. |
| 2 | POST /orders | 202 { order_id, state: "PENDING" } |
| 3 | GET /orders/{order_id} | PENDING — wait 2–3 s and repeat. |
| 4 | GET /orders/{order_id} | FULFILLED, and voucher_count === qty. |
| 5 | GET /orders/{order_id}/vouchers | Parse each secret, store, deliver to the customer. |
POST /orders never returned. The order may or may not exist.
| # | Call | Then |
|---|---|---|
| 1 | GET /orders?partner_order_ref=ORD-10294 | If an order comes back, it was created — adopt its order_id and poll. |
| 2 | Empty list | Retry POST /orders with the same Idempotency-Key and the same bytes. |
| 3 | Either outcome | You end with exactly one order. |
partner_order_ref
creates a second order, and you pay for the same cards twice.| # | Observation | Meaning |
|---|---|---|
| 1 | state: "FULFILLED", qty: 5, voucher_count: 3 | Three cards were sourced; two were not. |
| 2 | The voucher endpoint returns 3 | Retrieve and deliver those three normally. |
| 3 | The shortfall | Carries a refund obligation. |
voucher_count, never on qty. Bill your customer from the
vouchers you actually retrieved. They are usually the same number, which is
precisely why this is easy to miss.
| Term | Meaning |
|---|---|
| canonical SKU | Stable identifier for a product in one country and currency — BIGBASKET--IN--INR. |
| denomination | Face value of a single gift card, in minor units. |
| minor units | Integer subdivisions of a currency — paise, cents. ₹500.00 is 50000. |
| item | One line of an order: a SKU, a denomination and a quantity. |
| voucher | One gift card. An item of qty: 2 produces two vouchers. |
| kind | How a voucher redeems: CODE, CODE_PIN, URL, URL_PIN. |
| secret | The redemption material, returned only by the voucher endpoint, as a JSON string. |
| masked hint | A non-redeemable fragment such as ****4821, safe for logs. |
| fulfilment hint | An advisory signal that a product is usually fulfilled quickly. |
| value mode | FIXED (a fixed set of amounts) or RANGE (an interval). |
| idempotency key | A caller-supplied string making POST /orders safe to retry. |
| canonical string | The four newline-joined components the signature is computed over. |