Onboarding Process - Gift Card API

Thank you for choosing to integrate your application with the Amazon Incentives API. The steps below will guide you on how to integrate your platform with each of our API products. If you have any questions, please visit our frequently asked questions (FAQs) or email our integration team at incentives-api@giftcards.amazon.com.

Note: Please be sure to include your Partner ID in all correspondence. Don’t have one yet? Go to our Contact Us page to reach out to one of our account management team who can provide you with a Partner ID

Getting started
API Access Keys
Post Launch Tools
FAQ
Contact Us

Getting started

Complete the steps below to get started with Amazon Incentives:

Create a new Amazon Account
Setting up the Amazon Incentives Portal
Integrate your application with an API feature
Fund your account
Launch your application!

Step 1 - Create a new Amazon account

An Amazon account is required to access the Amazon Incentives API Portal to view transactions, notify us of payments, receive account alerts, invite new users, edit existing roles for users, and manage your API security credentials.

Create a new account for your company using your company email address. Please go to the below link to create a new account for your chosen marketplace.

US | CA | MX | FR | IT | ES | DE | UK | UAE | TR | JP | AU | SA | SE | SG | NL | PL | EG | BE | ZA

Note: You will also need to set an account to be used as an IT Manager user at your organization. This can be the same account, or it can be a separate account if you prefer to onboard with two users (one with regular credentials, and one with elevated permissions to access security-related features in the Portal).

Important: This should not be tied to your personal Amazon account. We are not able to create incentives account for personal domains such as gmail or live.

Step 2 - Setting up the Amazon Incentives API Portal

Auto Onboarding (NEW)

For the most efficient onboarding experience, please utilize our self-service onboarding options instead of the manual onboarding process. However, if you work with account managers to set up your account, please skip auto onboarding section and go to manual onboarding section below.

Please go to the below link to access the auto-onboarding forms for your chosen marketplace.

US | CA | FR | IT | ES | DE | UK | JP

After you fill out the form, your incentives portal and sandbox account will be automatically created. (This is currently available for United States, Canada, France, Italy, Spain, Germany, United Kingdom and Japan partners only)

Important: If you are an existing partner with a Partner ID and a sandbox already provisioned, please DO NOT follow Auto Onboarding flow. In such cases, please move forward with manual onboarding by contacting our team

Manual Onboarding

To setup your Amazon Incentives API Portal manually, you need to email the following information to incentives-api@giftcards.amazon.com. Our API Solutions team will setup your account and you’ll receive an email confirmation from the team within 1-2 business days.

Click here for an email template to send to the API team.

[Required] Your Amazon account email address created in step 1:
Your Amazon account email address for an IT Manager user account at your organization. To be used for security purposes. This should be an IT administrator or someone else who will be handling API credentials and other sensitive settings. It can be the same as the address used in 1:
[Required] An email alias that we can use for security and system notifications. We will use this address to contact your technical team. Ideally address should be an alias, distribution list, or any other email not tied to any individual user account:
[Required] Your Partner ID:

Important: Don’t have a Partner ID yet? Go to our Contact Us page to reach out to one of our account management team who can provide you with a Partner ID

Step 3: Integrate your application with an API feature

Our API offers a number of unique use-cases. Some of which are highlighted below. If you are unsure on how the API can help your business, please reach out to the incentives-api@giftcards.amazon.com.

Create a digital gift card

Become familiar with the product by reading the Digital Gift Cards developer guide, the Pin On Receipt (B&M) developer guide or the Product Voucher developer guide
Develop your application using the sandbox environment
Create a set of API access keys for Sandbox (see API Access Keys)
Test your application in Sandbox using the test plan

Point of Sale Activation (POSA)

Become familiar with the product by reading the POSA developer guide or the Physical Gift Cards developer guide
Ask your Amazon Account Manager for inactive test card numbers for the test cases. Please ensure you have a PGP encryption tool on your computer to decrypt the test card data file. Share your public key (asc file) along with your request
Follow the steps in the developer guide to configure all of the required components.
Create a set of API access keys for Sandbox (see API Access Keys)
Test your application in Sandbox using the test plan

Load Amazon Balance (Login with Amazon / Amazon Cash)

Become familiar with the product by reading the Login & Receive developer guide or the Amazon Cash developer guide
Follow the steps in the developer guide to configure all of the required components
Create a set of API access keys for Sandbox (see API Access Keys)
Test your application in Sandbox using the test plan

