A gift card catalog API should return, for every product, enough data to sell it without a human in the loop: a stable product ID, brand, redemption region, currency, denomination rules, current trade price, availability, delivery type and any input the order needs. If a field is missing, someone on your team will end up filling it by hand, and hand-filled catalogues drift quickly.
How often to pull the catalogue and how to handle price drift is covered in our catalogue sync guide. This article is about the shape of the response itself: what to expect, what to ask for, and which gaps turn into production incidents.
One product, one row, one stable ID
The unit of a catalogue is not a brand; it is a sellable product. “Steam Wallet” is a brand. “Steam Wallet, 50 USD, redeemable in the United States” is a product. A good catalogue endpoint returns one entry per product with an identifier that never changes, even when the name, image or price does.
Stable IDs matter because everything downstream references them: your storefront listings, your order records, your reconciliation reports. A provider that re-issues IDs on every catalogue refresh forces you to match products by name, and name matching breaks the first time someone fixes a typo.
The fields that matter
A typical entry looks something like this. Field names vary by provider; the content is what to check.
{
"product_id": "prd_8f21c",
"brand": "Example Games",
"name": "Example Games Wallet 50 USD (US)",
"region": "US",
"currency": "USD",
"denomination": { "type": "fixed", "value": "50.00" },
"price": { "amount": "...", "currency": "USD" },
"available": true,
"delivery_type": "code",
"required_inputs": [],
"max_quantity_per_order": 100,
"redemption_url": "https://redeem.example.com",
"updated_at": "2026-10-01T09:00:00Z"
}| Field | Why you need it | What goes wrong without it |
|---|---|---|
| Stable product ID | Order and report references | Name matching, broken history |
| Region | Where the card redeems | Wrong-region sales and refunds |
| Face currency and value | What the customer receives | Mislabelled listings |
| Denomination type | Fixed amount or open range | Orders for values that do not exist |
| Trade price and currency | What you pay per unit | Quoting from guesswork |
| Availability | Can it be bought right now | Checkout failures on dead products |
| Delivery type | Code, link or direct top-up | Wrong fulfilment flow |
| Required inputs | Player ID, server, email | Orders rejected at submission |
| Per-order limits | Max quantity per request | Bulk runs failing mid-batch |
| Updated timestamp | Freshness of this entry | No way to detect stale data |
Region is a first-class field, not part of the name
Most gift cards are locked to a redemption country, for the reasons laid out in why gift cards are region-locked, though some products are multi-region, so check per product. A catalogue that only carries region inside a free-text name (”… (EU)”) makes you parse strings to decide who can buy what. Ask for region as a structured field, ideally an ISO country code or a documented list of region codes, so your storefront can filter by the buyer’s location without regular expressions.
The same goes for currency. The face value currency (what the card loads) and the price currency (what you are billed in) can differ, and both should be explicit.
Denominations: fixed values and open ranges
Some products come in preset amounts; others accept any value inside a range, sometimes in fixed steps. The trade-offs are covered in fixed vs open value denominations. For the API, the point is that the catalogue must say which kind each product is. A fixed product needs its value; an open product needs minimum, maximum and step. Without the step, your form will accept 37.50 for a product that only exists in whole units, and the order will fail at submission.
Delivery type and required inputs
Not every catalogue item is a code. Direct top-ups credit a game account and need a
player ID, sometimes a server too; the details are in
player ID validation. If the catalogue
exposes delivery_type and a machine-readable list of required inputs, your
checkout can render the right form per product automatically. If it does not, you
end up hard-coding exceptions per brand, and every new title becomes a release.
Filtering, paging and change detection
A catalogue with hundreds of brands across many regions runs to thousands of products. Three features keep that manageable:
- Filters by brand, region, delivery type and availability, so a regional storefront pulls only what it can sell.
- Pagination with a stable cursor, so a long pull does not skip or repeat items while the catalogue changes underneath it.
- Change detection, either an
updated_sinceparameter or per-entry timestamps, so routine syncs fetch the delta rather than the whole list.
A single-product lookup by ID is the fourth, quieter requirement. It is what lets you re-check price and availability at order time without pulling everything again.
Catalogue endpoint checklist
Before you build against a catalogue API, confirm each of these:
- Product IDs are stable across refreshes and documented as such.
- Region and both currencies are structured fields.
- Denomination type is explicit, with range and step for open products.
- Availability is per product and reflects live stock, not a daily batch.
- Delivery type and required inputs are machine-readable.
- Delisted products disappear or flip to unavailable in a documented way.
- Paging, filters and a single-product lookup exist.
- Every entry carries an updated timestamp.
Giftoro exposes catalogue, pricing and instant code delivery through one integration; the gift card API overview describes what that covers, and the specification with a sandbox key is available on request.
Frequently asked questions
What is a gift card catalog API?
It is the part of a distributor’s API that lists the products you can buy: brands, regional variants, denominations, prices and availability. Your storefront reads it to build listings and to check price and stock before ordering. Ordering and code delivery usually live on separate endpoints of the same integration.
How often should I call the catalogue endpoint?
Pull the full catalogue on a schedule (many teams pull hourly) and use change detection where the API supports it. For anything with money attached, re-check the single product live at order time rather than trusting the last sync.
Why does the same brand appear many times in the catalogue?
Because each combination of region, currency and denomination is a separate product. A brand sold in five regions with six amounts each is thirty catalogue entries, each with its own ID, price and stock state. That is expected, not duplication.
Should catalogue prices be shown directly to customers?
No. The catalogue price is your trade price, not your retail price. Your storefront applies its own pricing rules on top, and should keep the trade price out of public pages and client-side code entirely.
What should happen when a product disappears from the catalogue?
Mark it unavailable and hide it from browsing, but keep its record so past orders and reports still resolve. Products sometimes return after a short absence, and a hidden entry is one flag away from being live again.