Gift Card API for Online Stores: How It Works

Short Answer

A Gift Card API lets your online store connect to a supplier's product catalog, check stock, retrieve current pricing, create orders and receive digital codes automatically — without any manual steps between customer payment and code delivery. For an online store, this means customers get their codes immediately after purchase, regardless of time zone or order volume. The key capabilities to evaluate are product catalog access, real-time stock, price sync, order creation, code delivery, order status tracking, balance checking, webhooks and reconciliation export.

Definition: A Gift Card API is a B2B interface that allows an online store or reseller to connect to a digital goods supplier's catalog, automate code fulfillment, track order status and export transaction data for reconciliation — without manual involvement in the delivery process.

Key takeaway: A properly integrated gift card API removes the four biggest bottlenecks in digital goods reselling: manual stock management, delayed code delivery, reconciliation errors and customer support overhead for missing codes. The integration work is done once; the operational benefit is permanent.

Who This Guide Is For

This guide is for:

• Online store owners who want to add gift cards or game codes to their catalog and deliver them automatically
• Developers building the integration between a store and a digital goods supplier
• Marketplace operators evaluating API-based digital goods fulfillment
• Telegram bot developers who need automated code delivery for customer orders
• Anyone currently delivering digital codes manually who wants to automate the process

What a Gift Card API Is

A Gift Card API is a set of HTTP endpoints that connect your store to a supplier's inventory, pricing and fulfillment system. Instead of buying codes upfront, storing them in a spreadsheet and manually emailing them to customers, the API handles the entire chain:

1. Customer places an order on your store
2. Your store calls the supplier's order creation endpoint
3. The supplier returns the code instantly
4. Your store delivers the code to the customer

The process happens in seconds. The customer does not know the difference between a code you had pre-purchased and one delivered through an API call.

The Alternative Without API

Without API integration, the typical manual workflow is:

• Buy codes in advance and store them locally
• Receive a customer order
• Find the right code in your inventory
• Send it manually via email, chat or order confirmation
• Update your inventory count
• Periodically reorder when stock is low

This works at 10 orders per day. It does not work at 500.

Core API Features and What They Do

API Feature Overview

Product Catalog Endpoint

The catalog endpoint returns a list of available products with metadata: product name, denomination, activation region, currency and current availability status.

For an online store, this powers:

• Automated product import (no copy-paste from spreadsheets)
• Catalog sync (new products appear automatically)
• Regional filtering (show only products relevant to your customers)

What to verify:

• Does the catalog include region labels for each SKU?
• Are denominations listed accurately (e.g., $10, $25, $50, $100)?
• Is the catalog updated in real time or on a schedule?

Stock Check Endpoint

Before accepting a customer's payment, your store should check stock availability for the requested SKU. A stock check call returns whether codes are available and in what quantity range.

Without this check:

• Customer pays
• Your order call fails because the SKU is out of stock
• You must issue a refund and explain the problem to the customer

With this check:

• Your product page shows the correct availability state
• Your checkout blocks purchase of out-of-stock items before payment is taken

Price Endpoint

The price endpoint returns the current wholesale cost per SKU. Because supplier prices can change — especially for region-specific cards subject to FX movements — querying price at order time (rather than caching it) ensures your margin calculation is accurate.

Two pricing models:

Order Creation Endpoint

This is the core API call. Your store submits an order (SKU, quantity, customer reference) and the API returns the fulfillment data: typically one or more codes, with any activation instructions.

A basic order creation flow:

1. POST /api/orders/
   { "items": [{ "itemId": "product_01krgfgww8eth9xvvysd6y7r4j", "quantity": 1 }] }

2. API returns:
   { "id": "order_01k...", "status": "completed",
     "items": [{ "externalData": ["XXXXX-YYYYY-ZZZZZ"] }] }

3. Your store delivers the code to the customer

What to check in the API response:

• Is the status completed or pending? Pending means code is not yet delivered.
• Is the code format correct for the product (some require a PIN separately)?
• Is there a redemption URL or instructions included?

Order Status Endpoint

For orders that are not instantly fulfilled (processing state), the order status endpoint lets you check when fulfillment is complete. This is used for:

