A gift card API gives a storefront live access to a distributor’s catalogue: products, prices, availability and instant code delivery through one integration. Instead of loading code batches by hand, your checkout requests a code the moment a customer pays and receives it in seconds.
The integration itself is not hard. Most teams have a first order flowing in a few days. The mistakes that hurt are not in the happy path; they are in retries, price drift and how you store the codes after delivery. This guide covers the whole path.
How to integrate a gift card API
- Start in the sandbox. Any serious provider offers test credentials and fake stock. Wire up your flow end to end before a single live order.
- Sync the catalogue, do not cache it forever. Products appear, disappear and change price. Pull the catalogue on a schedule (hourly is typical) and treat your local copy as a snapshot, not a source of truth.
- Build the order flow around idempotency. Send a unique key with every purchase request. If your request times out and you retry without one, you may buy the same code twice, and codes are not returnable once delivered.
- Decide what happens on delay. Most orders complete in seconds, but some queue. Show the customer an honest “your code is on its way” state instead of failing, and deliver by email when the code lands.
- Reconcile daily. Compare your order log against the provider’s invoice line by line. Quiet mismatches (a retried order, a failed delivery you never noticed) surface here and nowhere else.
Treat delivered codes like cash
A gift card code is a bearer instrument: whoever sees it can redeem it. That has direct consequences for your architecture.
- Encrypt codes at rest and decrypt only at the moment of display or delivery.
- Never write codes to application logs, error trackers or analytics. Mask them the way you would mask a card number.
- Limit human access. Support staff rarely need the code itself; they need the order status and the delivery address.
- Purge or archive codes after delivery on a fixed schedule. Old codes in a database are pure liability.
A leaked database of undelivered codes is money gone, with no chargeback to save you.
The three mistakes that cost real money
Quoting from a stale price. If your checkout shows a price synced yesterday and the trade price moved overnight, you sell at a loss and find out at reconciliation. Re-check the live price at order time for anything expensive.
Retrying without idempotency keys. Every payment system has taught this lesson at least once. Timeouts are not failures; the first request may still complete.
Ignoring out-of-stock responses. Availability is per product and per region, and it changes. Handle the out-of-stock response as a normal case with a clear customer message, not as an exception that crashes the order.
Frequently asked questions
How long does a gift card API integration take?
For a storefront with a working checkout, the typical range is two days to two weeks: days for the order flow itself, longer when catalogue mapping and code storage are built properly. Onboarding and business checks with the provider often run in parallel, so the commercial and technical tracks finish together.
Do catalogue prices change without notice?
Yes. Trade prices follow issuer pricing and currency movements, and a catalogue API reflects that continuously. This is normal; build your sync schedule and your quoting logic around it rather than treating price changes as incidents.
What if a delivered code turns out to be already redeemed?
Report it through the provider’s dispute process with your delivery log. This is where disciplined logging pays off: a timestamped record of when the code was delivered, and to whom, is the difference between a quick replacement and a long argument. Ask about the replacement policy before you sign, not after the first case; our checklist for a first bulk order covers what else belongs in that conversation.
Do I need to test in a sandbox before going live with a gift card API?
Yes, and a provider without one is a warning sign. Sandbox credentials and fake stock let you rehearse the full flow, including the awkward paths: timeouts, retries with idempotency keys, out-of-stock responses and delayed delivery. Codes are not returnable, so a bug found in production is paid for in real stock. Move to live orders only once every failure case behaves the way you designed.
How should a storefront store gift card codes after API delivery?
Like cash, because a code is a bearer instrument: whoever reads it can redeem it. Encrypt codes at rest, decrypt only at the moment of delivery, and keep them out of logs, error trackers and analytics. Restrict staff access to order status rather than the code itself, and purge delivered codes on a fixed schedule. A leaked table of codes is stock gone with no recovery path.