Sign In
Sign In

Amazon Incentives API - FAQs

The Incentives API lets partners create and distribute Amazon Gift Card claim codes quickly through the internet.

Non-developer FAQ

Q: What does the Amazon Incentives API allow me to do?
We currently support four key API features:
• CreateGiftCard - Create an Amazon Gift Code (GC) on-demand for your customers.
• ActivateGiftCard - Activate a physical Amazon Gift Card on-demand for your customers.
• Login and Receive - Load a GC into a customer account within your app or website.
• LoadAmazonBalance - Add funds to a customer account on your storefront site.
• GetAvailableFUnds - Check your Amazon Incentives account balance via API
Q: How is purchasing through the Amazon Gift Card API different from purchasing through the Bulk Ordering Portal?
Instead of purchasing gift cards through the bulk ordering portal, the Amazon Gift Card API (application program interface) supports the creation and activation of both physical and digital gift cards on demand in real-time. Codes ordered through the API are available instantly and can support any number of use cases that require a quick turnaround or automation.
Q: What Gift Code denominations are available?
Digital Gift Card denominations are customizable. Each marketplace has a minimum and a maximum denomination which is available. These are shown on each of the product pages. To provide a brief example, in the US, Digital Gift Card can range from $0.15 to $2,000. Physical Gift Card denominations range from $1 to $2,000. $2,000 is the maximum amount that can be applied and purchased for an individual Amazon Gift Card.
Q: What is the validity period of Gift Codes?
Validity periods vary between countries. Gift Cards purchased for use in US and Canada never expire, while Gift Cards purchased through all EU websites for use in respective EU locales or through Amazon.jp for use in Japan expire after 10 years.
Q: How do I get started integrating with the API?
You can get started by filling out this form and an account manager will get in touch with you to discuss next steps.
Q: How do I pay for Amazon Gift Card API Orders?
Since gift cards are issued in real time, the amount per gift card will be deducted from your account in real time. This requires that you have funds available in your account before you start ordering gift cards. For any additional support related to payments, please contact your account manager or corp-gc-salesops@amazon.com.
Q: What should I include in my wire payment notes to ensure my payments are received correctly?
Please include your Payment Matching ID. You can find this code in “How to send a Payment” under the Support menu on the Incentives Portal. Please ensure you’re including this ID in every wire payment your organization sends. Without this ID, your payment may not be applied or for customers with multiple Amazon Incentives accounts, applied to the wrong account. Please allow at least 3 business days to see your payments.
Q: When should I expect to see my payments reflected in my API account?
Please allow at least two business days to see your payments in your account. It may take longer for your first payment to arrive and, if a Payment Matching ID is not included on wire payments, our team may reach out to ensure we are applying that payment correctly for you.
Q: How can I track my API transactions?
Tracking transactions on your API account is easy. In the API ordering portal (linked by region below), click Detailed Activity on the left side of the screen. You can download account activity as a file for use in a spreadsheet or database.
US CA MX FR IT ES DE UK AE TR
JP AU SA SE SG NL PL EG BE ZA
Q: After creating a code, am I able to cancel it?
We do not recommend cancelling codes once they have been issued. If you must cancel a code, however, the cancel operation must be performed within 15 minutes of creation.
Q: What is a Partner ID?
A Partner ID is a unique identifier for you to use within the Amazon Gift Card API. As part of on-boarding, you will receive a Partner ID in your welcome email. If you need to confirm your Partner ID or if you’ve lost your welcome email, please reach out to your account manager or email incentives-api@giftcards.amazon.com.
Q: How does security work with the API?
The Amazon Gift Card API uses secure data transmission, with endpoint certificates that support SHA-256 or better (TLS 1.2). This meets the Payment Card Industry (PCI) Data Security Standard. Each request is also signed using AWS Signature Version 4, which encrypts contents using your secret key.
Q: What are access keys?
Your API credentials consist of two parts: an access key ID and a secret access key. Like a user name and password, you’ll need to use both to authenticate your requests in the API portal. Access keys are credentials you use to sign your requests to call the API.
Q: What is Self-Service Key Management?
Self-Service Key Management is a self-service tool that enables you to generate and manage both access key and secret key within the Incentives API portal. To manage your keys, open the Incentives API portal for your national marketplace. In the portal, click API security credentials. Alternatively use the URL below.
US CA MX FR IT ES DE UK AE TR
JP AU SA SE SG NL PL EG BE ZA
Q: What are some best practices for refreshing my account’s credentials?
From a security standpoint, we recommend that you rotate (change) your access keys about every 90 days (three months). Changing access keys on a regular basis is an effective and widely used security practice that reduces the impact on your business if a key is compromised.

