Tutorial: Test Selling Partner API endpoints

Selling Partner API (SP-API) provides sandbox environments where you can test the SP-API endpoints without affecting production data. You can direct calls to the SP-API sandbox endpoints to make static requests that return mock responses. By using the sandbox, you can practice the steps required to make a call, gain an understanding of the request and response formats, practice validating application credentials, and play with API endpoints without impacting production data.

Tutorial

The following tutorial demonstrates how to generate the required access tokens and make calls to the SP-API sandbox endpoints.

Prerequisites

To complete this tutorial, you need the following prerequisites:

• A Postman account and workspace. For more information on how to use Postman, refer to Using Postman for Selling Partner API models.
• If you have your own selling partner account, you can self authorize your application to access your account information.
• If you don’t have your own selling partner account, then you must set up a third-party OAuth workflow. With this workflow, third-party sellers and vendors can authorize your application to access their Amazon Selling Partner data.

During this process, you receive a refresh token which you can later exchange for an access token. An access token is required to call SP-API endpoints.

Variables needed to perform testing with Postman

To make calls with Postman, you must first set up the credentials. You will need the following global variables for your workspace:

• client_id: You must have the client_id to request an LWA access token. The client_id appears after you register your app. To get this value, refer to Viewing your developer information.
• client_secret: You must have the client_secret to request an LWA access token. The client_secret appears after you register your app. To get this value, refer to Viewing your developer information.
• refresh_token: The LWA refresh token, get this value when the selling partner authorizes your application. If you have your own Selling Partner account, you can self authorize your application to get the refresh token. For more information, refer to Authorizing Selling Partner API applications.
• base_url_sandbox: To get Selling Partner API sandbox endpoints for each regions, refer to SP-API sandbox endpoints.

Step-by-step workflow

You can use the following steps to test a Selling Partner API endpoint:

Step 1. Generate a Login with Amazon (LWA) access token

First you need to authorize your application to access selling data on behalf of a selling partner. When you generate a Login with Amazon (LWA) access token, it can be used for multiple SP-API calls until it expires.

For detailed steps, refer to Generate an LWA Access Token using Postman or Step 1. Request a Login with Amazon access token.

The response returns an LWA access token that you can use to authenticate your SP-API call. An LWA access token must be included in calls to all operations (except restricted operations) that return Personally Identifiable Information (PII). When calling restricted operations, you include a Restricted Access Token (RDT) instead of an LWA access token

The following image shows an example where the access token starts Atza|**************************** and expires in (the number of seconds before the LWA access token becomes invalid) 3600 seconds (1 hour).

Step 2. Make a call to the SP-API sandbox endpoint

The following steps cover how to practice making a call to the SP-API sandbox endpoint using the Orders API Swagger model. You can use this process to test API calls and examine mock requests and responses.

1. Import the Orders API Swagger model to your Postman workspace.
2. Search the code for an x-amzn-api-sandbox object that contains a static array of request and response examples for static sandbox calls to the API operation in which they appear.
3. Set the request parameters with the same values that the Orders API Swagger model defines.
4. Check that your request includes all required parameters as defined in the corresponding Swagger model. The following example shows an Order API v0 Swagger model, where Get Order API call is highlighted with a successful response:

5. Make a GET Call to /orders/v0/orders.
6. Set the baseUrl as Selling Partner API sandbox.
7. Under the Params tab, pass the static request values from the Orders API model.

8. Under the Headers tab, pass the access_token received in Step 1 for each API call, using the key value pair x-amz-access-token: Atc|********************. Skip this step for restricted operations and grantless operations.

9. For restricted operations, pass the Restricted Data Token (RDT) received from the createRestrictedDataToken operations using the key value pair x-amz-access-token: Atz.sprdt|********************.

🚧

Important

If you are calling a restricted operation to access a customer's Personally Identifiable Information (PII), such as buyer information or a shipping address, pass a Restricted Data Token (RDT) in the request headers instead of an LWA access token. You can call the createRestrictedDataToken operation in Tokens API to get a Restricted Data Token (RDT) for one or more restricted resources that you specify.

The following example response returns an RDT and its expiration time. The RDT token can be used in the Get Orders operation to retrieve PII data.

{ "restrictedDataToken": "Atz.sprdt|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR", "expiresIn": 3600 }

10. Verify that the response returns a payload that matches the Swagger model.

Use the Selling Partner API dynamic sandbox to make stateful requests

The SP-API also provides a dynamic sandbox where you can make requests and receive varied responses that are potentially stateful and that react to input.

You can determine which operations support dynamic sandbox calls by reviewing the Swagger model JSON for the API that you want to call. An operation supports calls to the dynamic sandbox if the operation includes the following object:

"x-amzn-api-sandbox": { "dynamic": {} }

The object can be found at either the operation or path level. When at the path level, all operations within the path can make calls to the dynamic sandbox.

For more details on how to make calls to the dynamic sandbox, refer to How to make a dynamic sandbox call to the Selling Partner API.

Conclusion

In this tutorial, you learned how to test your SP-API sandbox endpoints. In the walkthrough, you generated an LWA Access Token and explored examples of SP-API calls to the sandbox endpoints.