Selling Partner Reports API on AWS

Partner Solution Deployment Guide

QS

June 2022
Federico Rodriguez, Amazon Selling Partner Developer Services

Refer to the GitHub repository to view source files, report bugs, submit feature ideas, and post feedback about this Partner Solution. To comment on the documentation, refer to Feedback.

This Partner Solution was created by Amazon Selling Partner Developer Services in collaboration with Amazon Web Services (AWS). Partner Solutions are automated reference deployments that help people deploy popular technologies on AWS according to AWS best practices. If you’re unfamiliar with AWS Partner Solutions, refer to the AWS Partner Solution General Information Guide.

Overview

This guide provides instructions for deploying the Selling Partner Reports API Quick Start reference architecture on the AWS Cloud. If you are unfamiliar with AWS Quick Starts, refer to the AWS Quick Start General Information Guide.

Costs and licenses

No licenses are required to deploy this Quick Start. All AWS service resources consumed during the launch of the Quick Start incur AWS service usage costs.

Architecture

Deploying this Quick Start with default parameters builds the following Selling Partner Reports API environment in the AWS Cloud.

Architecture
Figure 1. Quick Start architecture for Selling Partner Reports API on AWS

As shown in Figure 1, the Quick Start sets up the following:

  • Three Amazon API Gateway HTTP endpoints, providing REST APIs for three Lambda functions.

    • Token storage to encrypt and store the selling partner’s SP-API refresh token.

    • Notifications subscriber to subscribe the selling partner to the SP-API notifications.

    • Report creator to submit report creation requests to the SP-API.

  • An AWS IAM role to authenticate API Gateway requests.

  • Two Amazon Dynamo DB tables, one for client tokens and another for report information.

  • A selling partner notifications Amazon Simple Queue Service (Amazon SQS) queue to receive SP-API notifications.

  • A notifications processor Lambda function to listen for SP-API messages and invoke an AWS Step Functions workflow.

  • An AWS Step Functions workflow (Report processor) containing the following resources:

    • A report document retrieval Lambda function to retrieve report information from the SP-API.

    • A report document storage Lambda function to store reports in an Amazon Simple Storage Service (Amazon S3) bucket.

    • A presigned URL generator Lambda function to generate presigned URLs for the stored reports.

    • An Amazon Simple Notification Service (Amazon SNS) topic to send email notifications of completed report processing.

    • An Amazon S3 bucket to store reports.

  • AWS Key Management Service (AWS KMS) to encrypt and decrypt client tokens.

  • AWS Secrets Manager to store SP-API IAM user credentials and SP-API application credentials.

Deployment options

This Quick Start provides the following deployment options:

Predeployment steps

Prepare your Seller Central account

You must have a Professional selling plan on Amazon Seller Central and register as a developer to create SP-API applications.

Your SP-API application must be registered with an AWS IAM role. If you are using an AWS IAM user instead, follow these steps:

  1. Sign in to Amazon Seller Central.

  2. Under Partner Network, choose Develop Apps.

  3. Choose Edit App.

  4. Update the application to use an AWS IAM role.

Deployment steps

  1. Sign in to your AWS account, and launch this Partner Solution, as described under Deployment options. The AWS CloudFormation console opens with a prepopulated template.

  2. Choose the correct AWS Region, and then choose Next.

  3. On the Create stack page, keep the default setting for the template URL, and then choose Next.

  4. On the Specify stack details page, change the stack name if needed. Review the parameters for the template. Provide values for the parameters that require input. For all other parameters, review the default settings and customize them as necessary. When you finish reviewing and customizing the parameters, choose Next.

    Unless you’re customizing the Partner Solution templates or are instructed otherwise in this guide’s Predeployment section, don’t change the default settings for the following parameters: QSS3BucketName, QSS3BucketRegion, and QSS3KeyPrefix. Changing the values of these parameters will modify code references that point to the Amazon Simple Storage Service (Amazon S3) bucket name and key prefix. For more information, refer to the AWS Partner Solutions Contributor’s Guide.

  5. On the Configure stack options page, you can specify tags (key-value pairs) for resources in your stack and set advanced options. When you finish, choose Next.

  6. On the Review page, review and confirm the template settings. Under Capabilities, select all of the check boxes to acknowledge that the template creates AWS Identity and Access Management (IAM) resources that might require the ability to automatically expand macros.

  7. Choose Create stack. The stack takes about 5 minutes to deploy.

  8. Monitor the stack’s status, and when the status is CREATE_COMPLETE, the Selling Partner Reports API deployment is ready.

  9. To view the created resources, choose the Outputs tab.