To encourage regular key rotation, you will receive an email 30 days before the keys should be rotated. If you have questions, please contact your account manager or incentives-api@giftcards.amazon.com.

Q: How do I change my access keys?
To rotate access keys, follow these steps:

Step 1. In the API portal (linked by region below), click “API security credentials”. (If you are unable to see the page, reach out to an Administrator at your company. Only an account that has IT Manager access can see the API security credentials page.)

Step 2. Create a second access key in addition to the one in use.

Step 3. Update all of your applications to use the new access key and validate that you are able to make successful requests to the APIs you use.

Step 4. Change the state of the previous access key to inactive.

Step 5. Carefully validate that your applications are still working as expected. This validation is important, as once an access key is deleted, it cannot be recovered.

Step 6. Delete the inactive access key.

US CA MX FR IT ES DE UK AE TR
JP AU SA SE SG NL PL EG BE ZA
Q: I’ve received an error! What should I do?
Common errors in the API portal are listed below, along with some instructions on how to resolve them. Please refer to the error handling section in the Technical documentation here. If you need assistance resolving an error, please email incentives-api@giftcards.amazon.com.

• F200 - “The request signature we calculated does not match the signature you provided. Check your AWS Secret Access Key and signing method. Consult the service documentation for details” - Your access key and secret key do not match. Please check your credentials again. Please email incentives-api@giftcards.amazon.com if you are still seeing this error after a few tries.

• F300 - “Insufficient Funds” - You do not have enough credits or funds to create, activate, or load balance onto a gift card. Please reach out to your local Operations team (listed by region below) for support.

• F300 - “ActiveContractNotFound” - You do not have a valid contract to create, activate, or load balance. Please reach out to your local Operations team (listed by region below) for support.

• F400 - “SystemTemporarilyUnavailable” – There is a system error, but you can try placing your order again. Please Cancel, Deactivate, or Void your original request ID, then Resend, Create, Activate or BalanceLoad API.

Q: What are the guidelines for claim code storage?
Partners are not permitted to store claim codes. Please refer to the Gift Codes Storage Guidelines.
Q: How can I contact Amazon in case of an outage?
For any outage, please follow the steps outlined here.
Q: Where can i find the Technical Documentation
For detailed and up to date technical documentation please go here.
Q: How do i Contact the Gift Card Operations Team (Non Technical)
For questions related to orders or payments, please contact your regional Operations team, listed below.
North America: corp-gc-salesops@giftcards.amazon.com
Japan: jp-gc-salesops@giftcards.amazon.com
Australia: amazonaucorpgc@giftcards.amazon.com
United Kingdom: corporate-gifts@giftcards.amazon.com
Germany: gutscheine-grosskunden@giftcards.amazon.com
France: cartes-cadeaux-entreprises@giftcards.amazon.com
Spain: cheques-regalo-empresas@giftcards.amazon.com
Italy: buoni-regalo-imprese@giftcards.amazon.com
Netherlands: amazon-incentives-nl@giftcards.amazon.com
United Arab Emirates: uae-gc-operations@giftcards.amazon.com
Turkey: amazon-bm-gc-inbox-eu@amazon.com
Singapore: sg-gc-salesops@giftcards.amazon.com

If you need further technical assistance, please feel free to contact us at incentives-api@giftcards.amazon.com.

↑ Back to top

  • Next - Go to Outage & Maintenance here.

Developer FAQ

