Can a gift card API deliver codes instantly?

Yes, for pre-purchased or on-demand stock, API order creation typically returns codes within seconds. "Instant" depends on the supplier's fulfillment pipeline. Verify response times in the sandbox before going live.

What API features are required as a minimum?

The minimum viable set is: catalog, stock check, order creation and order status. For any production store, add webhooks and balance API. Reconciliation is required for any business with more than ~50 orders per month.

Does a gift card API work for Telegram bots?

Yes. The API calls are HTTP requests — they work the same regardless of whether the calling system is a web store, a Telegram bot backend or a marketplace integration.

How do I handle a failed order?

The API should return an error code with a reason. Common reasons: out of stock, insufficient balance, invalid SKU. Your store should catch these errors, not charge the customer, and either retry with a different supplier or show a meaningful error message.

Can I connect to multiple supplier APIs simultaneously?

Yes. Many stores use a primary supplier for most SKUs and a backup supplier for out-of-stock situations. This requires routing logic in your order handler.

What is the difference between a code-based gift card API and a top-up API?

A gift card API delivers a code (alphanumeric string) that the customer redeems on the platform. A top-up API sends credit directly to the customer's game account — no code is generated. Top-ups require a validated player ID.

What should my webhook listener return?

Return HTTP 200 immediately after receiving and validating the webhook. If you return anything else — or time out — the supplier will retry. Never process business logic in the synchronous webhook handler; queue it.

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:

Customer places an order on your store
Your store calls the supplier's order creation endpoint
The supplier returns the code instantly
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

API Feature	Purpose	Business Value
Product catalog	List available SKUs with names, denominations and activation regions	Automated product import; no manual catalog maintenance
Stock check	Verify code availability per SKU before creating an order	Prevents overselling; surfaces out-of-stock before customer pays
Price endpoint	Retrieve current wholesale price per SKU	Enables dynamic pricing and real-time margin management
Order creation	Submit a purchase order and receive fulfillment data	Delivers codes instantly after customer payment
Order status	Check the current state of a submitted order	Powers customer-facing delivery status and support queries
Balance API	Query your reseller account credit balance	Prevents failed orders from insufficient balance
Webhooks	Receive push notifications when order status changes	Real-time fulfillment without polling; needed for high-volume stores
Reconciliation	Export order history, amounts and settlement data	Finance reporting, tax records, audit trail

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:

Model	How it works	Risk
Static price list	Wholesale prices are fixed and updated manually	Margin erosion if prices change without notice
Dynamic price API	Wholesale prices queried per order	Accurate margin; requires logic to pass cost through to retail price

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 /orders
   { "sku": "steam-10-usd", "quantity": 1, "reference": "ORD-12345" }

2. API returns:
   { "order_id": "SUP-99887", "status": "completed",
     "codes": [{ "code": "XXXXX-YYYYY-ZZZZZ", "pin": null }] }

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 API

Your reseller account with the supplier runs on a prepaid balance. The balance API lets you check the current balance programmatically. Use this to:

Block order creation if balance is below the order amount
Set up automated alerts when balance falls below a threshold
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.

Webhooks

Webhooks are push notifications sent from the supplier to your server when an order event occurs: order received, order fulfilled, order failed. They eliminate the need to poll the order status endpoint repeatedly.

For a store processing more than 50 orders per day, webhooks are not optional — polling at scale wastes API rate limits and introduces latency.

Webhook event types to expect:

order.created
order.fulfilled
order.failed
order.refunded

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 API

The reconciliation endpoint returns your full order history with timestamps, order IDs, SKUs, quantities, amounts paid and settlement status. 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
  └── Webhook listener: updates order status from supplier events

Supplier API ──────────────────────────────────────────────────
  ├── GET /catalog
  ├── GET /stock/:sku
  ├── GET /prices/:sku
  ├── POST /orders
  ├── GET /orders/:id
  ├── GET /balance
  └── GET /reconciliation

Integration Models

Model	How It Works	Best For
On-demand API ordering	Order created when customer pays; code delivered from supplier in real time	Lowest capital requirement; works for any catalog size
Pre-purchased stock	Codes bought upfront, stored in your database; API only for reordering	Faster delivery independence; requires capital and storage logic
Hybrid	Popular SKUs pre-purchased; rare or expensive SKUs ordered on demand	Balances availability and working capital

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

Factor	What to Check	Why It Matters
Documentation quality	Are endpoints documented with request/response examples?	Poor docs = slow integration = bugs
Uptime and reliability	Is there an SLA or status page?	API downtime = failed customer orders
Response time	How fast does the order endpoint respond?	Customer waits for code after payment
Region labeling	Are regions explicit in the catalog (e.g., "US", "EU", "TR")?	Wrong region = refund request
Error codes	Does the API return structured errors?	Easier debugging and customer messaging
Sandbox environment	Is there a test environment?	Test before going live
Webhook support	Does the API support webhooks?	Required for reliable high-volume operation
Rate limits	What are the request limits?	Plan your polling and batch logic accordingly
Reconciliation format	Is export in CSV, JSON or only PDF?	Finance team needs machine-readable format

Common Integration Mistakes

Not checking stock before accepting payment — leads to failed orders and refund friction
Caching prices too aggressively — a price cached at 9am may be wrong by 3pm for FX-sensitive products
Ignoring webhook signature validation — anyone can POST to your webhook endpoint if you don't verify signatures
Processing webhooks synchronously — the supplier's retry logic will re-send if your server times out; process async
Not handling partial fulfillment — for multi-unit orders, some items may fulfill and others fail; handle each code independently
Not monitoring balance — a zero balance causes all orders to fail until you top up; set alerts
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 sandbox credentials and test all endpoints
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)
Set up webhook listener with signature validation
Implement async webhook processing
Set up balance monitoring with alerts
Test refund/failure paths in sandbox
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