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

# Giftcard API overview

> Order gift cards, poll them to completion, and retrieve the redemption material

Five endpoints, one signing scheme, and one rule that governs everything else:
**an order is a fulfilment instruction, and it is accepted before it is
finished.**

<Warning>
  **This is a separate service from the Partner API.** It does not use `API-KEY`,
  it is not under `/api/v0`, and it does not take an `Api-Version` header.
  Requests are signed with HMAC-SHA256, and money is in integer minor units
  rather than decimal strings.
</Warning>

## The five endpoints

| Endpoint                                                          | Purpose                      | Auth   | Scope           | Rate limit         |
| ----------------------------------------------------------------- | ---------------------------- | ------ | --------------- | ------------------ |
| [`GET /catalog/products`](/giftcards/list-products)               | What can be ordered          | None   | —               | 120/min per IP     |
| [`POST /orders`](/giftcards/create-order)                         | Place an order               | Signed | `orders:write`  | 300/min per key    |
| [`GET /orders/{order_id}`](/giftcards/get-order)                  | Poll one order               | Signed | `orders:read`   | 300/min per key    |
| [`GET /orders`](/giftcards/list-orders)                           | List and filter orders       | Signed | `orders:read`   | 300/min per key    |
| [`GET /orders/{order_id}/vouchers`](/giftcards/retrieve-vouchers) | Retrieve redemption material | Signed | `vouchers:read` | **30/min per key** |

## The integration in three steps

1. **Read the catalogue and cache it.** [`GET /catalog/products`](/giftcards/list-products)
   tells you which `canonical_sku` values exist and which amounts each accepts.
2. **Place the order** with an `Idempotency-Key`. You get an `order_id` back
   immediately, in state `PENDING`.
3. **Poll, then retrieve.** When the order reaches `FULFILLED`, the codes are
   available from the [voucher endpoint](/giftcards/retrieve-vouchers).

<Warning>
  **There is no confirmation step and no cancellation endpoint.** An accepted
  order either fulfils or produces a refund obligation, so validate before you
  send rather than after.
</Warning>

## The rule that costs money if you miss it

An item can reach `FULFILLED` having produced **fewer vouchers than ordered**.

```json theme={null}
"qty": 5,
"voucher_count": 3
```

Three cards were sourced; two were not. The shortfall carries a refund
obligation.

**Bill your customer from `voucher_count` and the vouchers you actually
retrieved, not from what you ordered.** They are usually the same number, which
is exactly why the failure is easy to miss.

## Where to next

* [Signing requests](/giftcards/authentication) — the canonical string, and the four rules that decide whether it verifies
* [Conventions](/giftcards/conventions) — money, identifiers, rate limits, pagination
* [Order lifecycle](/giftcards/lifecycle) — the six states and how to poll them
* [Worked flows](/giftcards/flows) — the happy path, recovering a lost response, and a short fulfilment