Getting Started with the GIFQ API

Overview

The GIFQ API is a single REST interface for purchasing digital gift cards in bulk and dispatching payouts to recipients in 90+ countries across 5,000+ brands. It's the same surface our own dashboard uses — anything you can do by clicking in the dashboard you can do programmatically: browse the catalog, charge against your balance, place orders, dispatch payout campaigns, and reconcile transactions.

This guide walks through what the API does, how it's shaped, and what to read next. For full request and response schemas, jump to the API reference.

When to use the API

Most teams reach for the API when one of three things is true:

• Embedded rewards. You're shipping a SaaS, marketplace, or platform feature where end users earn gift cards. Catalog, ordering, balances, and FX handling are all in a single integration.
• Programmatic payouts. You're sending recurring rewards — research incentives, affiliate payouts, customer make-goods, employee recognition — and don't want to operate a dashboard each time.
• Cross-border distribution. You need one endpoint that resolves brand availability, currency, and supplier routing across countries you don't want to integrate one by one.

How the API is shaped

The GIFQ API is REST over HTTPS, JSON in and JSON out, with standard HTTP status codes. There is one external surface — everything under /api/* excluding internal endpoints — and one source of truth: the published reference at docs.gifq.com.

Environments

• Sandbox — https://api-sandbox.gifq.com. Pre-funded test balances, mock catalog, no IP whitelisting. Used for building and end-to-end testing.
• Production — https://api.gifq.com. Real catalog, real balances, IP allowlist required. Activated once your production setup is complete on both sides.

Authentication

Every external request carries an X-Api-Token header. Sandbox and production each have their own token; the same code works in both environments by switching credentials and base URL. Treat the token like a password — it grants full access to your account's balances and orders.

The API also exposes a public, unauthenticated surface for the recipient redemption flow (GET /api/payouts/:token), where the single-use claim token in the URL is itself the credential. Your servers don't call this — recipients do, via the redeem page.

If a request lacks X-Api-Token, it falls back to IP-based throttling under the same 10 requests-per-second limit. Authenticate every request from your application.

What the API can do

Catalog (products and brands)

The catalog is the source of truth for what you can sell or send. Brands carry stable slugs (amazon, adidas) and product options carry the actual purchase constraints — country availability, currency, denomination range, and discount or fee. Always validate amount, country, and currency at product level before placing an order; brand-level fields are for browsing only.

• GET /api/products — paginated catalog of brands and product options.
• Per-product min_face_value / max_face_value distinguishes fixed denominations from variable amounts.
• Per-product discount can be positive (a discount you receive) or negative (a fee you pay). Treat negative values explicitly as fees in your UI.
• stock_count may be null when stock is dynamic. Code defensively and re-validate at order time.

Orders

Orders are how you purchase and deliver a gift card. You specify the brand slug, currency, face value, and country — plus your own unique reference for idempotency. The system selects the best available supplier behind the scenes, charges your company balance, and returns redemption details.

• POST /api/orders — create an order.
• GET /api/orders/:id — fetch an order and its redemption details once completed.
• GET /api/orders — paginated list, newest first.

Orders move through pending → completed (or failed → automatic refund). Poll the single-order endpoint until you reach a terminal state. Once an order is completed, redemption details land in the response — depending on the brand, that includes some combination of code, pin, link, link_challenge_code, serial, and security_code.

Idempotency. Pass a unique reference per order. Retrying a request with the same reference will not create a duplicate. Use this on every order — it's the difference between a clean retry on a network blip and a double-charged customer.

Payouts and campaigns

If you want recipients to choose their reward instead of receiving a single specific gift card, use Payouts. A campaign is the wrapper — branding, email copy, and the curated list of brands recipients can pick from. A payout order is a batch of recipients (up to 1,000 each) dispatched against an active campaign. Each recipient gets a unique single-use redeem link, completes a one-time-code verification, and selects a brand from the campaign's catalog.

• GET / POST /api/campaigns — manage campaigns (Draft → Active → Paused → Archived).
• GET / POST /api/payout-orders — dispatch and track payout batches.
• GET /api/payouts — individual payouts and their statuses.
• GET /api/payouts/:token — public, unauthenticated catalog endpoint consumed by the recipient's redeem page.

The full campaign lifecycle, recipient statuses, and the verified redemption flow are covered in the Payout Campaigns Setup Guide.

Balances

Your account has a balance per currency. Orders and payout dispatches are charged atomically against the relevant balance — if funds are short, the request fails with no records created. In sandbox, accounts are pre-funded with 5,000 USD, 5,000 GBP, and 5,000 EUR so you can integrate without a top-up.

• GET /api/balances — list all balances, one per currency.

Transactions

Every balance movement — top-ups, order charges, payout dispatches, refunds, and FX conversions — is recorded as a transaction. Use this endpoint for reconciliation against your own ledger.

• GET /api/transactions — paginated transaction history.

Cross-currency orders

If you hold balance in EUR but want to order a USD gift card, pass the order's payment_currency. The API converts the order amount at the current rate, applies a 1% FX fee, and charges your EUR balance. The response includes an fx_fee object with the rate, fee percentage, and total charged in your payment currency — surface those values in your reconciliation.

Conventions every endpoint follows

Pagination

List endpoints (orders, products, transactions, campaigns, payouts, payout-orders, campaigns/:id/catalog) use a page query parameter with an optional limit (default 10, max 20). Each response carries four headers — current-page, page-items, total-count, total-pages. Iterate until current-page equals total-pages. Requesting an out-of-range page returns HTTP 400; restart from page 1 if it happens.

Rate limiting

Each API token is throttled at 10 requests per second. Tokens are independent — traffic on one integration does not impact another. Exceeding the limit returns HTTP 429 with a Retry-After header indicating how many seconds to back off. Read the header and pause; do not implement custom backoff that ignores it.

Error model

Errors return a JSON body with message and status: "error". Failed order creations return HTTP 422 along with a request_id — keep that ID; if you need support, it's the fastest way for our team to find your request.

Status codes you'll see

• 200 / 201 — success.
• 400 — malformed request or out-of-range pagination.
• 401 — missing or invalid X-Api-Token.
• 422 — order or payout could not be created (validation, balance, or catalog drift).
• 429 — rate limited; honor Retry-After.

Getting access

Activation is a guided process. The current path is:

• Reach out to sales. Your GIFQ representative provisions an account, sandbox API credentials, and sandbox dashboard access. No credit card is required to start.
• Build against sandbox. No IP whitelisting. The catalog mirrors production. Pre-funded balances let you exercise the full order and payout lifecycle end-to-end.
• Move to production. Once your integration is reviewed and your production account is set up, we provision live credentials and configure the IP allowlist. The same code switches over with a credentials-and-base-URL change.

Operated by Gift Quest OÜ, an Estonian-registered, GDPR-aligned company. Sister brand to CoinGate Gift Cards (B2C). The API is operated under EU jurisdiction.

Where to go next

This article is the high-level shape. For request and response schemas, parameter lists, and copy-paste examples, the API reference is the source of truth.

• Getting Started — sandbox provisioning, production cutover, and account setup.
• Authentication — API key handling and rotation.
• Products and Catalogs — full data model for brands and product options.
• Orders — full order lifecycle and FX handling.
• Balance Management — top-ups, currency model, transactions.
• Pagination and Rate Limiting — conventions you'll touch on every list endpoint.
• Payout Campaigns Setup Guide — the dashboard equivalent to the Payouts API endpoints.

If a section above looks different in production from what you read here, the live API reference is authoritative — and we'd appreciate you flagging the drift to your GIFQ representative so we can fix the doc.