How to test Selling Partner API 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:

• 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.
• aws_access_key_id: Access keys are long-term credentials for an IAM user, obtained just after creating an IAM user while configuring your IAM policies and entities for SP-API.
• aws_secret_access_key: Access keys are long-term credentials for an IAM user, obtained just after creating an IAM user while configuring your IAM policies and entities for SP-API.
• 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

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).

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.

3. Under the Authorization tab, choose Type, and then select AWS Signature.
4. Pass the following values:

• AccessKey: Input the information obtained after configuring your IAM policies and entities for SP-API.
• SecretKey: Input the information obtained after configuring your IAM policies and entities for SP-API.
• AWS Region: Input the particular AWS Region associated with the Selling Partner API endpoints you wish to test.
• For the NA Region, enter us-east-1 and use the following URL: https://sts.amazonaws.com/?Version=2011-06-15&Action=AssumeRole&RoleSessionName=Test&RoleArn={{roleARN}}.

• 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}}.

• Service Name: Enter sts.

5. 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.

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:

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 Swagger Model.

8. Under the Authorization tab, click on the Type drop down menu and choose AWS Signature.
9. Pass the following values depending on your IAM configuration:
   • If an IAM role is associated with your application ID, pass the Access Key Id, Secret Access Key and Session Token obtained in Step 2. Generate temporary AWS access keys using AWS STS.
   • If an IAM user is associated with your application ID, pass the values for AWS Access Key Id and AWS Secret Access Key obtained after configuring your IAM policies and entities for SP-API. Leave the Session Token field empty.
   • Set the AWS Region as us-east-1.
   • Set the ServiceName as execute-api.

10. 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.

11. 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.

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

12. 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 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:

• Vendor Direct Fulfillment Orders API v2021-12-28 model
• Vendor Direct Fulfillment Shipping API v2021-12-28 model
• Vendor Direct Fulfillment Transactions API v2021-12-28 model

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

• Selling Partner API sandbox developer guide
• Authorizing Selling Partner API applications
• Tokens API Use Case Guide

👍

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.