Reseller

If you are a reseller, you need to use an approved Program ID. For details regarding the Program ID, please refer to Reseller Program ID

Important: Please also refer to the following guidelines to know more about your requirements for being an authorized reseller with Amazon Incentives.

Step 4: Fund your account

To ensure timely activation of your API account, once your Amazon Incentives API Portal account has been created, please navigate to the ‘How to send a payment page’. A quick link for this has been provided below.

US | CA | MX | FR | IT | ES | DE | UK | UAE | TR | JP | AU | SA | SE | SG | NL | PL | EG | BE | ZA

In the ‘How to send a payment page’ you’ll find a unique Payment Matching ID which must be used when sending payments to Amazon. The details may be entered into an optional field within your bank's transfer page labeled "Description," "Memo," "Message to Recipient," or a similar descriptor. For customers in Canada and Japan, you will not have a Payment Matching ID as your personalized payment information will be unique to your account to accurately allocate payments. You can find the information in the "How to send a payment" page.

If your Payment Matching ID is blank or is not showing, please reach out to your account manager who will be able to help you resolve this.

Proforma Invoice

Need a Proforma invoice to make a payment? You can generate a Proforma invoice directly from the Amazon Incentives API Portal under the support heading. A quick link has been provided for you below.

US | CA | MX | FR | IT | ES | DE | UK | UAE | TR | JP | AU | SA | SE | SG | NL | PL | EG | BE | ZA

Note: Once funding is received you will receive an email notification of your account activation. ACH payments are usually processed within 3 business days, wire transfers are processed within 2 business days.

Step 5: Launch your application!

Create a set of API access keys for Production (see API Access Keys).
Modify your application to use the Incentives API production endpoint as detailed in the product developer guide
Validate your application in the production environment using the test plans found in Step 3 and viewing the transactions within the Incentives API Portal transaction viewer. Quick links are provided below.

US | CA | MX | FR | IT | ES | DE | UK | UAE | TR | JP | AU | SA | SE | SG | NL | PL | BE | ZA

↑ Back to top

API Access Keys

Access keys are credentials for your AGCOD API account. You use them to sign your requests to the API, and they consist of two parts: an access key ID (for example, AKIAIOSFODNN7EXAMPLE) and a secret access key (for example, wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY). Like a user name and password, you must use both the access key ID and secret access key together to authenticate all your requests.

Important: Manage your access keys as securely as you do your user name and password for other services.

Managing access keys

You can use the Security Credentials page within the Amazon Incentives API Portal to manage your account's access keys. Quick links for this page is below.

US | CA | MX | FR | IT | ES | DE | UK | UAE | TR | JP | AU| SA | SE | SG | NL | PL | EG | BE | ZA

To create, modify, or delete your access keys

Navigate to the security credentials page of the Amazon Incentives API Portal. Quick Links are above. If you can’t see this page, that means you don’t have the correct permissions to do so. Please reach out to the API Solutions team at incentives-api@giftcards.amazon.com.
Select the environment (Production or Sandbox).
In the access keys section, do any of the following
- To create an access key, choose Create new access key and store the Access key ID and Secret access key in a secure location. You will not have access to the secret key again after this dialog box closes. When you create an access key, the key pair is active by default, and you can use the pair right away.
- To disable an active access key, choose Deactivate.
- To re-enable an inactive access key, choose Activate.
- To delete an access key, choose Delete. Select Delete key in the dialog box to confirm. When you delete an access key, it's gone forever and cannot be retrieved. However, you can always create new keys. Only inactive keys can be deleted.

Note: You should only have one active access key at a time, except for when you are rotating your keys.

Rotating access keys

As a security best practice, we recommend that you regularly rotate (change) your access keys. You can do so within the Security Credentials page in the Amazon Incentives API Portal.

If you can’t see this page, that means you don’t have the correct permissions to do so. Please reach out to the Incentives API Solutions team at incentives-api@giftcards.amazon.com.

Changing access keys on a regular schedule is a well-known security best practice because it shortens the period an access key is active and thereby reduces the business impact if they are compromised. Having an established process that is ran regularly also ensures the operational steps around key rotation are verified, so changing a key is never a scary step for your organization.

