Before your application can connect to the Selling Partner API, you must register it and it must be authorized by a selling partner. See Registering your application and Authorizing Selling Partner API applications.
These instructions show you the steps for making a call to the Selling Partner API. For help with constructing a Selling Partner API URI and adding headers to it, see Generating a Java client library. For a more complete solution that includes code for exchanging LWA tokens and authentication, see Generating a Java SDK with LWA token exchange and authentication.
# Step 1. Request a Login with Amazon access token
A Login with Amazon (LWA) access token authorizes your application to take certain actions on behalf of a selling partner. An LWA access token expires one hour after it is issued.
Note about restricted operations. An LWA access token must be included in calls to all operations except restricted operations, which return Personally Identifiable Information (PII). When calling restricted operations, instead of including an LWA access token, you include a Restricted Access Token (RDT). For information about getting RDTs and calling restricted operations, see the Tokens API Use Case Guide.
To request an LWA access token, make a secure HTTP POST to the LWA authentication server (https://api.amazon.com/auth/o2/token) with the following parameters:
| Name | Description | Required |
|---|---|---|
| grant_type | The type of access grant requested. Values:
| Yes |
| refresh_token | The LWA refresh token. Get this value when the selling partner authorizes your application. For more information, see Authorizing Selling Partner API applications. | No. Include refresh_token for calling operations that require authorization from a selling partner. If you include refresh_token, do not include scope. |
| scope | The scope of the LWA authorization grant. Values:
| No. Include scope for calling a grantless operation. If you include scope, do not include refresh_token. |
| client_id | Get this value when you register your application. See Viewing your developer information. | Yes |
| client_secret | Get this value when you register your application. See Viewing your developer information. | Yes |
Example for calling an operation that requires selling partner authorization:
POST /auth/o2/token HTTP/l.l
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
grant_type=refresh_token
&refresh_token=Aztr|...
&client_id=foodev
&client_secret=Y76SDl2F
2
3
4
5
6
7
Example for calling a grantless operation:
POST /auth/o2/token HTTP/l.l
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
grant_type=client_credentials
&scope=sellingpartnerapi::notifications
&client_id=foodev
&client_secret=Y76SDl2F
2
3
4
5
6
7
Tip: To avoid getting an untrusted certificate authority (CA) error when calling the LWA authorization server, be sure to update your trust store so that your application trusts the LWA authorization server.
Response
A successful response includes the following values.
| Name | Description |
|---|---|
| access_token | The LWA access token. Maximum size: 2048 bytes. |
| token_type | The type of token returned. Must be bearer. |
| expires_in | The number of seconds before the LWA access token becomes invalid. |
| refresh_token | The LWA refresh token that you submitted in the request. Maximum size: 2048 bytes. |
HTTP/l.l 200 OK
Content-Type: application/json;charset UTF-8
Cache-Control: no-store
Pragma:no-cache
{
"access_token":"Atza|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSREXAMPLE",
"token_type":"bearer",
"expires_in":3600,
"refresh_token":"Atzr|IQEBLzAtAhRPpMJxdwVz2Nn6f2y-tpJX2DeXEXAMPLE"
}
2
3
4
5
6
7
8
9
10
For more information, visit the Authorization Code Grant (opens new window) page in the Login with Amazon documentation.
# Step 2. Construct a Selling Partner API URI
Here are the components of a Selling Partner API URI.
| Name | Description | Example |
|---|---|---|
| HTTP method | The HTTP method. | GET |
| Endpoint | A Selling Partner API endpoint. | https://sellingpartnerapi-na.amazon.com |
| Path | The Selling Partner API section/version. number of the section/resource. | /fba/inbound/v0/shipments/{shipmentId}/preorder/confirm |
| Query string | The query parameters. | ?marketplace=ATVPDKIKX0DER |
| Path parameter | The path parameters. | shipmentId1 |
For example:
PUT https://sellingpartnerapi-na.amazon.com/fba/inbound/v0/shipments/shipmentId1/preorder/confirm?MarketplaceId=ATVPDKIKX0DER&NeedByDate=2020-10-10
# Step 3. Add headers to the URI
Add headers to the URI that you constructed in Step 2. Construct a Selling Partner API URI. Here are the HTTP headers that you include in requests to the Selling Partner API:
Request headers
| Name | Description |
|---|---|
| host | The marketplace endpoint. See Selling Partner API endpoints. |
| x-amz-access-token | The LWA access token. See Step 1. Request a Login with Amazon access token. Note about restricted operations. If you are calling a restricted operation, pass in a Restricted Data Token (RDT) here instead of an LWA access token. For information about getting RDTs and calling restricted operations, see the Tokens API Use Case Guide in the Tokens API Use Case Guide. |
| x-amz-date | The date and time of your request. |
| user-agent | Your application name and version number, platform, and programming language. These help Amazon diagnose and fix problems you might encounter with the service. See Include a User-Agent header in all requests. |
Here is an example of a request to the Selling Partner API with URI and headers but no signing information:
PUT /fba/inbound/v0/shipments/shipmentId1/preorder/confirm?MarketplaceId=ATVPDKIKX0DER&NeedByDate=2020-10-10 HTTP/1.1
host: sellingpartnerapi-na.amazon.com
user-agent: My Selling Tool/2.0 (Language=Java/1.8.0.221;
Platform=Windows/10)
x-amz-access-token=Atza|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSREXAMPLE
x-amz-date: 20190430T123600Z
2
3
4
5
6
To sign a request to the Selling Partner API, see Step 4. Create and sign your request.
# Step 4. Create and sign your request
The Selling Partner API uses the AWS Signature Version 4 Signing Process (opens new window) for authenticating requests. When you send HTTP requests to the Selling Partner API, you sign the requests so that Amazon can identify who sent them. You sign requests using your AWS access keys, which consists of an access key ID and a secret access key. Amazon recommends using the AWS Security Token Service (AWS STS) (opens new window) to request temporary AWS access keys to sign your requests. See Creating and configuring IAM policies and entities to create an IAM user (with an AWS STS policy attached) that assumes an IAM role. You then register your application using the IAM role. For more information about using AWS STS and the AWS SDKs that can help with your implementation, see Requesting temporary security credentials (opens new window) in the AWS documentation.
Note: You need to learn how to sign HTTP requests only when you manually create them. When you use the one of the AWS SDKs to calculate signatures for you, the SDK automatically signs the requests with the AWS access key that you specify when you configure it. When you use an SDK you don't need to learn how to sign requests yourself. Java developers, for example, can use AWS4Signer.java (opens new window) from the AWS SDK for Java as a model for calculating a signature. You can find SDKs for other languages in the AWS GitHub repository (opens new window).
To create and sign your request, complete the following:
Create a canonical request
Follow the instructions in Task 1: Create a Canonical Request for Signature Version 4 (opens new window) in the AWS documentation, using this guidance:
See Step 3. Add headers to the URI for an example of an unsigned request to start with when you create your canonical request.
Use SHA-256 for the hash algorithm.
Do not put authentication information in the query parameters. Put it in the
Authorizationheader parameter. For information about using theAuthorizationheader parameter for the authentication information, see Authorization header.
Create a string to sign
Follow the instructions in Task 2: Create a String to Sign for Signature Version 4 (opens new window) in the AWS documentation, using this guidance:
The algorithm designation value is
AWS4-HMAC-SHA256To determine the credential scope, see Credential scope.
Calculate the signature
Follow the instructions in Task 3: Calculate the Signature for AWS Signature Version 4 (opens new window) in the AWS documentation.
Important: See Credential scope to help you complete this step.
Add the signing information
Follow the instructions in Task 4: Add the Signature to the HTTP Request (opens new window) in the AWS documentation, using this guidance:
Do not add signing information to the query string. Add it to the
Authorizationheader parameter.See Authorization header for details about creating an
Authorizationheader parameter.
The following example shows what a request might look like after you've added the signing information to it using the Authorization header.
PUT /fba/inbound/v0/shipments/shipmentId1/preorder/confirm?MarketplaceId=ATVPDKIKX0DER&NeedByDate=2020-10-10HTTP/1.1
Authorization: AWS4-HMAC-SHA256 Credential=AKIAIHV6HIXXXXXXX/20201022/us-east-1/execute-api/aws4_request, SignedHeaders=host;user-agent;x-amz-access-token,
Signature=5d672d79c15b13162d9279b0855cfba6789a8edb4c82c400e06b5924aEXAMPLE
host: sellingpartnerapi-na.amazon.com
user-agent: My Selling Tool/2.0 (Language=Java/1.8.0.221;
Platform=Windows/10)
x-amz-access-token=Atza|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSREXAMPLE
x-amz-date: 20190430T123600Z
2
3
4
5
6
7
8
# Credential scope
The credential scope is a component of the "string to sign" that you create when you sign a request to the Selling Partner API. See Create and sign your request.
Credential scope is represented by a slash-separated string of dimensions, as shown in the following table:
| Dimension | Description | Example |
|---|---|---|
| Date | An eight-digit string representing the year (YYYY), month (MM), and day (DD) of the request. | 20190430 |
| AWS region | The region you are sending the request to. See Selling Partner API endpoints. | us-east-1 |
| Service | The service you are requesting. You can find this value in the endpoint. See Selling Partner API endpoints. | execute-api |
| Termination string | A special termination string. For AWS Signature Version 4, the value is aws4_request | aws4_request |
For example:
20190430/us-east-1/execute-api/aws4_request
Important: The date that you use as part of your credential scope must match the date of your request, as specified in the x-amz-date header. For more information, see Handling Dates in Signature Version 4 (opens new window) in the AWS documentation.
For more information, see Step 4. Create and sign your request.
# Authorization header
The Authorization header contains the signing information for a request. Although the header is named "Authorization", the signing information is used for authentication.
Here are the components of an Authorization header:
| Component | Description |
|---|---|
| The algorithm used for signing | The hash algorithm used throughout the signing process. The Selling Partner API requires SHA-256. You specify this in Step 4. Create and sign your request. |
| Credential | Your AWS access key ID plus the Credential scope. You get your AWS access key ID in Step 2. Create an IAM user. |
| SignedHeaders | A list of all the HTTP headers that you included with the signed request. For an example, see Step 3. Add headers to the URI. |
| Signature | The signature calculated in Step 4. Create and sign your request. |
For example:
Authorization: AWS4-HMAC-SHA256 Credential=AKIAIHV6HIXXXXXXX/20201022/us-east-1/execute-api/aws4_request, SignedHeaders=host;user-agent;x-amz-access-token;x-amz-date, Signature=5d672d79c15b13162d9279b0855cfba6789a8edb4c82c400e06b5924aEXAMPLE
For more information, see Step 4. Create and sign your request.