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
  • Endpoints
    • Sandbox endpoints
    • Production endpoints
  • Building Requests to the Incentives API
  • Common Request Headers
  • Throttle Rates
• Tools
  • Incentives API Scratchpad
  • Incentives API Samples
  • Incentives API Portal
• API Response Changes
• Data Storage Guidelines
• Handling Errors
  • Error Handling
  • Error Codes
• 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

Production endpoints

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.

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

When requests from your code exceed a throttle rate, your request fails and a ThrottlingException is returned:

<ThrottlingException>
  <Message>Rate exceeded</Message>
</ThrottlingException>

↑ Back to top

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.

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 to com.amazonaws.agcod
• 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 - Acme1
• currencyCode – USD for US, EUR for EU, JPY for JP, CAD for CA, AUD for AU, TRY for TR, AED for UAE
• agcodAccessKey - your-security-credential
• agcodSecretKey - your-security-credential
• region – 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.

↑ Back to top

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.

↑ Back to top

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 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.
• If you need to cancel a gift card claim code, your code must call CancelGiftCard within 15 minutes of code creation.

↑ Back to top

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.

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.

↑ Back to top

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

↑ Back to top

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.

↑ Back to top

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