> ## Documentation Index
> Fetch the complete documentation index at: https://docs.endl.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Worked flows

> The happy path, recovering a lost response, and a short fulfilment

## Happy path

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

## Recovering from a lost response

Your `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.                                                  |

<Warning>
  **Never invent a new reference to "try again".** A fresh `partner_order_ref`
  creates a second order, and you pay for the same cards twice.
</Warning>

## A short fulfilment

The order reached a terminal state but produced fewer vouchers than ordered.

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

**Reconcile on `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.

## Glossary

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