How to Send Bulk Gifts via API: A Developer Guide to Batch Gift Fulfillment at Scale

Sending bulk gifts via API means submitting one job that fans out into many gift orders: five hundred employees recognized at quarter end, every customer on a list receiving a holiday gift, a whole cohort rewarded at once. The mechanics differ from single-trigger gifting in exactly the ways that bite in production: request structure, retries, rate limits, and partial failure. This guide covers the pattern end to end, the way you would actually build it.

It assumes you have already decided you need a gifting API and are now evaluating the engineering work. The short version: a well-built bulk integration is a few days of work, and most of it is error handling and reconciliation rather than the happy path. The RealGifts API documentation covers the concrete endpoints; this post covers the architecture decisions that apply to any batch gifting job.

Single-Trigger vs. Batch Gifting: When to Use Each

Single-trigger gifting fires one order per event: a user hits a milestone, your backend sends one gift. It is the right shape whenever the moment belongs to one recipient at a time. The wire-level mechanics of that pattern (event subscription, payloads, callbacks) are covered in the companion guide to gifting API webhooks, and the product case in the guide to gift automation for platforms.

Batch gifting fires many orders from one decision: end-of-quarter employee recognition, a holiday campaign to a customer list, a make-good send to every account affected by an incident. The recipients are known up front, the send is scheduled rather than reactive, and the job is measured in hundreds or thousands of orders.

The architectural difference matters more than it looks. Single-trigger integrations are event consumers, and their failure mode is a missed event. Batch integrations are jobs, and their failure modes are duplicates, partial completion, and throughput. The rest of this guide is about those three.

Structuring a Bulk Gift Request

At the pattern level, a batch gift request carries three things: a recipient list (identifiers and a delivery contact, typically email), a gift definition (a specific catalog item, or a budget range the recipient chooses within), and campaign metadata (a campaign name, a cost center, whatever your reconciliation needs to group by). The API accepts the batch, validates it, and returns a job reference your system tracks.

Two structuring decisions to make before you write code. First, recipient-choice or fixed item: for large heterogeneous lists, recipient-choice within a budget almost always beats picking one item for everyone, because the claim flow absorbs taste, size, and address problems. Second, chunking: do not treat ten thousand recipients as one atomic request. Submit in bounded chunks, so a validation failure quarantines one chunk instead of the whole campaign and retries stay cheap.

Keep the source of truth on your side. Persist the recipient list, the chunk boundaries, and the job references the API returns before you submit anything. When something fails mid-campaign (something eventually will), reconciliation starts from your record, not from memory.

Idempotency: How to Avoid Double-Gifting

Idempotency is the most important concept in bulk gifting, because the failure it prevents is the expensive one. Networks fail after a request succeeds: your client times out, the connection drops, your job runner restarts, and your code retries a request the server already processed. Without idempotency, that retry ships a second gift to several hundred people, and there is no undo on a shipped package.

The fix is the standard one: every order-creating request carries an idempotency key, a unique value your system generates deterministically from the send itself, for example a hash of campaign ID plus recipient ID. When a retry arrives with a key the server has already seen, the server returns the original result instead of creating a second order. Two rules make it work in practice: derive the key from the business operation (campaign plus recipient), never from the attempt (no timestamps, no random values per retry), and persist your keys with the campaign record, so a restarted job resends the same keys.

Treat retries themselves with discipline: retry timeouts and server errors with exponential backoff, do not retry validation failures, and cap the attempts. With deterministic keys an aggressive retry policy is safe; without them, every retry is a gamble.

Rate Limits and Throughput

Every production API meters write traffic, and order creation is the most metered surface of a gifting API. Plan for the batch to be throttled, not blasted: a bulk job is a queue your worker drains at a controlled rate, not a loop that fires as fast as the network allows.

Set realistic expectations with the campaign owner: a few thousand gifts is a job that completes in minutes to hours, and that is fine, because nothing downstream is real-time (fulfillment and shipping operate on days). Respect the API's signals: when a rate-limit response arrives, back off and resume rather than hammering, and when you list or reconcile large jobs, follow the pagination instead of assuming one page holds everything. If your campaign sizes are unusual, ask about expected throughput before launch day rather than during it.

Testing Bulk Campaigns in Sandbox

Never point a first bulk campaign at production. A sandbox run costs nothing and surfaces almost every bug this guide warns about: malformed recipients, chunking errors, retry storms, key collisions. RealGifts sandbox access is included from day one of the trial, so the full rehearsal happens before any spend.

Rehearse the failure paths, not just the happy one. Submit the same chunk twice and confirm idempotency returns the original orders. Kill your worker mid-job and confirm the restart resumes without duplicates. Seed the test list with bad rows (an invalid email, a missing field) and confirm the job quarantines and reports them rather than dying or silently dropping them. A bulk integration that has only ever seen clean data in sandbox has not been tested.

Webhook Callbacks for Delivery Status

A batch job is not done when the API accepts it; it is done when the gifts are delivered. Webhooks track the distance between those two points. The pattern: you register an endpoint, and the platform posts status events as each order moves through its lifecycle (accepted, claimed, shipped, delivered, failed), each event carrying the order reference and your campaign metadata so you can attribute it.

Build the consumer to standard webhook discipline: acknowledge fast and process asynchronously, treat events as possibly out of order and occasionally duplicated (the handler should be idempotent too, keyed on event ID), and reconcile rather than trust: a periodic job that queries order status for anything not yet in a terminal state catches whatever your endpoint missed. Campaign reporting (how many delivered, how many claimed, what failed) falls out of this event stream for free if you store it.

Error Handling and Fallbacks

Bulk sends fail at the row level, and the design question is what happens to the other 990 rows when 10 fail. The answer should be: nothing. Validation failures are quarantined and reported, never fatal to the batch. A bounced recipient email is a re-contact workflow (correct the address, resend the claim link), not a lost gift, because the gift is claimed via link rather than shipped blind to an unverified address.

Out-of-stock is the other classic: between submission and claim, a specific item can become unavailable. Recipient-choice sends within a budget range are largely immune, which is one more argument for them at scale; fixed-item sends should define the substitution policy up front (an equivalent item, a budget credit, or hold and notify). Whatever the policy, the failure surface must end in a report the campaign owner can act on: every row accounted for as delivered, in flight, or needs attention.

Where to Start

Build the walking skeleton first: one chunked submit with deterministic idempotency keys, one webhook consumer, one reconciliation query. Then scale the list. Run the rehearsal in sandbox, including the failure drills above, before the real campaign.

The developer docs cover the orders API, the webhook events, and sandbox setup. The free trial runs 14 days with full API access and no credit card required: enough time to take a bulk integration from empty repo to a rehearsed campaign.

Launch My Free Trial