For better or for worse Amazon Gift Cards have become a standard in incentivizing customers and employees. Amazon Incentives API provides an easy and secure way of generating gift cards in real-time. Let’s see how we can make them a part of a referral program run with Voucherify.
What you can build with Amazon Incentives API
The primary feature of the Amazon Incentives API is to create virtual Amazon gift cards in real-time. But it enables a bunch of other interesting digital incentive scenarios too:
- Login And Receive — recharge a new or existing customer’s Amazon account when they log in (Amazon Login SDK necessary).
- Activate Physical Gift Cards — programmatically activate physical gift cards purchased in bulk earlier.
- Product Vouchers — create a gift card for a specific product category only (specs controlled by Amazon here).
The API also provides some brick & mortar gift card activity capabilities, go to the docs to learn more.
In this tutorial we’re going to cover real-time digital gift card generation which is a more secure and more convenient method to use them as referral rewards to buying gift cards in bulk.
API & portal access
Only verified partners can access the Amazon Incentives API. Verified means that you have Amazon Incentives partner ID — this is different from AWS solution partner ID. You can get this by filling out this form https://www.amazon-incentives.com/api/contact-us (For the Polish marketplace I waited ~2 weeks but it was a holiday season.)
Then, you can go to Step 2 of the onboarding guide.
The first API call
Note : Here’s a Postman collection with all API calls used in this tutorial.
Let’s test the API by creating a fake gift card within their Sandbox environment. We need three keys to authenticate a request: credentials and partner ID we obtained in the previous step.
To get credentials, go to /gc/corp/account/keys/, select Sandbox and create new access keys.
As with every Amazon service, the first step is to locate the right endpoint and region. For the Polish marketplace, the URL to Amazon Gift Codes On Demand (AGCOD) is https://agcod-v2-eu-gamma.amazon.com and the region is eu-west-1. You can find the reference here.
Also, any request needs to be signed with Signature Version 4 algo. If you test the API with Postman, then you can configure it in the Authorization tab as shown below (apart from credentials, remember to provide the respective region and service name: AGCODService).
According to the spec, we need to send the following payload to the /CreateGiftCard endpoint.
<CreateGiftCardRequest>
<creationRequestId>YourPartnerIDTSpecTest001</creationRequestId>
<partnerId>YourPartnerID</partnerId>
<value>
<currencyCode>PLN</currencyCode>
<amount>10.00</amount>
</value>
</CreateGiftCardRequest>
Caveats :
- currencyCode needs to match the currency set up in your Amazon Incentives API account.
- creationRequestId needs to start with your partner id as a prefix.
By invoking the request, you should get something like this:
<CreateGiftCardResponse>
<gcClaimCode>GVFW-Y9DWGW-K5BQ</gcClaimCode>
<cardInfo>
<value>
<amount>10.0</amount>
<currencyCode>PLN</currencyCode>
</value>
<cardStatus>Fulfilled</cardStatus>
</cardInfo>
<gcId>4510447105517016</gcId>
<creationRequestId>YourPartnerIDTSpecTest001</creationRequestId>
<gcExpirationDate>Sun Aug 21 21:59:59 UTC 2033</gcExpirationDate>
<status>SUCCESS</status>
</CreateGiftCardResponse>
Status Fulfilled means that the gift card certificate stored in gcClaimCode is ready to be shipped to the customer.
The developer portal should now be showing this:
How to store gift cards
Actually, you don’t need to. The AGCOD CreateGiftCard operation is idempotent, so if the API receives more than one request with the same creationRequestId, only the first request will result in the creation of a new gift card, and all subsequent responses will return the same original gift card. They will not be treated as different transactions.
This means you can use your customer identifier (up to 40 alphanumeric chars) to differentiate gift cards. Keep in mind that the service is rate-limited with 10 requests per second.
You can also import gift card codes to Voucherify. Importing them as regular codes will be helpful to track Amazon gift cards along with other rewards. The other way is to store them in a custom field in the Customer object.
Testing & error handling
Because gift card API deals with money directly, your integration needs to be rock solid. Good news is that the AGCOD architects prepared a rock solid test plan for your integration. The error codes list is also well-documented.
Highlights :
- In case of a mistake, you can cancel the gift card within 15 minutes after creation.
- You can simulate returning the error by any endpoint by providing a specific error code as a creationRequestId, e.g. F3003 will result in the endpoint returning F300 InsufficientFunds.
- Success response can be mocked by using mock code F0000.
- Six seconds is the recommended timeout for the client side application.
- If you suspect a bug at their end, the AGCOD team describes how and when they want to be bothered.
You can monitor the available funds with the portal (/gc/corp/payments/notifications/), where you can also set up alerts for low balance:
Or you can call /GetAvailableFunds, Sandbox will always return 0 though.
<GetAvailableFundsResponse>
<availableFunds>
<amount>0.0</amount>
<currencyCode>PLN</currencyCode>
</availableFunds>
<timestamp>20230821T154205Z</timestamp>
<status>SUCCESS</status>
</GetAvailableFundsResponse>
How to use Amazon Gift Cards in your referral program
Earlier this year, Taxfix, a prominent provider of tax filing services in Germany, introduced a two-sided referral program to increase their presence in the German market. Individuals who successfully referred their friends received Amazon gift cards as rewards. The Taxfix development team employed Voucherify and Braze to manage the program, and the operational process unfolded as follows:
By utilizing Voucherify, they set up a customized referral program that allowed them to reward successful referrers with Amazon gift cards and invited friends with -50% discount codes on their first tax return with Taxfix.. With every referral code application, Voucherify would send a webhook notification to the Taxfix system.
Next, they would call Amazon Incentives API to create rewards ($30 Amazon gift cards) for each successful referral.
The Taxfix team used Braze to divide their audience into different groups and prioritize those who were most engaged. They strategically encouraged these engaged users to refer more people by sending them push notifications and emails. The referral messages contained a deep link that took advocates to a specific view in the app, where they could find their personalized referral code.
So, to create an end-to-end referral reward experience, Taxfix:
- Generated referral codes in Voucherify.
- Defined the discount associated with the referral code.
- Defined a successful referral event — using the referral code during signup.
- Promoted referral program with Braze emails and push notifications including a deeplink to the referral view containing the referral code.
- When a referral event occured, they sent a webhook to the Taxfix backend system.
- Backend called the Amazon Incentives API to get a new gift card code and send it with a transactional email to the customer.
Scaling and improvements
The scenario covers only a single marketplace. If you want to create gift cards for more countries, you need to get a partner ID for each supported country.
You can think of other rewards and incentive campaigns, both digital and brick and mortar. For instance, you can use Product Vouchers to narrow down the gift scope to be applicable only to Education Assistance products or other good cause.
Another option is to replace Amazon gift cards with vouchers or discounts for your services. With Voucherify, you can manage digital gift cards and other incentives within one platform.
If you want to discuss options or get some help, drop me a line.
Top comments (0)