Watch Demo
Watch Demo
Most incentive programs start in a spreadsheet.
Someone exports a list of qualifying people, uploads it to a portal, and sends rewards in a batch. That works until the volume grows, the timing needs to be immediate, or the qualifying logic lives inside your own product.
A reward API is what replaces that spreadsheet.
This guide is written for the person who has to build the integration, not the person who has to approve it. It covers what these APIs actually do, how a sane integration is structured, the failure modes that cost real money, and the cases where you should not use an API at all.
For the wider context of how value reaches recipients, see what digital payouts are.
A reward API is a programmatic interface for sending incentives from your own systems.
Instead of a person deciding who gets rewarded and uploading a file, your application makes an authenticated request when someone qualifies. The provider handles reward delivery, redemption, and the underlying catalogue.
The useful mental model is that it turns rewards into an event in your product rather than an administrative task in someone calendar.
Underneath the marketing, most reward APIs expose four capabilities. If a provider is missing one of these, that is worth knowing early.
Evaluate providers against these before looking at pricing. A missing capability usually means manual work later.
Query this rather than hardcoding a list that will drift.
The one call that spends money. Treat it accordingly.
Redemption status is what you report on, not sends.
Programs fail silently when funds run out. Monitor this.
A well-built reward integration has four stages, and the fourth is the one most teams skip on the first attempt.
Your system owns eligibility. The provider owns delivery. The boundary between them should be one call and one callback.
Your application decides who is eligible. Never delegate this. Business rules belong in your code.
Send an authenticated issue call with a unique reference id you generate and store first.
Persist the provider response against your record before doing anything else, including retrying.
Consume webhooks for delivery and redemption. Without this you know what you sent, not what worked.
This is the single most important technical detail in a reward integration, and it is the one vendor marketing pages never mention.
A reward call spends money. If your request times out, you do not know whether the reward was sent. Retry blindly and you may have just paid twice.
Idempotency solves this. You generate a unique key for each logical reward, send it with the request, and the provider guarantees that repeating the same key returns the original result instead of issuing a second reward.
Three rules follow from that.
The failure this prevents is not theoretical. Duplicate payouts at volume are expensive and very awkward to claw back.
Issuing a reward is not the end of its lifecycle. It still has to be delivered, opened, and redeemed, and you want to know about all three.
Webhooks are the right default. The provider calls you when state changes, and you stay current without hammering their API.
Three things make a webhook consumer reliable. Verify the signature so you know the call is genuine. Respond quickly and process asynchronously, because slow handlers cause retries and duplicates. Make your handler idempotent, since you will receive the same event more than once.
Polling is the fallback when a provider has no webhooks or your network cannot accept inbound calls. It works, but expect to poll far less often than you would like and to build reconciliation anyway.
Most reward APIs draw from a prefunded balance.
That creates a failure mode that has nothing to do with your code. The integration is correct, the requests are valid, and rewards stop going out because the account is empty.
This usually surfaces as confused recipients rather than an alert, which is the worst way to find out. Monitor balance as an operational metric, alert on a threshold that accounts for your peak send rate, and make sure the alert reaches someone who can act on it rather than a mailbox nobody reads.
Never develop a reward integration against production. You will send real money to test recipients, and everyone does it at least once.
A usable sandbox should let you issue without spending, simulate redemption, and trigger failure cases such as an invalid recipient or an exhausted balance. If you cannot force a failure, you cannot test your error handling, and your error handling is the part that matters.
Test the timeout path deliberately. That is where idempotency either works or does not.
Distinguish three categories, because they need different responses.
A reward that fails quietly is worse than one that fails loudly. Someone was promised something.
A reward API key can move money, so treat it like a payment credential rather than an analytics token.
Keep keys server side, never in a mobile app or browser. Use separate keys per environment. Rotate on a schedule and immediately when someone leaves. Restrict by IP where the provider supports it, and log every issue call with the actor who triggered it.
Also rate limit your own endpoint that triggers rewards. If a bug or an attacker can call it in a loop, your balance is the limiting factor.
Integration has a real cost, and plenty of programs do not justify it.
Stay with manual or bulk sending when volume is low and predictable, when qualification is a human judgement rather than a rule, when the program is a one-off campaign, or when you are still testing whether the incentive works at all.
Build the API integration once the sending is repetitive, the timing needs to be immediate, or the eligibility logic already lives in your product. Automating a program you have not validated just means failing faster.
The most expensive omission on this list. Timeouts happen, retries happen, duplicate payouts follow.
Anything a browser or app can trigger, someone can trigger repeatedly. Qualification belongs on your server.
Sends are a cost. Redemptions are the outcome. Report the second.
Availability changes by market and over time. Query it instead.
In a batch of a thousand, some will fail. Decide in advance whether that stops the run or gets queued for review.
Sending incentives programmatically from your own systems, so rewards are triggered by events in your product rather than by someone uploading a file.
A unique value you attach to a request so that repeating it returns the original result instead of issuing a second reward. It is what makes retrying a timed-out call safe.
If you care about delivery and redemption rather than just sends, yes. Otherwise you know what you attempted, not what worked.
Server side only, separated by environment, rotated on a schedule. They can move money, so treat them like payment credentials.
Usually yes, but available rewards, denominations, and currencies vary by country. Query the catalogue per market rather than assuming parity.
Often not. If volume is low, timing is flexible, and eligibility is a human decision, bulk sending is cheaper and faster to run.
A good reward integration draws a clean line. Your system decides who earned what, because that logic is your business. The provider handles catalogue, delivery, and redemption, because that is infrastructure you should not rebuild.
Get three things right and the rest is ordinary engineering. Use idempotency keys so retries cannot pay twice. Consume webhooks so you measure redemption rather than sends. Monitor your balance so the program never stops silently.
And if the program is small and unproven, do not integrate at all yet.
If you are planning a reward integration and want to talk through the API and delivery model, talk to the ORBT team.
How global rewards distribution works: reward availability by market, value equivalence vs currency conversion, compliance, delivery, and what to localize.
Read More ➞
How gift card incentives work: open vs closed loop, choosing denominations, delivery, breakage, fraud, and when a gift card is the wrong reward to send.
Read More ➞
Digital payouts explained: how they work, the payout methods available, what small payouts really cost, and how to choose the right method for each recipient.
Read More ➞Built on global gift-card infrastructure, ORBT connects your business to thousands of brands, enabling seamless digital value distribution at scale.
Contact Sales