How to Test Selling Partner API Endpoints

This blog post explains how to test SP-API calls using selling partner sandbox endpoints.

by Ritika C., Integration Specialist, Selling Partner Developer Services | December 7th, 2022

Selling Partner APIs (SP-APIs) provide sandbox environments to test the SP-API endpoints without affecting production data. Directing calls to the SP-API sandbox endpoints allows you to make static requests that return mocked responses. By using the sandbox, you can learn the steps required to make a call, understand the request and response formats, practice validating application credentials, and play with API endpoints without impacting production data.

Overview

Use the following steps to test SP-API calls:

  1. Generate a Login with Amazon (LWA) access token: Authorize your application to access selling data on behalf of a selling partner. After the access token is issued, it can be used for multiple SP-API calls until it expires.
  2. Generate temporary AWS access keys using AWS Security Token Service (STS): Request temporary, limited-privilege credentials for the Identity and Access Management (IAM) user that you will use to sign SP-API requests.
  3. Make a call to the SP-API sandbox endpoint: Test API calls to examine mock requests and responses.

Tutorial

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

Prerequisites

To test SP-API calls, you need Self-authorization or a third-party OAuth workflow.

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

  • 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. This workflow will allow third-party sellers and vendors to authorize your application’s access to their selling data.

Variables needed to perform testing in Postman

In order to set up the credentials needed to make calls in Postman, you will need the following global variables for your workspace:

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

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 the 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, which return Personally Identifiable Information (PII). When calling restricted operations, instead of including an LWA access token, you include a Restricted Access Token (RDT).

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

2034

LWA access token request and response

Step 2. Generate temporary AWS access keys using AWS Security Token Service (STS)

If your application ID is associated with an Identity and Access Management role Amazon Resource Names (IAM role ARN), you must generate temporary AWS access keys using AWS STS. We recommend registering your application using an IAM role, as its short-term credentials increase security. For detailed steps, refer to Request AWS STS and generate temporary credentials using Postman.

The STS AssumeRole action allows you to request temporary, limited-privilege credentials for the IAM user that you will use to sign SP-API requests. To create an IAM user that assumes an IAM role has permissions to call the SP-API, refer to Creating and configuring IAM policies and entities.

If you have an IAM user ARN associated with your application ID, skip this step and go to Step 3. Make a call to the SP-API sandbox endpoint.

Use the following procedure to practice requesting and retrieving a response using an AWS STS:

  1. Make a GET call to https://sts.amazonaws.com/?Version=2011-06-15&Action=AssumeRole&RoleSessionName=Test&RoleArn=arn:aws:iam::XXXXXXXXXXXX:role/SellingParSellingPart&DurationSeconds=3600.
  2. Under the Params tab, replace the RoleArn with your account ARN.
2252

Postman Params tab

  1. Under the Authorization tab, choose Type, and then select AWS Signature.
  2. Pass the following values:
2710

Postman Authorization tab for the NA Region

  • For the EU Region, enter eu-west-1 and use the following URL: https://sts.eu-west-1.amazonaws.com/?Version=2011-06-15&Action=AssumeRole&RoleSessionName=Test&RoleArn=arn:aws:iam::336161429297:role/SellingPartnerAPIRole){{roleARN}}.
2724

Postman Authorization tab for the EU Region

  • Service Name: Enter sts.
  1. Under the AssumeRoleResponse/AssumeRoleResult/Credentials path, find the defined AWS Access Key Id, Secret Access Key and Session Token. Copy these variables onto your clipboard and save them for later. These temporary credentials will be used to access the SP-API endpoints.
2728

AssumeRoleResponse/AssumeRoleResult/Credentials path

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

Follow the steps to practice making a call to the SP-API sandbox endpoint using the Orders API Swagger Model.

  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. Refer to the following example of an Order API v0 Swagger Model, where Get Order API call is highlighted with a successful response:
2148

Order API v0 Swagger Model

  1. Make a GET Call to /orders/v0/orders.
  2. Set the baseUrl as Selling Partner API sandbox.
  3. Under the Params tab, pass the static request values from the Orders Swagger Model.
2704

Static request values under the Params tab

  1. Under the Authorization tab, click on the Type drop down menu and choose AWS Signature.
  2. Pass the following values depending on your IAM configuration:
2726

Postman Authorization tab for Get Orders v0 API

  1. Under the Headers tab, pass the access_token received from 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.
2720

Access token under the Headers tab

  1. 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's 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 the PII data.

2708

Restricted Data Token response and expiration time

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

  1. Verify that the response returns a payload that matches the Swagger model.
2698

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 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": {} }

For now, the dynamic sandbox is limited to Vendor Direct Fulfillment APIs 2021-12-28 version only. The following APIs are available for dynamic sandbox operations:

Use the Vendor Direct Fulfillment SandboxData API 2021-10-28 version to generate fictional orders to use while testing with these APIs. For more details on how to make calls, refer to Vendor Direct Fulfillment Dynamic sandbox.

Conclusion

This blog post guided you on how to test your SP-API sandbox endpoints. In the walk-through, you generated an LWA Access Token, created temporary AWS access keys using AWS STS, and explored examples of SP-API calls to the sandbox endpoints. You also learned about the dynamic sandbox and the APIs available for dynamic sandbox operations.

Related resources

👍

Have feedback on this post?

If you have questions or feedback on this post, we'd like to hear from you! Please vote and leave a comment using the tools at the bottom of this page.

Subscribe to updates via RSS feed.