Sign In
Sign In

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.

Getting started

Complete the steps below to get started with Amazon Incentives:

  1. Create a new Amazon Account
  2. Setting up the Amazon Incentives Portal
  3. Integrate your application with an API feature
  4. Fund your account
  5. 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

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)

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.

  1. [Required] Your Amazon account email address created in step 1:
  2. 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:
  3. [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:
  4. [Required] Your 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

  1. 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
  2. Develop your application using the sandbox environment
  3. Create a set of API access keys for Sandbox (see API Access Keys)
  4. Test your application in Sandbox using the test plan

Point of Sale Activation (POSA)

  1. Become familiar with the product by reading the POSA developer guide or the Physical Gift Cards developer guide
  2. 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
  3. Follow the steps in the developer guide to configure all of the required components.
  4. Create a set of API access keys for Sandbox (see API Access Keys)
  5. Test your application in Sandbox using the test plan

Load Amazon Balance (Login with Amazon / Amazon Cash)

  1. Become familiar with the product by reading the Login & Receive developer guide or the Amazon Cash developer guide
  2. Follow the steps in the developer guide to configure all of the required components
  3. Create a set of API access keys for Sandbox (see API Access Keys)
  4. 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

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

Step 5: Launch your application!

  1. Create a set of API access keys for Production (see API Access Keys).
  2. Modify your application to use the Incentives API production endpoint as detailed in the product developer guide
  3. 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.

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

  1. 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.
  2. Select the environment (Production or Sandbox).

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

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:

  1. Create a second access key in addition to the one in use.
  2. Update all your applications to use the new access key and validate that you are able to make successful AGCOD requests.
  3. Change the state of the previous access key to inactive.
  4. 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.
  5. 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

Last updated: Sep 06, 2021