How to Authorize the Amazon SP-API and Make Your First API Call with Python

The Amazon Selling Partner API (SP-API) is a powerful tool that allows developers and sellers to programmatically access various functionalities of Amazon Seller Central. This includes listing products, managing inventory, processing orders, retrieving reports, and even analyzing competitor data on Amazon.

In this post, I'll walk you through, step-by-step, how to authorize the Amazon SP-API and get started using the Python library httpx to make your first API call.

Create an app in Seller Central, get your credentials and authorize the app

To use the Amazon SP-API, you first need to register an application in your Amazon Seller Central account to get your credentials. Note that you must have a professional Seller Central account to access the SP-API. Here are the steps:

1. Log in to your Amazon Seller Central account.
2. Navigate to the Apps and Services section and select Develop Apps.
3. You are now in Developer Central, where you can create and manage your applications.
4. Click on Add a new app client.
5. Fill in the required information, including the app name and the required Roles (permissions) for your app.
6. If you are requesting SP-API access for the first time, you will be asked to provide additional information about your business and how you plan to use the API. Amazon will review this information before you can proceed. Unless you are requesting access to restricted personally identifiable information (PII), this is usually a quick process of approximately 1-2 business days.
7. After you are granted access or if you already have it, you can continue with the next steps.
8. To get your credentials, go to Developer Central, find your application, and in the LWA credentials column, click View. Here you will find your Client ID and your Client Secret.
9. Next, you need to authorize your app. In Developer Central, click the small arrow next to your app's Edit App button and then click Authorize.
10. You will be redirected to a page where you just have to click Authorize app to complete the authorization process. You will then receive your Refresh Token. You'll need this token to request access tokens for making API calls.
11. Finally, store your Client ID, Client Secret, and Refresh Token securely, as you will need them to authenticate your app.

Please refer to the GIF above for a visual guide through the process.

Make your first API call with Python

To make our first API call to the Amazon SP-API, we'll use the Python library httpx. You can install it via pip if you haven't already:

pip install httpx

While there's a helpful third party Python library called python-amazon-sp-api to handle authentication and requests, I prefer using httpx directly in this guide. This approach provides a clearer understanding of how the API works under the hood. It also makes it easier to learn how to work with the official Amazon SP API documentation. It is good practice to familiarize yourself with the official Amazon SP API documentation, as the documentation for the third-party library is limited and may sometimes be out of date.

Note: The httpx library is a more modern alternative to the popular requests library and offers async capabilities, which can be beneficial for more complex applications. All examples in this post will also work with the requests library, just make sure that you have the library installed and replace httpx with requests in the code snippets.

Set up your credentials and configuration

To access the API and make requests, you need to set up your credentials and configuration. This includes your CLIENT_ID, CLIENT_SECRET, and REFRESH_TOKEN. You also need to define the MARKETPLACE_ID for the specific Amazon marketplace and the API_URL for the region you are working in.

You can find the correct MARKETPLACE_ID and regional API_URL (Endpoint) in the official Amazon SP-API documentation. The AUTHENTICATION_URL is always the same, regardless of region.

import httpx

CLIENT_ID = "amzn1.application-oa2-client...your_client_id..."
CLIENT_SECRET = "amzn1.oa2-cs.v1...your_client_secret..."
REFRESH_TOKEN = "Atzr|...your_refresh_token..."

MARKETPLACE_ID = "A1PA6795UKMFR9"  # Marketplace ID for Germany
API_URL = "https://sellingpartnerapi-eu.amazon.com"  # API URL for Europe

AUTHENTICATION_URL = "https://api.amazon.com/auth/o2/token"

Get your access token

To make API calls, you first need to obtain an access token using your CLIENT_ID, CLIENT_SECRET, and REFRESH_TOKEN. To get your access token, you need to make a POST request to the AUTHENTICATION_URL with your credentials. The response will contain your access token. The first step is to set up the request headers and body:

headers = {"Content-Type": "application/x-www-form-urlencoded;charset=UTF-8"}

data = {
    "grant_type": "refresh_token",
    "client_id": CLIENT_ID,
    "client_secret": CLIENT_SECRET,
    "refresh_token": REFRESH_TOKEN,
}

Now, make the POST request:

response = httpx.post(AUTHENTICATION_URL, headers=headers, data=data)

A successful request will return a 200 status code and a response body containing your access token, which should look something like this:

print(response.json())

{
  "access_token": "Atza|...your_access_token...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "refresh_token": "Atzr|...your_refresh_token..."
}

The access_token is what you need for subsequent API calls. An access_token typically expires after one hour (3600 seconds) and you will need to request a new one using the same process.

Note: This post doesn't cover handling access token expiration. In a production application, you should implement a logic to automatically refresh the token before it expires.

Now, extract the access token from the response, to use it in your API calls:

access_token = response.json()["access_token"]

Make your first API call

For this example, we'll make a GET request to the getOrders endpoint to retrieve a list of orders.

First, define the request headers for the API call. The headers must include the Content-Type and the x-amz-access-token, which holds your access token.

api_headers = {
    "Content-Type": "application/json",
    "x-amz-access-token": access_token,
}

Next, define the parameters for the API call. In the case of the getOrders endpoint, you must specify the MarketplaceIds and a time filter, like CreatedAfter. You can find the full list of parameters in the official documentation for the getOrders operation.

params = {
    "MarketplaceIds": MARKETPLACE_ID,
    "CreatedAfter": "2023-01-01T00:00:00Z",  # A time-based filter is required
    # Add other optional parameters as needed
}

Finally, make the GET request to the getOrders endpoint:

response = httpx.get(f"{API_URL}/orders/v0/orders", headers=api_headers, params=params)

A successful request will return a 200 status code and a response body containing a list of orders, which should look something like this:

print(response.json())

{
  "payload": {
    "Orders": [
      {
        "AmazonOrderId": "123-1234567-1234567",
        "OrderStatus": "Shipped",
        "..."
      },
      {
        "AmazonOrderId": "123-1234567-7654321",
        "OrderStatus": "Pending",
        "..."
      }
    ]
  },
  "NextToken": "...token_for_next_page..."
}

Conclusion

In this post, I've shown you how to authorize the Amazon SP-API and make your first API call using Python and the httpx library. The post was designed to give you a clear understanding of the authorization process and how to interact with the API directly. Depending on your use case, you can either continue using httpx, which will give you more control and flexibility, or explore third-party libraries like python-amazon-sp-api for a more streamlined experience.