Amazon Gift Card Incentives API

Please make sure to set up your Amazon Incentives API account before starting integration. Create Incentives API account.



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.

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.

Note: The underlying IP addresses of these endpoints change frequently based on geography and load. Do not hardcode IP addresses in your code or in your firewall whitelist. Only use the full DNS addresses shown here to reach our endpoints.

Sandbox endpoints

Countries Base Endpoint URL
North America
(US, CA, MX)
https://agcod-v2-gamma.amazon.com
(region us-east-1)
Europe
(IT, ES, DE, FR, UK, TR, UAE)
https://agcod-v2-eu-gamma.amazon.com
(region eu-west-1)
Far East
(JP, AU)
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
(IT, ES, DE, FR, UK, TR, UAE)
https://agcod-v2-eu.amazon.com
(region eu-west-1)
Far East
(JP, AU)
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. Signing correctly using Signature Version 4 can be the toughest hurdle when calling Incentives API endpoints. This section describes resources you use to build your signing code.

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.

Note: When passing a request with a JSON body, the scratchpad does not show the content_type header, which is set to application/json.

AWS Signature Version 4 Sample code

Signature Version 4 is an AWS standard. AWS documentation includes code snippets that can call an operation using this signature. The following table shows parameters you can modify in the Python POST example found at Examples of the Complete Version 4 Signing Process. With these modifications, the Python code calls the CreateGiftCard operation in the North America Sandbox using a JSON body:

parameter value
service AGCODService
host agcod-v2-gamma.amazon.com
region us-east-1
endpoint https://agcod-v2-gamma.amazon.com/CreateGiftCard
content_type application/json
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

Also find additional snippets in Java, C#, Python, Ruby, and JavaScript: Examples of How to Derive a Signing Key for Signature Version 4

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.

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 - Acme1
  • currencyCode – USD for US, EUR for EU, JPY for JP, CAD for CA, AUD for AU, TRY for TR, AED for UAE
  • agcodAccessKey - AKIAJE2RAAV7RP2WROKA (not valid, example only)
  • agcodSecretKey - Vgjd4AjpU0Sm6IYNDjRRX9nZOA+VPxwaF5K43G9K (not valid, example only)
  • regionus-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)

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

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. The time stamp must be within 15 minutes of the Amazon system time when the request is received. If it isn't, the request fails with the RequestExpired error code to prevent someone else from replaying your requests.

Implementing Signature Version 4

The samples listed above might not cover your scenario. To implement Signature Version 4 from scratch, start by studying these topics:

Every REST operation request your code sends must include a signature. To sign a request, you create a string that includes the text of your request along with your secret access key. You pass this string to a cryptographic hash function, which returns a hash value. You include this hash value in the Signature field of the Authorization header of your REST operation request. Before handling your request, our services recalculate the signature using the same inputs, and confirm your Authorization hash value matches our own calculation.

The API gateway supports authentication using AWS Signature Version 4. The process for calculating a signature can be broken into three tasks:

Task 1: Create a Canonical Request

Create your HTTP request the canonical format described in Task 1: Create a Canonical Request for Signature Version 4 in the Amazon Web Services General Reference.

Task 2: Create a String to Sign

Create a string that you will use as one of the input values to your cryptographic hash function. The string, called the string to sign, is a concatenation of the name of the hash algorithm, the request date, a credential scope string, and the canonical request from the previous task. The credential scope string itself is a concatenation of date, region, and service information.

For the x-amz-credential parameter, specify the code for the endpoint where you will send the request, for example, us-east-1. Find your region in the Endpoints tables. Example:

x-amz-credential=AKIAIGHKAVYIDBOH3O3A/20170118/us-east-1/AGCODService/aws4_request

Important: You must use lowercase characters for the Region, service name, and special termination string. The x-amz-credential header is used when authentication parameters are added to the query string. They are as easily added to the single Authorization header, and in that instance, x-amz-credential does not appear. So it's a bit confusing to mention x-amz-credential, a keyword that is only used in a particular instance, and isn't required. Its value is required, but the x-amz-credential is only required when query string parameters are used to carry authentication.

Task 3: Create a Signature

Create a signature for your request by using a cryptographic hash function that accepts two input strings: your string to sign and a derived key. The derived key is calculated by starting with your secret access key and using the credential scope string to create a series of hash-based message authentication codes (HMACs). The following diagram illustrates the general process of computing a signature:

Signed Request Example

Payload to sign

{"loadBalanceRequestId":"Amazon123456","partnerId":"Amazon","amount":{"currencyCode":"USD","value":"1000"},"transactionSource":{"sourceId":"Customer Service"},"account":{"id":"amz1.account.123512341234","type":"2"}}

Hashed Payload

24921f8ae68d62e1d96fd98e33f28da3e52826f43c5fa0389bfa33817e2711a1

Canonical request (include empty lines)

POST /LoadAmazonBalance

accept: application/json
content-type: application/json
host: agcod-v2-gamma.amazon.com
x-amz-date: 20160708T073147Z
x-amz-target: com.amazonaws.agcod.AGCODService.LoadAmazonBalance

accept;content-type;host;x-amz-date;x-amz-target 24921f8ae68d62e1d96fd98e33f28da3e52826f43c5fa0389bfa33817e2711a1

Hashed Canonical request

a6a2e4283152cbcc7114409dfbc3dda721663f4bb14b6e34f8e1f71c374f9c14

String to sign

AWS4-HMAC-SHA256
20160708T073147Z
20160708/us-east-1/AGCODService/aws4_request
a6a2e4283152cbcc7114409dfbc3dda721663f4bb14b6e34f8e1f71c374f9c14

Derived signing key