Q: What is the recommended amount of time for timeout settings?
Six seconds is the recommended timeout for the client side application.
Q: After creating a code, are there any time limits to how long after it’s creation it can be cancelled?
We do not recommend cancelling codes once they have been issued. However, if you feel it is necessary to cancel a code, the cancel operation must be performed within 15 minutes of creation.
Q: How frequently can a partner account call an endpoint?
Calls to any endpoint should not exceed 10 per second, or a ThrottlingException will be returned. For details, see Throttle Rates.
Q: What happens if there are not sufficient funds in the account to cover a request?
If there are not sufficient funds, the Incentives API operation will return an F300 error and not activate the gift card. It is important that you accurately forecast your Gift Card volumes and maintain a contingency for unanticipated demand. Work with your Account Manager to determine the best approach.
Q: I get “F300 Issuance Cap Exceeded” error when I try to create a Gift Card Claim Code.
This might be caused by the Issuance Cap being exceeded for non-FPS prepay partners if nothing else has changed on the partner’s side. If you are receiving this error in Production it is likely related to exceeding the amount of funds you have in your account. To find out more contact your Account Manager. If you are receiving this error in Sandbox contact Amazon to assist you further.
Q: I get “Max Amount Exceeded” error when I try create a Gift Card Claim Code
Make sure the amount of the Gift Card you are activating does not exceed $2,000 in the US as restricted by law (other countries might have a different limit). See a list of transaction amount limits in nine countries.
Q: I am getting this error: F200 Pre Denomination Mismatch
This is often caused by making a second call to CreateGiftCard using a creationRequestId value that was used previously in a request to CreateGiftCard that specified a different amount value. If your request uses the same creationRequestId and same amount value, the call reports success and returns the results returned previously by the original request. This happens because this endpoint is idempotent, so multiple identical calls to the endpoint are equivalent to just one call.
Q: I’m getting a lot of F500/F200 errors, but I cannot figure out what’s wrong on my side. What’s going on?
F500 errors are usually caused by timeouts on the Amazon side. If you seeing a regular occurrence of these contact Amazon. F200 errors are usually a result of a submission that contains invalid information. If the information being submitted has been verified, contact Amazon for assistance.
Q: I am getting this error: The String-to-Sign should have been 'AWS4-HMAC-SHA256/…./us-east-1/AGCODService/aws4_request…
This might be caused by an invalid access key. Verify that access key is correct, that it is for the correct environment (Sandbox vs. Production), and confirm the locale for the endpoint being used is correct. Also, make sure to prefix the key qualifier “AWS4” to the secret key when constructing the derived signing key (kSecret) per here. Additionally, you can follow this troubleshooting guide here and resolve some other common signature related errors.
Q: I am getting this error: <Message>Missing Authentication Token</Message>
This might be caused by specifying the wrong endpoint (e.g., https://agcod-v2.amazon.com instead of https://agcod-v2-gamma.amazon.com or the appropriate endpoint for your locale). Verify the endpoint being used is accurate and it is for the correct environment (Sandbox vs. Production) and locale.
Q: I am getting this error: HTTP Status 400 - There was an error while processing the request. The request does not match any of the supported protocols.
This is often caused by making a request to the incorrect endpoint. Verify you are using the correct endpoint.
Q: Does the Incentives API support HTTP GET operations?
No, only POST is supported.
Q: I get “Request Id Must Start With Partner Name” error, but I checked and have the correct Partner Name?
Partner ID is case sensitive. Also, make sure the endpoint/locale is correct (Sandbox vs. Production and NA vs. EU).
Q: Does the Incentives API support SOAP or Query?
No, it only supports RESTful requests.
Q: I am getting javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target error when I run the sample code?
This might be caused by not having the “VeriSign Class 3 Public Primary Certificate Authority – G5” and/or “Verisign Class 3 Secure Server CA – G3” CA cert, (see screenshot below) which is the root/intermediate CA signer of the SSL cert used at our endpoints, in your Java keystore.
Result:
The cert should be automatically populated when you install JRE/JDK on the machine where Eclipse (or other IDE) is installed. You can use the built-in Java keytool (only available in JDK, not JRE) to import the cert to the Java keystore or run the sample code from a different machine with the root/intermediate CA signer cert installed. Importing CA cert is outside the scope of AGCOD support. Reference the links below for more additional information. Also, consult your Java/Eclipse documentation if you need additional help on the following methods.
Method 1 - this method may be challenging, but has proven to resolve the issue.
  • http://javarevisited.blogspot.com/2012/03/add-list-certficates-java-keystore.html
  • http://wiki.eclipse.org/Generating_a_Private_Key_and_a_Keystore

Method 2 – may be easier for you

Alternatively, you can import the cert to the Java keystore using an Eclipse plug-in call keytool:
  • http://keytool.sourceforge.net/installing.html or
  • http://sourceforge.net/projects/keytool/?source=pdlp

Once the plug-in is installed, configure the keystore location (your keystore location might vary depending on your OS or location of your keystore). Default keystore password is Changeit.

Q: I am getting this error: <Message>The security token included in the request is invalid.</Message>
This might be caused by an invalid security access key. Verify that your access key is correct, that it is for the correct environment (Sandbox vs. Production), and confirm the locale for the endpoint being used.

↑ Back to top

Next

Last updated: Sep 22, 2021