📘

Buy with Prime API is now available for early access

Sign up for early access to the Buy with Prime API using the 'Sign Up' button below. The API may change as Amazon receives feedback and iterates on it.

Sign Up

When you make a request to the Buy with Prime API, you must provide an OAuth 2.0 access token in the header of the request. An access token is a set of short-lived credentials that signifies that Buy with Prime has given you permission to call the Buy with Prime APIs on a set of resources such as information such as orders and delivery previews.

To get an access token, you first generate your API credentials on the Buy with Prime merchant console. You then exchange your API credentials for an access token by making a POST request to a Buy with Prime token endpoint.

Buy with Prime access tokens expire every 15 minutes. After your access token expires, you can request a new access token by using the same client permissions.

Note Some mutations and queries use a shopper's Amazon identity token. With an identity token, you can get data related to the shopper, for example the shopper's location to help provide a more accurate delivery preview. For details, see Manage Shopper Identity.

Step 1: Generate API credentials

You generate your API credentials by using the Buy with Prime merchant console.

To generate API credentials by using the merchant console

1. Sign in to the Buy with Prime merchant console as an owner/admin.

2. On the left, click Settings.

3. Under Settings, click API credentials.

4. Click Generate credentials.

5. For Credentials name, enter a name that helps you identify the purpose of the credentials.

6. Choose the permissions that you want the API credentials to have. You can choose Full Access or Custom. We recommend that you adhere to the principle of least privilege and choose granular access depending on the functionality that you are building using the API credentials.

   • Full access: Allows edit and view access to all the listed permissions. Choosing this option automatically chooses all APIs in the list and automatically includes access to any future Buy with Prime APIs.
   • Custom: Allows you to select permissions from a list. If you choose this option, you must manually choose the specific APIs that you need.

7. Click Generate.
   Buy with Prime generates your API credentials and then takes you to a page where you can download a file that contains the credentials. The file contains a client ID, client secret, target ID, and a list of permissions that the credentials have access to.

8. Download the credentials file to your computer.

   🚧

   You must download the credentials file and save it securely. If you navigate away without downloading the credentials, you will not be able to download the credentials later.

9. Locate and open the downloaded credentials file on your computer.
   The file has the name that you chose for the credentials. The file looks like the following image, which contains fictitious data.

   

Step 2: Use API credentials to get an access token

After you get your API credentials, you use the API credentials to request a Buy with Prime access token.
To get an access token for the Buy with Prime API

1. Make an HTTPS POST request to https://api.buywithprime.amazon.com/token with the following fields in the body of the request.

   Request Fields

   Field	Description	Required?
   client_id	The client ID of the API credentials that you downloaded in Generate API credentials.	Yes
   client_secret	The client secret of the API credentials that you downloaded in Generate API credentials.	Yes
   grant_type	OAuth 2.0 grant type. Use client_credentials.	Yes

   Example Request

   In the following example request, replace the following placeholders:

   • EXAMPLE_CLIENT_ID with the client_id from the API credentials that you downloaded.
   • EXAMPLE_CLIENT_SECRET with the client_secret from the API credentials that you downloaded.
   
   
   HTTPcURLPythonJavaScript

   POST /token HTTP/1.1
   Host: api.buywithprime.amazon.com
   Content-Type: application/x-www-form-urlencoded
   x-api-version: $api_version
    
   client_id=EXAMPLE_CLIENT_ID&client_secret=EXAMPLE_CLIENT_SECRET&grant_type=client_credentials
   

   curl --location --request POST 'https://api.buywithprime.amazon.com/token' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --header 'x-api-version: $api_version' \
   --data-urlencode 'client_id=EXAMPLE_CLIENT_ID' \
   --data-urlencode 'client_secret=EXAMPLE_CLIENT_SECRET' \
   --data-urlencode 'grant_type=client_credentials'
   

   import requests
   url = "https://api.buywithprime.amazon.com/token"
   payload='client_id=EXAMPLE_CLIENT_ID&client_secret=EXAMPLE_CLIENT_SECRET&grant_type=client_credentials'
   headers = {
     'Content-Type': 'application/x-www-form-urlencoded', 
     'x-api-version': '$api_version'  
   }
   response = requests.request("POST", url, headers=headers, data=payload)
   print(response.text)
   

   const url = "https://api.buywithprime.amazon.com/token";
   const headers = {
     "Content-Type": "application/x-www-form-urlencoded",
     "x-api-version": "$api_version"  
   };
   const payload="client_id=EXAMPLE_CLIENT_ID&client_secret=EXAMPLE_CLIENT_SECRET&grant_type=client_credentials";
   
   fetch(url, {
     method: "POST",
     headers: headers,
     body: payload
   }).then(response => {
       return response.json();
   }).then(json => {
     console.log(json);    
   });
   

2. Get the access token from the response, which contains the following fields.

   Example Successful Response

   JSON

   {
       "access_token": "EXAMPLE_BUY_WITH_PRIME_ACCESS_TOKEN",
       "expires_in": 885
   }
   

   Successful Response Fields

   Field	Description
   access_token	Token that you use to access the Buy with Prime API.
   expires_in	Time until the token expires, in seconds.

   Example Failed Response (HTTP 400)

   JSON

   {
       "message": "Content type is null or invalid. Ensure content type is: application/x-www-form-urlencoded",
       "code": "InvalidContentType",
       "type": "ValidationError"
   }
   

   Failed Response Fields

   Field	Description
   message	Description of the cause of the error.
   code	(Only present for HTTP 400 InvalidParameterException responses.) Code that further describes the cause of the HTTP 400 error. For a list of possible codes, see the table in the following section.
   type	The exception type thrown by the service. Examples: ValidationError or AccessDeniedError.

   Error Codes

   HTTP Status Code	Error Type	Error Code	Description
   400	ValidationError	InvalidContentType	The Content-Type field in the request is missing or invalid. The Content-Type field must be application/x-www-form-urlencoded.
   400	ValidationError	NonDeserializableContent	The request payload isn't in a format that the server can interpret.
   400	ValidationError	InvalidClientId	The request payload doesn't contain a client_id field, or the specified client_id is incomplete, malformed, or invalid.
   400	ValidationError	InvalidClientSecret	The request payload doesn't contain a client_secret field, or the specified client_secret is incomplete, malformed, or invalid.
   400	ValidationError	InvalidGrantType	The request payload doesn't contain a grant_type field, or the specified grant_type is incomplete, malformed, or invalid. The grant_type must be client_credentials.
   401	AccessDeniedError	N/A	The requested payload doesn't have permission to receive an access token.
   429	ThrottlingError	N/A	The request was throttled by the service. Requests are throttled after a limit of 12 requests per second per client_id is reached.
   500	InternalServerError	N/A	An internal error occurred. Try again.

Now that you have a Buy with Prime access token, you can call the Buy with Prime API. For details, see How to Call the Buy with Prime API.

Related topics

• Call the Buy with Prime API
• About the Buy with Prime API
• Integrate with Buy with Prime