Understading Products and Catalogs

Products power your catalog. This guide explains how products are organized, how availability works, and how to build a reliable, up‑to‑date catalog you or your users can browse and purchase from.

How Products Are Structured

• Brand
  • brand: Stable slug you can store and reference in your system
  • title, logo, description, terms, redeem_instructions, categories
  • countries: Union of all countries across the brand’s products (good for quick filtering)
• Product option (within a brand)
  • min_face_value / max_face_value: Amount constraints
    • Same value: fixed denomination
    • Different values: variable amount within the range
  • countries: Countries where this specific option is available
  • currency: Currency of the product
  • discount: Percentage. Important: negative values must be treated as a fee.
  • stock_count: May be null (unknown/dynamic); do not rely on it always being present
  • expiry, balance_check_url: Informative for UX and support

Availability Model

• Account‑scoped: Your catalog reflects your account’s configuration and commercial settings.
• Region‑aware: Use brand‑level countries for discovery; always confirm availability with product‑level countries before checkout.

Currency Model

• Product‑level currency: Use it for pricing, balance checks, and validation.
• Discounts and fees: Display informative messaging (e.g., “up to X% off”); final pricing is confirmed at order time.

Building Your Catalog

• Initial sync
  • Iterate pages (page 1 onward) and ingest all brands with their product options.
  • Index entries by brand slug for lookups; optionally store the brand UUID if you need a stable internal ID.
• Derive purchase options
  • Fixed denominations: min == max
  • Variable denominations: allow user amounts within [min, max] and validate at order creation
• Filtering & discovery
  • Filter by categories, brand‑level countries, product‑level countries, and product currency
  • Use product‑level countries for final purchase validation

Keeping Data Fresh

• Expect change: Stock, discounts, and availability can change during the day.
• Cache smartly: Cache the catalog, then refresh on a cadence that fits your UX (e.g., background job, session start, or on demand for high‑turnover brands).
• Pagination safety: If you encounter an out‑of‑range page, handle gracefully (e.g., restart from page 1).

Pre‑Purchase Checklist

• Amount: Within [min_face_value, max_face_value]
• Country: Present in the product option’s countries
• Currency: Use the product option’s currency for pricing and balance checks
• Stock awareness: Treat null stock_count as unknown; handle potential order‑time rejections gracefully

Resilience & Error Handling

• Authentication: Use your API token; treat 401 as a configuration/auth issue to resolve
• Pagination: Handle invalid/out‑of‑range page errors robustly (retry or restart)
• Data drift: Re‑validate amount, country, and currency at order time in case catalog data changed

Common Pitfalls

• Using brand currency for logic: It’s deprecated—always use product‑level currency
• Ignoring pagination headers: You may miss data if you don’t iterate pages
• Relying on brand‑level countries for purchase checks: Always validate at product level
• Assuming stock_count is always present: Treat null as unknown and code defensively
• Hard‑coding discounts: They can change; refresh and re‑display

Implementation Checklist

• Fetch and page through the catalog; store brands and their product options
• Index by brand slug; surface title, logo, categories for discovery
• Derive denomination UX from min/max; display product‑level currency
• Filter by country/currency as needed; always validate with product‑level countries
• Refresh your cache on a sensible cadence; re‑validate at order time