Frequently asked questions
Amazon Business roles
What is a role?
A role is the mechanism used by Amazon Business APIs to determine whether a developer or app has access to an operation or resource. As a developer, you must request and qualify for a role. Without a role, you are restricted to access the operations and resources grouped under that role. Roles protect access to personally identifiable information (PII) and other sensitive data. Roles ensure developers have access only to required data.
How do I determine what roles to request?
Review the role descriptions listed here to understand the purpose of each role. Refer to examples of the resources and operations governed by each role. Restricted means the role requires sensitive information which may include personally identifiable information (PII). You are required to provide additional information about your use of the data and your security controls. Approval of your developer profile depends on your role.
| Role | Description | Available Regions |
|---|---|---|
| Business Product Catalog (Non-Restricted) | Used to search Amazon Business Catalog to find relevant products and their associated offers. - products: Returns list of matching ASINS and the buybox offers for the keyword passed in API request - products/{productId}: Returns buybox winning offer for an ASIN - offers: Returns list of offers for a specific ASIN - getProductsByAsins: Returns buybox winning offer for a list of ASINs | NA, EU, JP |
| Amazon Business Analytics (Restricted) | Used to access Amazon Business Analytics Reports programmatically which are used to derive spend insights at different levels (user/organization/group), tracking orders. -getOrders -getOrderbyID | NA, EU, JP |
| Business Purchase Reconciliation (Restricted) | Used to retrieve payment transactions for a given date range and keep accounting books up-to-date or create automated entries for employee reimbursement. transaction: Returns a paginated list of business transactions with feed dates that fall within your specified date range. | NA, EU, JP |
| User Management (Non-Restricted) | Used to create user accounts for new to Amazon users in existing business accounts. | NA, EU, JP |
How do I select a role for my app?
You select a role for your app by populating your Developer profile during the app registration. There's a section where you'll choose role(s) from the list provided.
How do I add or remove the role(s) for my app after submission?
1. Sign in to Developer Central.
- In Action column, select Edit App. The role(s) you previously requested and approved displays.
- To add, choose role(s) from the list. To remove, deselect the checkbox.
How do I add a new role after my app has been submitted or published?
To add a new role after your app has been published, do these steps:
1. Go to your developer profile and submit a role to be added.
2. Once your developer profile has been approved, go to your app configuration. Apply the newly approved role. Save the changes and relist the app.
3. After the app is approved, get new authorizations to generate a new refresh token. The refresh token will grant access to the API operations, reports, feeds, and notifications the new role will provide.
What happens when I call an operation for which I don't have the required role(s)?
The response to the request will have an HTTP status code of 403 and error information in the response body.
Developer account information
Do I need to create individual developer account for each Amazon Business store?
No. You don't need to create a developer account for each Amazon Business store. You can use the same developer account for another Amazon Business store. But you'll have to follow the authorization process for each Amazon Business store. The authorization process generates access and refresh tokens that are unique for each Amazon Business store.
Do I need to create an app for each Amazon Business store?
You can create a single app for all Amazon Business stores or an individual app for each Amazon Business store. A single app option is recommended. Create multiple apps if you want to support different environment like test, User Acceptance Testing (UAT), or production. The maximum number of apps you can create is up to 10.
How can I view my developer account information?
After registration of your Amazon Business partner app, do these steps:
1. Sign in to Developer Central. The Developer Central page appears, displaying the IAM ARN associated with your application(s).
2. Select **View** under **LWA** credentials for the application you want. Your LWA client identifier and client secret for that application appears. Use these credentials when requesting for LWA access token.
Error Messages
My customer has an issue with their email. Here's the error message.
{
"errors": [
{
"code": "Unauthorized",
"message": "Email is not authorized",
"details": "End user email is not Authorized"
}
]
}
This happens when the user is passing an email that isn't associated with the Amazon Business account or the user email falls under Matching and Clearing Engine (MACE).
The email address is a mandatory parameter in the header of the request. To resolve this issue, the user must pass an email in the x-amz-user-email field that is associated with the Amazon Business account. Also, the email shouldn't fall under MACE.
My customer has an issue with their access token. Here's the error message.
{
"errors": [
{
"message": "Access to requested resource is denied.",
"code": "Unauthorized",
"details": "The access token you provided has expired."
}
]
}
This happens when the user is passing a token in the x-amz-access-token field that's been expired. Access tokens expire after an hour.
To resolve this issue, you need to generate a refresh token. Refer to Step 4: Onboarding Step 4: Authorize your Amazon Business API apps.
My customer has an issue with their grant code. Here's the error message.
{
"error_description": "The request has an invalid grant parameter : code",
"error": "invalid_grant"
}
This happens because the grant code has expired. Grant code expires in five minutes after generation.
To resolve the issue, generate a refresh token to get the grant code. Refer to Step 4: Onboarding Step 4: Authorize your Amazon Business API apps.
My customer has the right access token, but is having problem with security token. What could be the reason?
{
"errors": [
{
"message": "The security token included in the request is invalid.",
"code": "InvalidInput"
}
]
}
This happens if the user isn't passing the right IAM AccessKey and SecretKey in authorization.
Refer to Onboarding Step 2: Create and configure IAM policies and entities for details.
OAuth
If I have accounts in multiple Amazon Business stores, do I use the same OAuth for each store?
No. If you have accounts in multiple Amazon Business stores, you’ll need to get tokens for each Amazon Business store. The tokens are unique for each Amazon Business store. Use the domain of the country where your Amazon Business store is located.
If you have five Amazon Business account in different countries, here's your sample schema.
What are the steps to generate access and refresh tokens?
Onboarding Step 4: Authorizing Amazon Business API apps provides steps to generate access and refresh tokens.
Does the refresh token expire?
No. Refresh token doesn’t expire, but it won't work if the authorization is revoked.
What happens if I’m not an admin of all legal entities in Amazon Business while performing authorization activity?
You’ll receive an error and will be unable to proceed. More info here.
Can I provide consent if I don't have an admin account or not added as an admin at a legal entity level?
No. You must sign in using an admin account to provide consent. An error will occur if you aren't using an admin account while providing consent. To resolve the error, follow the steps here.
I'm getting an error that says "We're sorry. We can't connect this account." What's the cause of this error?
This error is caused by invalid redirect_uri and applicationId. You must use the same redirect_uri and applicationId you've provided in the Developer Central. Any missing or additional characters will cause an error. To resolve the error, follow the steps here.
What could cause an error while trying to generate an OAuth code?
An error occurs because of an invalid redirect_uri and applicationId. Use the same redirect_uri and applicationId you've provided in Developer Central. You'll encounter an error and will be unable to proceed if there's a mismatch. More info here.
Others
API関連日本語マニュアルはこちら (Guides in Japanese language)
Are there guidelines for designing an apps using the Amazon Business APIs?
Yes. We provide guidance on what is required when displaying Amazon Business products within your platform. Compliance with these standards are enforced. Refer to Product Search API customer experience guidelines here.
What is the difference between public app and private app?
* Public app. An app that is publicly available and is authorized by a business customer.
* Private app. An app that is available only to your organization and is self-authorized.
My customer's app requires a higher transaction per second (TPS). Can we increase the TPS?
By default, each app has 0.5 TPS. You can request to increase the TPS.
Is Sandbox environment available for Amazon Business APIs?
We are in active development of setting up a sandbox environment. We plan to offer it in the future.
Product Search API
My customer isn't seeing merchant ratings in getProducts call. What could be the reason?
By default, the merchant ratings and feedback values are inactive. We activate these fields by request.
My customer is getting an "InvalidInput" error when calling the getProductsByAsins method. What causes this error?
{
"errors": [
{
"code": "InvalidInput"
}
]
}
getProductsByAsins is a POST method as opposed to other methods. Please ensure that they have the right method selected when making the API call. Also, ensure that the content being posted has the content-type JSON.