• Customer-facing "your order is being processed" messaging
• Internal monitoring of fulfillment SLA
• Support ticket investigation

Balance

Your reseller account with the supplier runs on a prepaid balance. Balance is enforced at order time — FoxReload has no GET /balance endpoint; if your balance is insufficient, POST /api/orders/ returns a BalanceNotEnough error. Top up via POST /api/topups/crypto/. Use this to:

• Monitor order failures for BalanceNotEnough errors and alert ops proactively
• Set up automated alerts when repeated balance errors occur
• Include balance monitoring in your operations dashboard

A failed order due to insufficient balance creates a worse customer experience than a clear "out of stock" message.

Order Status Tracking (Polling or Webhooks)

Tracking order status lets you detect when fulfillment completes and deliver codes to customers. How this is done depends on your supplier:

• FoxReload: uses polling only — call GET /api/orders/{order_id} at intervals until status is "completed", "cancelled", or "failed". When completed, items[].externalData contains the codes. There are no webhooks, no signature headers, and no callback events.
• Other suppliers: may send webhook push notifications to your server when order status changes.

For high-volume stores using FoxReload, run a background polling worker that checks all pending orders on a schedule and triggers code delivery when status reaches "completed".

If your supplier does support webhooks, your server must:

• Accept the webhook POST request
• Validate the signature (the supplier signs webhook payloads)
• Respond with HTTP 200 within the timeout window
• Process the event asynchronously (do not process in the webhook handler)

Reconciliation

GET /api/orders/?statuses=completed&limit=200&offset=0 returns your completed order history with timestamps, order IDs, items and settlement status — paginate with offset to cover the full period. This is used by:

• Finance teams for monthly settlement reporting
• Accounting systems for tax documentation
• Auditors verifying transaction records

How the API Fits Into Your Store Architecture

Customer Browser
      │
      ▼
Your Online Store
  ├── Product page: calls catalog/stock API to show availability
  ├── Checkout: calls stock API to confirm before payment
  ├── Payment: processes customer payment through your gateway
  ├── Order handler: calls supplier order creation API
  ├── Fulfillment: delivers code from API response to customer
  └── Order status poller: polls GET /api/orders/{order_id} until terminal status (or webhook listener if supplier supports it)

FoxReload API ──────────────────────────────────────────────────
  ├── GET /api/categories/
  ├── GET /api/products/          (product id = itemId; price included)
  ├── GET /api/products/search
  ├── POST /api/orders/
  ├── GET /api/orders/{id}        (codes in items[].externalData when completed)
  └── POST /api/topups/crypto/    (balance top-up; there is no GET /balance)

Integration Models

For most stores starting out, the on-demand model is the right default. It requires no upfront inventory capital and works for any catalog size the supplier offers.

What to Check Before Connecting a Supplier API

Common Integration Mistakes

1. Not checking stock before accepting payment — leads to failed orders and refund friction

2. Caching prices too aggressively — a price cached at 9am may be wrong by 3pm for FX-sensitive products

3. Ignoring webhook signature validation — anyone can POST to your webhook endpoint if you don't verify signatures

4. Processing webhooks synchronously — the supplier's retry logic will re-send if your server times out; process async

5. Not handling partial fulfillment — for multi-unit orders, some items may fulfill and others fail; handle each code independently

6. Not monitoring balance — a zero balance causes all orders to fail until you top up; set alerts

7. Using one order reference for multiple customer orders — always use unique references per customer order for reconciliation

Integration Checklist

• Read the full API documentation before writing any code
• Obtain API credentials and test all endpoints (use isMock: true for FoxReload test orders)
• Implement product catalog sync (catalog endpoint)
• Implement real-time stock check before checkout
• Implement order creation with error handling
• Handle all order statuses: completed, pending, failed
• Implement code delivery to customer (email, order page, Telegram message)
• Implement order status polling (or webhook listener if your supplier supports webhooks)
• For polling: use background worker; for webhooks: process events asynchronously
• Set up balance monitoring with alerts
• Test failure paths using isMock: true orders
• Implement reconciliation export for finance
• Set up API error logging and alerting
• Load test the integration at your expected order volume
• Go live with monitoring active