Tutorial: Convert a public Amazon MWS application into a Selling Partner API application

Migration workflow

This migration workflow converts a public Amazon MWS application into a hybrid Selling Partner API application. A hybrid application can make API calls to both Amazon MWS and SP-API. With a hybrid application, you have functionality from both services and zero application downtime during the migration process.

Note: This workflow is for public applications only. A public application is publicly available and authorized by a selling partner. If you have a private application, go to Tutorial: Create a private Selling Partner application.

Migration tutorial for public applications

This tutorial explains how to convert a public Amazon MWS application to a hybrid Selling Partner API application.

Prerequisites

• A registered Amazon MWS application that is published in the Selling Partner Appstore.
• An Amazon Web Services (AWS) account. To create an account, sign up for AWS.

Step 1. Request the data access that your Selling Partner API application requires

1. Sign into Seller Central using your developer credentials and navigate to Develop Apps.
2. On the Developer Central page, choose View Profile.
3. On the Developer Profile page, in the Data Access section, select the roles that your applications require. For more information on choosing or requesting roles, refer to Roles in the Selling Partner API.
4. Choose Register.

The Developer Support team will evaluate your request and reply to your support case after their review is complete. This process may take several days. You can monitor your registration status in Developer Central on the Your developer registration is under review banner.

Note: You can not modify your Developer Profile while it is under review by Developer Support.

Step 2. Create and configure IAM resources

AWS Identity and Access Management (IAM) resources are required for you to convert your Amazon MWS application into a Selling Partner API application, including an IAM user, IAM policy, and an IAM role.

When you create your IAM role, you also generate an Amazon Resource Name (ARN), which is a unique identifier for your IAM role. You must use this IAM role ARN when you convert your private Amazon MWS application into a hybrid Selling Partner API application in Step 3.

You can create and configure your IAM resources in two ways:

• To programmatically create and configure the IAM resources, use the Selling Partner API on AWS Quick Start. The Selling Partner API on AWS Quick Start includes an AWS CloudFormation template that you deploy in your AWS account to programmatically create all of the required IAM policies and roles.

• To manually create and configure the IAM resources, refer to Creating and configuring IAM policies and entities in the Selling Partner API Developer Guide.

For more information about setting up AWS IAM, view the Integrate with Amazon SP-API: Set up AWS IAM video on the Amazon Seller University YouTube channel.

Step 3. Convert your public Amazon MWS application into a hybrid Selling Partner API application

1. Sign in to Seller Central using your developer credentials and navigate to Develop Apps.
2. On the Developer Central page, next to your Amazon MWS application, select Edit App.
3. From the App registration form, for API Type, choose SP-API and MWS. This selection populates the form with your app details.
4. In the IAM ARN box, paste the ARN for the IAM role that you created in Step 2. Create and configure IAM resources. If you are unsure of the ARN value, you can use the following processes:
   • If you created your IAM resources programmatically using the Selling Partner API on AWS Quick Start Deployment Guide, paste the ARN that you copied in Post-deployment steps - Copy the IAM role ARN.
   • If you created your IAM resources manually using the steps in the Selling Partner API Developer Guide, paste the ARN for the IAM role that you copied in Step 4. Create an IAM role. This IAM role should also have the AWS Security Token Service (AWS STS) policy attached.
   • To view the ARN in the AWS Management Console, sign in to the IAM Dashboard and in the left navigation pane, choose Roles. Search for and select the SP-API role that you created. On the Summary page, copy the Role ARN.
5. In the Roles section, select all roles required by your application. For more information on choosing or requesting roles, refer to Roles in the Selling Partner API.
6. Choose Save and Exit to complete the registration and create a draft hybrid Selling Partner API application.

Step 4. Implement OAuth authorization workflow

Set up and test an OAuth authorization workflow for your hybrid Selling Partner API application. For more information, refer to Authorizing Selling Partner API applications in the Selling Partner API Developer Guide.

When you finish testing your authorization workflow, you must convert your test authorization workflow to a production authorization workflow.

Step 5. Connect to the Selling Partner API

Set up a workflow for calling operations in the Selling Partner API. This workflow includes exchanging Login with Amazon (LWA) tokens, constructing URIs, adding headers, and creating and signing requests. To set up this workflow, generate and use an SDK that includes LWA token exchange and authentication. For more information, refer to Generating a Java SDK with LWA token exchange and authentication and Connecting to the Selling Partner API using a generated Java SDK in the Selling Partner API Developer Guide.

For information about connecting to the Selling Partner API sandbox, refer to the Selling Partner API sandbox guide.

Step 6. Migrate your notifications from Amazon MWS to Selling Partner API

As you migrate your MWS API sections, ensure you delete your old MWS subscriptions and use the Selling Partner API for Notifications that allows you to subscribe to notifications relevant to a selling partner's business. Using this API, you can create a destination to receive notifications, subscribe to notifications, delete notification subscriptions, and more.

Step 7. Publish your hybrid Selling Partner application in the Selling Partner Appstore

1. Sign into Seller Central using your developer credentials and navigate to Develop Apps.
2. On the Developer Central page, locate your application. Select Edit App and then choose Edit Listing.
3. On the App registration form, for API Type, choose SP-API and MWS. This selection populates the form with your app details.
4. Complete the remaining fields and submit the form. Your hybrid Selling Partner application will be published to the Selling Partner Appstore in 3 to 4 weeks.

Step 8. Migrate Amazon MWS authorizations to Selling Partner API authorizations

Note: Confirm that your Selling Partner API application is published in the Selling Partner Appstore prior to migrating your existing Amazon MWS authorizations to Selling Partner API authorizations. Additionally, any existing MWS authorization pathway used for your MWS or hybrid app must be removed in your new application. Removing the authorization pathway ensures that your new authorizations will be successful after conversion.

Migrate your existing Amazon MWS authorizations to Selling Partner API authorizations. For more information, refer to the Authorization API Use Case Guide. Be sure to store the LWA refresh token you receive in Step 2.

Step 9. Migrate your Amazon MWS calls to Selling Partner API calls

Update your application so that actions that previously called Amazon MWS operations will call the corresponding Selling Partner API operations. Refer to Mapping APIs from Amazon MWS to the Selling Partner API to determine which Selling Partner API operations correspond with which Amazon MWS operations.

🚧

Do not generate new LWA refresh tokens for every call to SP-API

The Authorization API is for migrating authorization from MWS to SP-API one time per authorization. It should not be used repeatedly to get new LWA refresh tokens for every SP-API call. An LWA refresh token should be stored and reused to get access tokens for subsequent calls.

Step 10. Convert your hybrid Selling Partner API application to a full Selling Partner API application

1. Convert your Hybrid SP-API application to a pure SP-API application (i.e. have SP-API as the only API type):
   • On the Developer Central page, locate your application. Choose the Edit App drop-down and then choose Edit Listing.
   • On the App registration form, for API type choose SP-API.
   • Submit the form.
2. Re-publish the application:
   • On the Developer Central page, locate your application. Choose Edit Listing.
   • Complete the listings form and submit.
3. Notify your sellers about the new authorization workflow.
   Note: After you switch to a full SP-API app, the old MWS authorization workflow will not be supported.