Amazon Gift Card Incentives API
The Incentives API provides programmatic endpoints you can use to perform these tasks in real time:
- Create claim codes that can be used on the Amazon website as currency to purchase products.
- Activate physical gift cards.
- Credit the gift card balance of a customer account through your app or website.
- Credit the gift card balance of a customer account at a brick-and-mortar site.
Your software can make synchronous requests to Incentives API endpoints. If your request results in a claim code, you can deliver this code to a customer in a manner that has been approved by Amazon.
- Service Information
- Tools
- API Response Changes
- Data Storage Guidelines
- Handling Errors
- Contacting Amazon for Technical Support
- Legal
Service Information
Endpoints
Requests from your code to any Incentives API include a base URL that is part of a full endpoint address. Your code will send requests to just one base URL that's determined by your country of operation. We also provide a Sandbox where you can call any Incentives API endpoint without consequences. The following tables show Sandbox and production base URL values for countries where the Incentives API is available.
Sandbox endpoints
Countries | Base Endpoint URL |
---|---|
North America (US, CA, MX) |
https://agcod-v2-gamma.amazon.com (region us-east-1 ) |
Europe and Middle East (IT, ES, DE, FR, UK, TR, UAE, KSA, PL, NL, SE, EG, BE, ZA) |
https://agcod-v2-eu-gamma.amazon.com (region eu-west-1 ) |
Far East (JP, AU, SG) |
https://agcod-v2-fe-gamma.amazon.com (region us-west-2 ) |
Production endpoints
Countries | Base Endpoint URL |
---|---|
North America (US, CA, MX) |
https://agcod-v2.amazon.com (region us-east-1 ) |
Europe and Middle East (IT, ES, DE, FR, UK, TR, UAE, KSA, PL, NL, SE, EG, BE, ZA) |
https://agcod-v2-eu.amazon.com (region eu-west-1 ) |
Far East (JP, AU, SG) |
https://agcod-v2-fe.amazon.com (region us-west-2 ) |
Building Requests to the Incentives API
Every request to an endpoint of the Incentives API must be digitally signed using your Incentives API security credentials and the Signature Version 4 signature algorithm. You can learn more about this signing process here.
Common Request Headers
The Incentives API requires the following headers in each HTTP request.
Header | Description/Value |
---|---|
method |
POST |
host |
A gateway endpoint listed under Endpoints. |
x-amz-date/date |
The date that is used to create the signature specified using either the x-amz-date or the date header. The format must be ISO 8601 basic format (YYYYMMDD'T'HHMMSS'Z'). See below for details. |
x-amz-target |
com.amazonaws.agcod.AGCODService.<operation> The Login and Receive service provides the following operations: LoadAmazonBalance, VoidAmazonBalanceLoad, GetAvailableFunds |
Authorization |
The information required for request authentication including: AWS4-HMAC-SHA256, Credential, SignedHeaders, and Signature. For more information about constructing this header, see Signing Requests. |
accept |
When set to */* , defaults to XML. Set to application/json to receive results as a JSON body. |
content-type |
application/json or application/xml |
regionName |
Region endpoint. See Endpoints table above. |
serviceName |
The name of the service, AGCODService |
region |
us-east-1 |
amz_target |
com.amazonaws.agcod.AGCODService.CreateGiftCard |
request_parameters |
Copy body from a request made in Incentives API Scratchpad that uses a JSON body |
access_key, secret_key |
Provide your keys |
canonical_url |
/CreateGiftCard |
For x-amz-date/date
, the following date time is a valid x-amz-date
value: 20120325T120000Z
. The x-amz-date
header is optional for all requests. If the date
header is specified in the ISO 8601 basic format, x-amz-date
is not required. For more information, see Handling Dates in Signature Version 4 in the Amazon Web Services General Reference.
Throttle Rates
The Incentives API will throttle/decline incoming requests to prevent misuse of the system. The request rate cannot exceed more than 10 per second, inclusive of all transaction types. These are only applicable if you are using Web Creation APIs
API | Throttle rate (# of requests) |
---|---|
CreateGiftCard |
10 per second |
CancelGiftCard |
10 per second |
ActivateGiftCard |
10 per second |
DeactivateGiftCard |
10 per second |
ActivationStatusCheck |
10 per second |
GetAvailablefunds |
1 per second |
When requests from your code exceed a throttle rate, your request fails and a ThrottlingException is returned:
<ThrottlingException>
<Message>Rate exceeded</Message>
</ThrottlingException>
Tools
Incentives API Scratchpad
You can call some Incentives API operations in a Sandbox using the Incentives API Scratchpad. By revealing the details of the request and response, this tool can demonstrate how a call to an Incentives API operation should look.
content_type
header, which is set to application/json
.Incentives API Samples
We also provide sample code Java, C#, Python, Ruby, PHP, and HTML (JavaScript). These samples are customized to call most Incentives API operations.
- Java sample
- You can select the request body format by commenting on the line of the non-preferred format.
- C# sample
- In the AwsAuthenticator constructor, set the
namespace
parameter tocom.amazonaws.agcod
- In the AwsAuthenticator constructor, set the
- Python sample
- Ruby sample
- PHP sample
- HTML sample
Notes:
- The sample code does not have good error handling therefore it is not “Production Ready”; they should only be used as a guide.
- The Secret Key / Access Key / PartnerId appear in this source code in clear text.
- This source code and secrets within it could be revealed in some scenarios, including scenarios where an unhandled error leads to a non-deterministic behavior in the program.
Provide the following parameters using your own specific values prior to testing:
partnerId
- Acme1currencyCode
– USD for US, EUR for EU, JPY for JP, CAD for CA, AUD for AU, TRY for TR, AED for UAEagcodAccessKey
- your-security-credentialagcodSecretKey
- your-security-credentialregion
–us-east-1
(will vary depending on location and environment – see regions and endpoints)endpoint
- (will vary depending on location and environment – see regions and endpoints)
Incentives API Portal
In the Incentives API Portal, you can:
- View Account balance, average daily spend (over last 14 days), days remaining (based on average spend), alerts.
- View detailed transaction activity, in browser or as a download.
- Set low balance amount alerts.
- Notify Amazon that you've made a payment.
- (IT Managers only) Create new access keys and control existing keys.
- Generate Proforma Invoices
- (Administrators only) Manage users and roles.
API Response Changes
Responses from Incentives API endpoints frequently include information in XML or JSON data interchange format. In the future, new attributes might be added to these responses, and elements may appear in a different order. Your code should handle future changes in the XML or JSON of a response body gracefully by using an XML or JSON parser. For example, XPath parses values from XML content using an expression syntax. A parser library is more reliable when the schema of an XML or JSON response body changes or grows.
Data Storage Guidelines
This section outlines some best practices for handling CreateGiftCard
results, especially gcClaimCode
values.
Also review the information security requirements in the Amazon Corporate Gift Card Purchase & Distribution Terms, including the Security Best Practices in the Corporate Gift Card Policies in the Amazon Incentives API Services Terms located here.
Guidelines for requesting and storing gift card claim codes returned from a successful call to CreateGiftCard:
- Your client code generates a unique
creationRequestId
value for each new call to theCreateGiftCard
operation. - Your client code should store the
creationRequestId
,amount
, andcurrencyCode
values used in each request. - Amazon stores every
gcClaimCode
. After you have generated a Gift Card claim code, your code can retrieve the same gift card claim code again by submitting a new request toCreateGiftCard
using the samecreationRequestId
,amount
, andcurrency
code values. This can be a more secure alternative to storing gift card claim codes in your database. - You should not store claim codes. If your code retains gift card claim codes temporarily, these values must be disposed of after you have delivered the gift card claim code to the customer.
- If you need to cancel a gift card claim code, your code must call CancelGiftCard within 15 minutes of code creation.
Handling Errors
Each response sent from the web service gateway has an associated status element that describes the execution status for the particular operation.
There are three status values SUCCESS
, FAILURE
and RESEND
. See below for guidance, especially for handling
the RESEND
result with retry logic.
Error Handling
Every response sent from the AGCOD Gateway has an associated Status element that describes the execution status for the particular operation; there are three statusCode
values: SUCCESS
, FAILURE
, and RESEND
.
SUCCESS
An operation response includes a statusCode
value of SUCCESS
when the operation is successful.
FAILURE
An operation response includes a statusCode
of FAILURE
when the request cannot be honored by the Incentives API. This status response may include invalid request data or some business logic error that needs to be reviewed by the partner. The errorCode
field will be populated in such cases providing additional details pertaining to the error.
RESEND
An operation response includes a statusCode
of RESEND
and an F400 error when there is a temporary system failure that can probably be resolved by retrying the request. It is important that your code provides retry logic, because an F400 error is an "unknown state" that can result in charges to your account. **The RESEND
error should not be interpreted as a failure.
Note:
The following steps show the backoff strategy for a call to ActivateGiftCard
/DeactivateGiftCard
. Your code should also use this backoff strategy for calls to CreateGiftCard
/CancelGiftCard
and to LoadAmazonBalance
/VoidAmazonBalanceLoad
.
- When your request returns an F400 error message, if you can just retry the same ActivateGiftCard operation again, just retry this operation. If you cannot retry, proceed to Step 2.
- Send a
DeactivateGiftCard
operation using the samerequestId
value. - If the call to
DeactivateGiftCard
returnsSUCCESS
, callActivateGiftCard
again using a newrequestId
value. - If the call to
DeactivateGiftCard
fails, pause one second and send the sameDeactivateGiftCard
request again. - If ten seconds elapse without a successful
DeactivateGiftCard
request, increase the delay using an exponential backoff scheme. - After 24 hours, please stop retrying and send an email to Amazon that contains details of the failed operations.
Error Codes
Find a list of production and mock error codes in Errors and Mock Errors.
Contacting Amazon for Technical Support
Throughout the development and integration process, technical questions can be directed to Partner Integration Team here.
It is important to include your Partner ID in communications with our developers to ensure they can easily identify your account. In your communication please provide as much of the following information as possible (as applicable)
- Complete Request/Response pair of your call to Incentives API
- Complete endpoint URL used (including the Server URL) to make the request
- The
StringToSign
value used in the request, if not already in the Request/Response above - The corresponding signature of the
StringToSign
value used, if not already in the Request/Response above - Approximate time (with time zone) used in your request (the time zone that is configured on the machine making the above request)
- Programming language used
- Any recent changes (both programming and infrastructure) on your end
- Screenshot of error
Legal
By integrating with and using the Incentives API, you (on behalf of yourself or the business you represent) agree to be bound by the Amazon Corporate Gift Card Purchase & Distribution Terms.
Next Below are the products available on the AGCOD API
- Digital Gift Cards
- Pin on Receipt for B&M Guide
- Activate Physical Cards
- Point of Sale Activation
- Login and Receive
- LoadAmazonBalance (Amazon Cash)
- Product Voucher Guide
Last updated: Sep 10, 2021