Amazon Incentives API Integration
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 firstname.lastname@example.org. Please be sure to include your Partner ID in all correspondence.
Overview of the integration process
- Complete the getting started steps
- Integrate your application with an API feature
- Fund your account
- Launch your application
Step 1: Getting started
(a) Create a new Amazon account
An Amazon account is required to access the Incentives API Portal to view transactions, notify us of payments, receive account alerts, and manage your API security credentials.
- US clients: Register in about 30 seconds by clicking here.
- International clients: Go to amazon.com (or replace '.com' with respective country suffix for international clients). For example, if you want access to the Japan portal, go to amazon.co.jp for your new account.
- Create a new account for your company using your company email address
Important: This should not be tied to your personal Amazon account.
Note: You will also need to set an
account to be used as an admin user at your organization. This can be
the same account created in the previous step, 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).
(b) Email your account details to Amazon
Email the following information to email@example.com and receive confirmation of your sandbox environment within 24-48 hours.
- Your Amazon account email address created in part (a) of step 1.
- Amazon account email address for an admin 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).
- An email alias that we can use for security and system notifications. We will use this address to contact your technical team. This address should be an alias, distribution list, or any other email not tied to any individual user account.
- Your Partner ID
Important: If you do not have a Partner ID, you will need to fill out the contact form by clicking the "Create Incentives API account" button above.
Step 2: Integrate your application
Integrate your application with one of the features below:
(a) Create a digital gift card
(b) Login and Receive
(c) Point of Sale Activation (Web Activation)
- Become familiar with the product by reading the 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
Step 3: Fund your account
To ensure timely activation of your API account,
please include "New API" followed by your partner ID within the wire
transfer details for your first wire payment.
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.
This is only necessary for your first payment and future wire payments should include the Payment Matching ID for faster payment processing. Your Payment Matching ID can be found on the"How to send a payment" page in the API Portal. Note that IDs are specific to an account balance.
Incentives API Portal by region: US | CA | MX | FR | IT | ES | DE | UK | UAE | TR | JP | AU | SA | SE | SG | NL | PL
Step 4: Launch your application!
- Create a set of API access keys for Sandbox (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 2 and viewing the transactions within the Incentives API Portal US | CA | MX | FR | IT | ES | DE | UK | UAE | TR | JP | AU | SA | SE | SG | NL | PL To learn more, watch this
API Access KeysAccess 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. Manage your access keys as securely as you do your user name and password for other services.
Managing access keysYou can use the AGCOD credentials page within the API portal to manage your account's access keys.
To create, modify, or delete your access keys
- Sign into the API portal and open the AGCOD credentials page at US | CA | MX | FR | IT | ES | DE | UK | UAE | TR | JP | AU. | SA | SE | SG | NL | PL
- 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 keysAs a security best practice, we recommend that you regularly rotate (change) your access keys. You can do so within the AGCOD Credentials page in the API portal. If you are unable to see the page, please reach out to an administrator at your company because only admin users have access to these features.
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 180 days (or 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 firstname.lastname@example.org.
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.
Q: How is Incentives API different from purchasing Gift Cards in bulk, as known as Bulk Incentives?
A: 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?
A: 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?
A: 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?
A: 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?
A: 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.
If you have questions please contact your account manager or email@example.com