780860beb9efce461eaee56c38d7f904cf1b803cd9ea6f2c3402415b92af9453

Signature

Your signature will be different, because you have different security access key credentials, but will follow this format:

66bd6a9ee258bcc34b7c0084ef871f2cb734e579b26f62ffce3ca1a33c06074a

Signed payload

POST /LoadAmazonBalance HTTP/1.1
accept:application/json
content-type:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20160708T073147Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadAmazonBalance
Authorization:AWS4-HMAC-SHA256 Credential=<AWS Key Id used for signing>/20160708/useast-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=66bd6a9ee258bcc34b7c0084ef871f2cb734e579b26f62ffce3ca1a33c06074a
{"loadBalanceRequestId":"Amazon123456","partnerId":"Amazon","amount":{"currencyCode":"USD","value":"1000"},"transactionSource":{"sourceId":"Customer Service"},"account":{"id":"amz1.account.123512341234","type":"2"}}

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 Error Handling for guidance, especially for handling the RESEND result with retry logic.

Troubleshooting your signature signing code

Check the following common coding errors at Examples of How to Derive a Signing Key for Signature Version 4.

Common coding errors include:

  • Inadvertently swapping the key and the data when calculating intermediary keys. The result of the previous step's computation is the key, not the data. Check the documentation for your cryptographic primitives carefully to ensure that you place the parameters in the proper order.
  • Forgetting to prepend the string "AWS" in front of the key for the first step. It is possible to implement the key derivation using a “for loop” or iterator. When you do, do not forget to special-case the first iteration so that it includes the "AWS" string.
  • Forgetting to use the asBytes option for the JavaScript HMAC.Crypto function. If you do not use the asBytes option, the HMAC implementation will perform an additional hex encoding by default.
  • Make sure the query string in your request is both properly sorted and encoded, the header names have been converted to lowercase characters and the headers have been sorted by character code. See Create a Canonical Request for Signature Version 4.
  • For JSON body requests, only content_type set to application/json will succeed.

Secure Data Transmission

Incentives API endpoints are open ONLY through a secure port (HTTPS) and all traffic over this channel is secured using SSL/TLS 1.2. This industry standard protocol encrypts gift card data while in transit. You are required to provide your own secure mechanisms within your systems to prevent unauthorized access to encryption keys used by SSL/TLS 1.2.

Important: API requests must use TLS 1.2 or above.

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.

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.
  • (Administrators only) Create new access keys and control existing keys.

Handling Keys

Access keys are credentials you use to sign your programmatic requests to any Incentives API endpoint. Like a user name and password, you must use both the access key ID and secret access key together to authenticate all your requests.

A partner account that has administrator permissions can new access keys and control existing keys from within the Incentives API Portal, on the API security credentials page. (A partner account that does not have administrator permissions cannot see this page. You can ask us to give an account administrator access by emailing us at incentives-api@amazon.com.)

Security for credentials

The access keys and secret keys provided on the API security credentials page must be secured from unauthorized access and accidental release. This is true for both production and sandbox credentials. Security of your system and your funds relies on secure handling of these secrets. Do not share your keys.

Rotating keys

Changing access keys on a regular schedule is a well-known security best practice that reduces the business impact of a compromised key. As a security best practice, we recommend that you regularly rotate (change) your access keys. Performing an established process regularly also ensures the operational steps around key rotation are verified, so changing a key is never a scary step for your organization.

You should change your access keys at least once every 180 days (6 months). You will receive an email 30 days before the keys should be rotated as a reminder to initiate the process. If you have questions please contact your account manager or incentives-api@amazon.com.

To rotate access keys, follow these steps:

  1. In the Incentives API portal, click API security credentials.
  2. Click Create new access key.
  3. Update all your applications to use the new access key.
  4. Confirm that all requests to Incentives API operations are succeeding using the new key values.
  5. For the original key, click Deactive.
  6. Confirm again that all requests to Incentives API operations are succeeding using the new key values. Be sure! Once an access key is deleted, it cannot be recovered.
  7. For the original key, click Delete.

The new key is now in use and the original key is now inactive and cannot be used again.

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 at https://www.amazon.com/gp/help/customer/display.html?nodeId=202120960.

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 the CreateGiftCard operation.
  • Your client code should store the creationRequestId, amount, and currencyCode 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 to CreateGiftCard using the same creationRequestId, amount, and currency 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. (See Security.)
  • If you need to cancel a gift card claim code, your code must call CancelGiftCard within 15 minutes of code creation.

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.

API Throttle rate (# of requests)
CreateGiftCard
(only applicable if you are using Web Creation APIs)
10 per second
CancelGiftCard
(only applicable if you are using Web Creation APIs)
10 per second
ActivateGiftCard
(only applicable if you are using Web Activation APIs)
10 per second
DeactivateGiftCard
(only applicable if you are using Web Activation APIs)
10 per second
ActivationStatusCheck
(only applicable if you are using Web Activation APIs)
10 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>

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.

  1. 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.
  2. Send a DeactivateGiftCard operation using the same requestId value.
  3. If the call to DeactivateGiftCard returns SUCCESS, call ActivateGiftCard again using a new requestId value.
  4. If the call to DeactivateGiftCard fails, pause one second and send the same DeactivateGiftCard request again.
  5. If ten seconds elapse without a successful DeactivateGiftCard request, increase the delay using an exponential backoff scheme.
  6. 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 (requires active contract/agreement)

Throughout the development and integration process, technical questions can be directed to Amazon.

Please note that if you do not have an active agreement and have not been given Sandbox access, you likely will not be recognized by the developers that monitor this alias. It is important that you work with your Account Manager to follow the steps required to get Sandbox access.

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.