Amazon Incentives API - FAQs

Integration Technical Specification - FAQs

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

Non-developer FAQ

See also: For more higher-level FAQ answers about the Incentives API, see Incentives API FAQ on the signup page.

Q. What is a partner ID?

A: Partner ID is a unique identifier we provide that you will use with the Incentives API. As part of on-boarding, you will receive a partner ID.


Q. What is Self-Service Key Management?

A: 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. Note: Only the account that has administrator access can see the API security credentials page. You can ask us to give an account administrator access by emailing us at incentives-api@amazon.com.


Q: What are the guidelines for claim code storage? What information are we allowed to store?

A: Partners are not permitted to store claim codes. See Handling Gift Card Claim Codes.

Developer FAQ

What is the recommended amount of time for timeout settings?

Six seconds is the recommended timeout for the client side application.


After creating a code, are there any time limits to how long after its 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.


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.


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.


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.


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.


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.


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.


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. Also, make sure to prefix the key qualifier “AWS4” to the secret key when constructing the derived signing key (kSecret) per http://docs.aws.amazon.com/general/latest/gr/sigv4-calculate-signature.html.


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://agocd-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.


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.


Does the Incentives API support HTTP GET operations?

No, only POST is supported.


How do I get the one-click Gift Card redemption experience where the customer does not have to type in the Claim code?

The Amazon Gift Card Redemption page appends an encrypted claim code in the url. So, in the url https://amazon.com/g/claimcode You have to use encrypted claim code instead of actual claim code in the code parameter. If you want to show redeem page with real plaintext claim code you can use https://amazon.com/gc/redeem?claimCode =XYZPQR


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).


Does the Incentives API support SOAP or Query?

No, it only supports RESTful requests.


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.

Method 2 – may be easier for you

Alternatively, you can import the cert to the Java keystore using an Eclipse plug-in call keytool:

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.


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.


Last updated: Oct 30, 2020