Ordering ten thousand gift card codes through a bulk gift card API is a batching problem, not ten thousand checkout orders in a loop. The engineering work sits in four places: using the provider’s batch primitive, respecting rate limits, funding the account before the run starts, and treating partial failure as a normal outcome you reconcile rather than an exception you panic over.
The commercial groundwork, contracts, volume terms and supplier vetting, is a separate exercise covered in the bulk buying checklist. This article is about the run itself.
Prefer the batch primitive
Where the provider offers a batch endpoint, use it: one request, one batch reference, server-side sequencing, and usually a single status object you can poll until the whole thing settles. Looping single orders reaches the same destination with ten thousand times the failure surface, since every request is a separate chance to time out, hit a limit, or land mid-deploy.
Some providers only offer single-order endpoints. A loop is then legitimate, but it needs the discipline of a batch: a fixed client-side pacing rate, a checkpoint after every confirmed order so a crash resumes instead of restarting, and one run-level reference tying all the line items together for later reconciliation.
Rate limits are part of the contract
Read the rate limit headers and obey them: remaining quota, reset windows, and any retry-after value on a 429. Spread a large run over time instead of firing it as fast as the connection allows.
Then go beyond the headers and talk to the provider before the first big run. Ask what burst rate is acceptable, whether bulk traffic should go through a different endpoint, and whether a run of this size should be announced. An unannounced spike of ten thousand purchase calls looks like a compromised account to any sane fraud system, and being throttled halfway through a run is the good version of that outcome.
Partial failure is the normal case
Order three thousand two hundred codes and a realistic result is three thousand delivered, two hundred failed: a denomination went out of stock mid-run, a pricing window closed, a handful of requests timed out. This is not a broken batch, it is how batches land.
The safe response has a fixed shape. Deliver everything that succeeded. Work out why the remainder failed, fix what needs fixing, and reorder only those line items. Never resubmit the whole batch because part of it failed: without protection that buys the successful three thousand a second time.
Which is why idempotency must live at the line-item level, not the batch level. A batch-level idempotency key only protects you from resubmitting the identical batch; a key per line item makes reordering the failed remainder safe, and makes a timed-out item resolvable on its own.
Fund the run first
A batch that outruns the prepaid balance fails midway, and now you hold a partial delivery plus a stalled run at the worst possible moment. Before starting, confirm the balance covers the full run with a buffer, and arm low-balance alerts so a concurrent drain from regular sales does not starve the batch. Large floats parked with a supplier carry their own exposure, which is worth understanding separately: see prepaid balance risk.
Delivery and custody at volume
Bulk codes arrive in one of three shapes: an array in the API response, a file drop (typically encrypted CSV to agreed storage), or a secure download portal with expiring links. Ask which one the batch endpoint uses before designing your intake, because a pipeline built for response arrays does not parse a file drop.
At volume, custody becomes the sharper issue. Ten thousand live codes are a bearer liability: encrypt them at rest, restrict and log access, and keep them out of email threads and shared spreadsheets. A code that leaks between delivery and sale is spent stock you already paid for.
Rehearse at one-tenth scale
Before the first production run, execute the same batch in the sandbox at one-tenth size: same pacing, same checkpointing, same intake pipeline. Force a partial failure and confirm the remainder-reorder path works, then check the run-level reference flows through to reconciliation so the batch can be matched line by line against the provider’s statement. A dry run costs an afternoon; discovering a checkpoint bug at item six thousand costs considerably more.
Frequently asked questions
How do I order thousands of gift cards through an API?
Use the provider’s batch endpoint where one exists: a single request with all line items, returning a batch reference you poll until completion. If only single-order endpoints exist, loop with fixed pacing, checkpoints after each confirmed order, and a shared run reference. Either way, confirm rate limits and burst policy with the provider first, and fund the account for the full run before starting.
What happens when a bulk order partially fails?
Part of the batch delivers and part fails, often because stock or a price window changed mid-run. Deliver the successful codes, diagnose the failed line items, and reorder only those, each under its own idempotency key. Never resubmit the entire batch, since that repurchases everything that already succeeded. Reconciliation against the provider’s statement then confirms the final delivered count.
Do gift card APIs have rate limits?
Yes, effectively all of them, and bulk ordering is where you meet the limits in earnest. Expect per-second or per-minute caps, quota headers, and 429 responses with a retry-after value. For large runs, ask the provider about burst policy in advance: unannounced high-volume traffic can resemble account compromise and get throttled or flagged mid-batch.
How are codes delivered after a bulk API order?
In one of three shapes: an array of codes in the API response, a file drop such as an encrypted CSV pushed to agreed storage, or a secure download portal with expiring links. Ask which one the batch endpoint uses before building your intake, because a pipeline written for response arrays will not parse a file drop. At ten thousand codes, custody matters too: encrypt on arrival and log every access.
Should I test a bulk gift card order in the sandbox first?
Yes, and at meaningful scale: run the same batch at about one-tenth size with identical pacing, checkpointing and intake. Force a partial failure on purpose and confirm that reordering only the failed line items works, then check the run-level reference carries through to reconciliation. A sandbox rehearsal costs an afternoon; finding a checkpoint bug at item six thousand of a live run costs far more.