Postdeployment steps

Confirm the SNS subscription

When a report is generated, this Quick Starts sends a notification to the email specified in the Parameters section of the CloudFormation stack creation. To receive these emails, the Amazon SNS subscription has to be confirmed by choosing Confirm subscription in the email you receive from Amazon SNS.

Retrieve IAM user credentials to invoke API Gateway endpoints

This Quick Start deploys three API Gateway endpoints and an IAM role and user. Complete the following steps to retrieve the user’s access keys and the Amazon Resource Name (ARN) of the role. You will use these to test the deployment and invoke the API endpoints from your product or application.

IAM user access keys

  1. Open the AWS IAM console.

  2. In the navigation pane, choose Users.

  3. Choose the user named ApiGatewayInvokeUser.

  4. On the Summary page, choose the Security credentials tab.

  5. Under Access keys choose Create Access key.

  6. Copy the generated Access key ID and Secret access key, or, choose Download .csv file.

Role ARN

  1. Open the AWS IAM console.

  2. In the navigation pane, choose Roles.

  3. Select the role named ApiGatewayInvokeRole.

  4. On the role summary page, copy the role ARN.

Test the deployment

Complete the following steps to create and process SP-API reports using a pre-built Postman collection.

Retrieve API Gateway endpoint IDs

  1. Open the Amazon API Gateway console.

  2. On the APIs page, copy the IDs for TokenStorageRestApi, NotificationsSubscriberRestApi, and ReportCreatorRestApi.

Set up the Postman collection

  1. Open the Selling Partner Reports API Quick Start Postman collection documentation page.

  2. Choose Run in Postman to import the collection to a workspace in the Postman client application.

  3. In your Postman workspace, choose Variables.

  4. In the CURRENT VALUE column, enter the following variable values:

    1. For iamUserAccessKey, enter the Access key ID of the IAM user deployed by the Quick Start. To retrieve this, refer to IAM user access keys.

    2. For iamUserSecretKey, enter the Secret access key of the IAM user deployed by the Quick Start. To retrieve this, refer to IAM user access keys.

    3. For iamRoleArn, enter the ARN of the IAM role deployed by the Quick Start. To retrieve this, refer to Role ARN.

    4. For tokenStorageApiId, enter the ID for TokenStorageRestApi. To retrieve this, refer to Retrieve API Gateway endpoint IDs.

    5. For notificationsSubscriberApiId, enter the ID for NotificationsSubscriberRestApi. To retrieve this, refer to Retrieve API Gateway endpoint IDs.

    6. For reportCreatorApiId, enter the ID for ReportCreatorRestApi. To retrieve this, refer to Retrieve API Gateway endpoint IDs.

    7. For stackRegion, enter the AWS Region in which the stack was created (for example, us-east-1 or eu-west-1).

Retrieve credentials

  1. In your Postman workspace, under the Selling Partner Reports API Quick Start collection, choose the STS Assume API Gateway Role request.

  2. Choose Send to submit the request. The request retrieves the temporary credentials from ApiGatewayInvokeRole and automatically stores them in collection variables.

Invoke the API endpoints

TokenStorageRestApi

  1. In your Postman workspace, under the Selling Partner Reports API Quick Start collection, choose the Token Storage request.

  2. On the Body tab, replace the SellerId and RefreshToken values with the seller ID and refresh token from the selling partner.

  3. Choose Send. The request encrypts and stores the selling partner’s credentials in the AWS Cloud, to be used in subsequent SP-API calls.

NotificationsSubscriberRestApi

  1. In your Postman workspace, under the Selling Partner Reports API Quick Start collection, choose the Notifications Subscriber request.

  2. On the Body tab, replace the SellerId value with the selling partner seller ID. Replace the RegionCode value with the selling partner’s AWS Region. Valid values are NA, EU and FE.

  3. Choose Send to submit the request. The request subscribes your application to REPORT_PROCESSING_FINISHED notification for the specified selling partner.

ReportCreatorRestApi

  1. In your Postman workspace, under the Selling Partner Reports API Quick Start collection, choose the Report Creator request.

  2. On the Body tab, replace the SellerId and RegionCode values with the selling partner’s seller ID and Region. Complete the remaining parameters on the Body tab with valid values for the report you want to create.

  3. Choose Send to submit the request. The request creates a report in SP-API. The system processes the incoming notification, stores the report locally, and sends a notification to the email address provided.