We recommend changing your access keys at a minimum of once every 90 days (or 3 months). You will receive an email as a reminder to initiate the key rotation process. If you have questions please contact your account manager or incentives-api@giftcards.amazon.com.

To rotate access keys, you should follow these steps:

Create a second access key in addition to the one in use.
Update all your applications to use the new access key and validate that you are able to make successful AGCOD requests.
Change the state of the previous access key to inactive.
Validate that your applications are still working as expected. Be sure to take care during this step because once an access key is deleted, it cannot be recovered.
Delete the inactive access key.

Both access keys will be supported while in the process of rotating.

↑ Back to top

Post Launch Tools

The Amazon Incentives API Portal has many tools that we have built overtime to make it easier for you to manage the integration with Amazon. Below are some of the key tools our partners use on a day-day basis to help them manage their integration. Don't see what you need? Send us an email at incentives-api@giftcards.amazon.com with your feature request.

Outage and Issue Management

We have a dedicated support page built to help you when things go wrong, or maybe you are working on an improvement to your systems and want to notify us about downtime. All this information and more can be found in our outage management page.

Payment Tracker

The Payment Tracker lets you review your daily/monthly/yearly issuance. Helping you identify your spend over a set amount of time. You can modify the timeframe to adjust your business needs and download the results. You can view this in the 'Detailed activity' page on the incentives portal. Quick links are below.

US | CA | MX | FR | IT | ES | DE | UK | UAE | TR | JP | AU| SA | SE | SG | NL | PL | EG | BE | ZA

Automatic Transaction Reports

You can receive your transaction reports automatically on a daily/weekly/monthly schedule. You can configure this in the 'Automatic report settings' page on the portal. Quick links below.

US | CA | MX | FR | IT | ES | DE | UK | UAE | TR | JP | AU| SA | SE | SG | NL | PL | EG | BE | ZA

Low Balance Alerts (LBAs)

Worries about running out of funds during a busy period or over the weekend? Low Balance Alerts lets you keep a close eye on your funds without coming to the portal every day. You can configure the alert to be sent if funds drop below a certain value or if we expect your funds to run out within a set number of days. You can configure this in the 'Manage fund alert' section of the portal. Quick links are below.

US | CA | MX | FR | IT | ES | DE | UK | UAE | TR | JP | AU| SA | SE | SG | NL | PL | EG | BE | ZA

Check Gift Card Tool

Ever needed to check the status of a gift card to see if it's been in a redeemable state. You can do this in the 'Check gift card status' page in the portal. Limited to 35 checks per week. If the claim code is able to be redeemed you will receive a successful message. All other status such as deactivated/canceled/claimed will show as an error. Quick links are below

US | CA | MX | FR | IT | ES | DE | UK | UAE | TR | JP | AU| SA | SE | SG | NL | PL | EG | BE | ZA

Reseller Tracking

For our partners who resell gift cards that they have purchased via the AGCOD gift card API, you'll need to ensure the clients you are selling to have been onboarded via our reseller tracking tool which is linked below. If you think you need to be part of our reseller programme, please reach out to your account manager for more information.

US | CA | MX | FR | IT | ES | DE | UK | UAE | TR | JP | AU| SA | SE | SG | NL | PL | EG | BE | ZA

FAQ

Our main FAQ can be found here however some relevant questions have been extracted below.

Q: How is Incentives API different from purchasing Gift Cards in bulk, as known as Bulk Incentives?: Instead of purchasing gift cards in bulk, Amazon Incentives API can support the creation and distribution of both physical and digital gift cards on demand in real-time.
Q: What are the guidelines for code storage? What information are we allowed to store?: Partners are not permitted to store claim codes. Refer to the AGCOD Data Storage Guidelines.
Q: How does the invoicing work for the AGCOD process? Can we adapt this according to the customer's needs?: API clients can download an activity report from the Incentives API portal and create a report to meet their needs.
Q: How does security work with the API?: The Incentives 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. Only partners that have a contractual agreement are permitted to use the API.
Q: How should access keys and secret keys be secured?: All access keys and secret keys (called credentials) must be secured from unauthorized access and accidental release. This is true for both production and sandbox credentials. Do not share your keys. Security of your system and your funds relies on secure handling of these secrets.

Contact Us

If you have questions please contact your account manager or incentives-api@giftcards.amazon.com.

↑ Back to top

Next

Get started with our API Service Guide and our Security Process

Last updated: Sep 06, 2021