Tutorial: Test Selling Partner API Endpoints
Use the sandbox to make test calls without impacting production data.
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).
![lwa access token request and response.png 2034](https://files.readme.io/b07e7cc-lwa_access_token_request_and_response.png)
LWA access token request and response
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.
- Import the Orders API Swagger model to your Postman workspace.
- 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. - Set the request parameters with the same values that the Orders API Swagger model defines.
- 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:
![Order API v0 Swagger Model.png 2148](https://files.readme.io/1a64633-Order_API_v0_Swagger_Model.png)
Orders API v0 Swagger model
- Make a
GET
Call to/orders/v0/orders
. - Set the
baseUrl
as Selling Partner API sandbox. - Under the Params tab, pass the static request values from the Orders API model.
![Static request values under the Params tab.png 2704](https://files.readme.io/edf56a4-Static_request_values_under_the_Params_tab.png)
Static request values under the Params tab
- Under the Headers tab, pass the
access_token
received in Step 1 for each API call, using the key value pairx-amz-access-token
:Atc|********************
. Skip this step for restricted operations and grantless operations.
![Access token under the Headers tab.png 2720](https://files.readme.io/de868a9-Access_token_under_the_Headers_tab.png)
Access token under the Headers tab
- For restricted operations, pass the Restricted Data Token (RDT) received from the
createRestrictedDataToken
operations using the key value pairx-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.
![Restricted Data Token response and expiration time.png 2708](https://files.readme.io/5408b6c-Restricted_Data_Token_response_and_expiration_time.png)
Restricted Data Token response and expiration time
{ "restrictedDataToken": "Atz.sprdt|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR", "expiresIn": 3600 }
- Verify that the response returns a payload that matches the Swagger model.
![Get Orders v0 API static response using access token.png 2698](https://files.readme.io/8c66161-Get_Orders_v0_API_static_response_using_access_token.png)
Get Orders v0 API static response using access token
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.
Updated about 1 month ago