Integrate the Quick Start with your product or application

Complete the steps in this section to retrieve the Quick Start API endpoint URLs and invoke them from your product or application.

Retrieve the API Gateway endpoint URLs

There are three API Gateway endpoints: TokenStorageRestApi, NotificationsSubscriberRestApi, and ReportCreatorRestApi. For each of these endpoints, retrieve its URL from the API Gateway console.

TokenStorageRestApi

  1. Sign in to the AWS Management Console, and open the API Gateway console.

  2. On the APIs page, choose TokenStorageRestApi.

  3. In the navigation pane, choose Stages.

  4. Expand the prod stage by choosing the right arrow.

  5. Under /tokens, choose POST.

  6. Copy the address for Invoke URL.

NotificationsSubscriberRestApi

  1. Sign in to the AWS Management Console, and open the API Gateway console.

  2. On the APIs page, choose NotificationsSubscriberRestApi.

  3. In the navigation pane, choose Stages.

  4. Expand the prod stage by choosing the right arrow.

  5. Under /notifications, choose POST.

  6. Copy the address for Invoke URL.

ReportCreatorRestApi

  1. Sign in to the AWS Management Console, and open the API Gateway console.

  2. On the APIs page, choose ReportCreatorRestApi.

  3. In the navigation pane, choose Stages.

  4. Expand the prod stage by choosing the right arrow.

  5. Under /reports, choose POST.

  6. Copy the address for Invoke URL.

Invoke the API endpoints

To invoke the Quick Start API endpoints from your product or application, you’ll need the following:

  • Access key and secret access key of the deployed IAM user. Refer to IAM user access keys, earlier in this guide.

  • ARN of the deployed IAM role. Refer to Role ARN, earlier in this guide.

  • URLs for TokenStorageRestApi, NotificationsSubscriberRestApi, and ReportCreatorRestApi endpoints. Refer to Retrieve the API Gateway endpoint URLs, earlier in this guide.

From your product or application, complete the following steps:

  1. Call the STS Assume Role API. Use the access key and secret access key of the deployed IAM user and the ARN of the deployed IAM role. This request retrieves temporary credentials from the ApiGatewayInvokeRole role, which are used in subsequent API calls.

  2. Send a POST request to TokenStorageRestApi using the TokenStorageRestApi endpoint URL. Sign the request using the temporary credentials from the ApiGatewayInvokeRole role from step 1. This request encrypts and stores the selling partner’s credentials in the AWS Cloud, which are used in subsequent SP-API calls. The following shows the body of a sample request.

      {
    "SellerId": "ABC...",
    "RefreshToken": "Atzr|..."
  }

  3. Send a POST request to NotificationsSubscriberRestApi using the NotificationsSubscriberRestApi endpoint URL. Sign the request using the temporary credentials from the ApiGatewayInvokeRole role from step 1. This request subscribes your application to the REPORT_PROCESSING_FINISHED notification for the specified selling partner specified. The following shows the body of a sample request.

    {
  "SellerId": "ABC...",
  "RegionCode": "NA|EU|FE",
  "NotificationType": "REPORT_PROCESSING_FINISHED"
}

  4. Send a POST request to ReportCreatorRestApi using the ReportCreatorRestApi endpoint URL. Sign the request using the temporary credentials from the ApiGatewayInvokeRole role from step 1. This request creates a report in SP-API. Then, the system processes the incoming notification, stores the report locally, and notifies using the email address provided. The following shows the body of a sample request.

    {
  "SellerId": "ABC...",
  "RegionCode": "NA|EU|FE",
  "ReportType": "GET_XML_BROWSE_TREE_DATA",
  "MarketplaceIds": "A1F83G8C2ARO7P",
  "ReportDataStartTime": "2022-03-01T09:00:00.000Z",
  "ReportDataEndTime": "2022-03-01T12:00:00.000Z",
  "ReportOptions": "{\"BrowseNodeId\": \"26978488031\"}"
}

AWS Step Functions workflow

This Quick Start enables REPORT_PROCESSING_FINISHED notification processing in an AWS Step Functions state machine. The state machine completes four steps: retrieve the report document, store it, generate a presigned URL for it, and send an email notification. This workflow covers basic functionality and is intended to be used as a template for a customized solution adapted to your product’s need. To extend the workflow, add or remove states. For more information, refer to States.

Best practices for using Selling Partner Reports API on AWS

For more information about Selling Partner API best practices, refer to the What is the Selling Partner API.

Security

This Quick Starts implements the following security best practices:

  1. Application credentials secure storage using AWS Secrets Manager secrets.

  2. Client token encryption using AWS KMS keys. By using the provided API Gateway TokenStorageRestApi endpoint and/or AWS Lambda SPAPITokenStorage function you are following credential encryption best practices.

  3. API authentication with temporary credentials.

  4. Least privilege IAM policies.

Troubleshooting

Q. I encountered a CREATE_FAILED error when I launched the Quick Start.

A. If AWS CloudFormation fails to create the stack, relaunch the template with Rollback on failure set to Disabled. This setting is under Advanced in the AWS CloudFormation console on the Configure stack options page. With this setting, the stack’s state is retained, and the instance keeps running so that you can troubleshoot the issue. (For Windows, look at the log files in %ProgramFiles%\Amazon\EC2ConfigService and C:\cfn\log.)

When you set Rollback on failure to Disabled, you continue to incur AWS charges for this stack. Delete the stack when you finish troubleshooting.

For more information, see Troubleshooting AWS CloudFormation.

Q. I encountered a size-limitation error when I deployed the AWS CloudFormation templates.

A. Launch the Quick Start templates from the links in this guide or from another S3 bucket. If you deploy the templates from a local copy on your computer or from a location other than an S3 bucket, you might encounter template-size limitations. For more information, see AWS CloudFormation quotas.

Q. Where do I find the client ID and client secret I need during installation?

A. Sign in to Amazon Seller Central. Under Partner Network, choose Develop Apps. Then, under LWA credentials, choose View.

Q. Which values should I use for Access Key and Secret Key parameters during the installation?

A. Specify the AWS IAM user’s access Key and secret key that you are currently using to assume role while signing your requests to SP-API.

Q. Which value should I use for the Role ARN parameter during the installation?

A. You have to specify the IAM role ARN that is currently registered in your app. To view the IAM role ARN for an app, sign in to Amazon Seller Central. Under Partner Network, choose Develop Apps. Then, choose Edit App.

Q. My application is currently registered with an AWS IAM user ARN instead of a role ARN, can I still use this Quick Start?

A. No. In order to use this Quick Start you have to update your application to use an AWS IAM role ARN instead. This is a best practice that increases the security of your application. To update this information, sign in to Amazon Seller Central. Under Partner Network, choose Develop Apps. Then choose Edit App.

Q. Will I automatically start receiving notifications for report processing completion after installing this Quick Start?

A. No. In order to start receiving notifications you must create the corresponding subscription by using the Amazon API Gateway NotificationsSubscriberRestApi endpoint. Subscriptions are specific to Selling Partners. You must call NotificationsSubscriberRestApi for each selling partner that you want to onboard to this Quick Start.

Q. Is it mandatory to store selling partner refresh tokens using the Amazon API Gateway TokenStorageRestApi endpoint provided in this Quick Start?

A. Yes. The AWS Step Functions workflow that is invoked when a report processing completion notification is received communicates to SP-API asynchronously. It signs the corresponding requests with the selling partner’s refresh token. For this reason, the refresh tokens have to be stored.

Customer responsibility

After you deploy a Partner Solution, confirm that your resources and services are updated and configured—including any required patches—to meet your security and other needs. For more information, refer to the Shared Responsibility Model.

Feedback

To submit feature ideas and report bugs, use the Issues section of the GitHub repository for this Partner Solution. To submit code, refer to the Partner Solution Contributor’s Guide. To submit feedback on this deployment guide, use the following GitHub links:

Notices

This document is provided for informational purposes only. It represents current AWS product offerings and practices as of the date of issue of this document, which are subject to change without notice. Customers are responsible for making their own independent assessment of the information in this document and any use of AWS products or services, each of which is provided "as is" without warranty of any kind, whether expressed or implied. This document does not create any warranties, representations, contractual commitments, conditions, or assurances from AWS, its affiliates, suppliers, or licensors. The responsibilities and liabilities of AWS to its customers are controlled by AWS agreements, and this document is not part of, nor does it modify, any agreement between AWS and its customers.

The software included with this paper is licensed under the Apache License, version 2.0 (the "License"). You may not use this file except in compliance with the License. A copy of the License is located at https://aws.amazon.com/apache2.0/ or in the accompanying "license" file. This code is distributed on an "as is" basis, without warranties or conditions of any kind, either expressed or implied. Refer to the License for specific language governing permissions and limitations.