3P Website Authorization Workflow for Amazon Shipping API

This document provides overview for 3P developers (Integrators) to build OAuth 2.0 workflow with Amazon Shipping API v2 API.

Authorizing Amazon Shipping API applications

The authorization model for the Amazon Shipping API is based on Login with Amazon, Amazon’s implementation of OAuth 2.0. In this model the Amazon Shipping account user authorizes your application by interacting with pages displayed by Amazon and by your website. Actions taken by the Amazon Shipping partner trigger responses by your website or by Amazon. The Amazon Shipping partner’s browser is the user-agent that passes parameters between your website and Amazon at each Amazon Shipping partner action. To implement OAuth authorization, you must configure your website to (1) accept and process the parameters that Amazon returns to it, and (2) redirect the Amazon Shipping user’s browser and pass parameters to Amazon.
Shippers can authorize your applications using below mentioned workflow: Website workflow, an OAuth authorization workflow initiated from your own website.

OAuth Authorization URLs

An OAuth authorization URI is a key component for creating and testing Amazon Shipping API authorization workflows. The OAuth authorization URI redirects a browser to an Amazon sign-in page. After sign-in, a consent page appears, where the shipper can give your application consent to make calls to the Amazon Shipping API on their behalf.

The Website authorization workflow is an OAuth authorization workflow that is initiated from your own website. The Selling partners OR Shipper sign into your website and click an “Authorize” button that you configure to initiate authorization. For more information, see Step 0. Set up an "Authorize" button.

Note. The examples in the following steps are for a seller application, using an OAuth authorization URI based on a Seller Central URL. For vendor applications, you can replace the Seller Central URL with a Vendor Central URL. For more information, see Constructing an OAuth authorization URI.

Step 0. Set up an "Authorize" button

Set up an “Authorize” button (or something similar) on your application website that the shippers can click to initiate authorization of your application. When the shipper clicks the button, your website loads an OAuth authorization URI into the browser and the shipper is redirected to an Amazon sign-in page. After sign-in, a consent page appears, where a shipper can give your application consent to make calls to the Amazon Shipping API on their behalf. For information about constructing an OAuth authorization URI, see Constructing an OAuth authorization URI.

Note. If you have OAuth authorization URIs for more than one region e.g. United States, United Kingdom, Italy, France etc be sure to set up your “Authorize” buttons so that Shipper are redirected to the Shipper Central sign-in page for their own region.

Setting up your “Authorize” button(s) is a one-time task.

Step 1. The shipper initiates authorization from your website

  1. The shipper signs into your website. If the shipper does not yet have an account, they complete your registration process.

  2. The shipper clicks the "Authorize" button that you set up in Step 0. Set up an "Authorize" button. If you have more than one regional "Authorize" button, be sure that the shipper is directed to the button that corresponds to the region that they sell in.

  3. Your application loads the OAuth authorization URI into the browser, adding the following query parameters:

ParameterDescription
APPLICATION_IDApplication ID available via Seller Central OR Developer Central (Screenshot attached)
REDIRECT_URIA URI for redirecting the browser to your application. This must an OAuth Redirect URI that you specified when you registered your application. If you do not include the redirect_uri parameter, the default is the first OAuth Redirect URI that you specified when you registered your application.
STATE_TOKENA state value generated by your application. Your application uses this value to maintain state between this request and the response, helping to guard against cross-site request forgery attacks.


Important: Because OAuth information is passed via URL query parameters, we highly recommended that you do the following: 1) Ensure that the state token is short-lived and verifiably unique to your user, and 2) Set the Referrer-Policy: no-referrer HTTP header, which prevents leaking sensitive information to websites that your website links to. For more information about cross-site request forgery and calculating a state parameter, see Cross-site Request Forgery in the Login with Amazon documentation.

Note: If you include the version=beta parameter, the workflow authorizes an application in Draft state. If you do not include the parameter, the workflow authorizes an application published on the Amazon Seller Central Partner Network.

For example:

https://ship.amazon.co.uk/settings/details/integrations/authorize/<APPLICATION_ID>?state=<STATE_TOKEN>&redirect_uri=<REDIRECT_URI>&version=beta

OR

https://ship.amazon.co.uk/settings/details/integrations/authorize/<APPLICATION_ID>?state=<STATE_TOKEN>&version=beta

For Pure OFF Amazon Sample Market place Shipper central account Authorisation URL:

Market PlaceShipper account Authorisation URL
UKhttps://ship.amazon.co.uk/settings/details/integrations/authorize/<APPLICATION_ID>?state=<STATE_TOKEN>&redirect_uri=<REDIRECT_URI>&version=beta
Italyhttps://ship.amazon.it/settings/details/integrations/authorize/<APPLICATION_ID>?state=<STATE_TOKEN>&redirect_uri=<REDIRECT_URI>&version=beta
Francehttps://ship.amazon.fr/settings/details/integrations/authorize/<APPLICATION_ID>?state=<STATE_TOKEN>&redirect_uri=<REDIRECT_URI>&version=beta
Spainhttps://ship.amazon.es/settings/details/integrations/authorize/<APPLICATION_ID>?state=<STATE_TOKEN>&redirect_uri=<REDIRECT_URI>&version=beta
UShttps://ship.amazon.com/settings/details/integrations/authorize/<APPLICATION_ID>?state=<STATE_TOKEN>&redirect_uri=<REDIRECT_URI>&version=beta

The shipper arrives at the sign-in page of Shipper Central.

Step 2. The shipper consents to authorize the application

  1. The shipper signs into Shipper Central, depending on the type of OAuth Authorization URI you constructed. The consent page appears. For more information, see Constructing an OAuth Authorization URI.

  2. The shipper views the consent page, reviews the data access requested by your application, and then clicks Confirm to continue. The shipper can click Cancel to exit without authorizing.

Step 3. Amazon sends you the authorization information

Amazon briefly displays a page indicating that we are authorizing you to access the shipper's data. While that page is displayed, the following actions take place:

  1. Amazon loads your OAuth Redirect URI into the browser (the first one you specified when you registered you application) (screenshot captured at the end of the document), adding the following query parameters:
ParameterDescription
stateThe state value from Step 1. The seller initiates authorization from.
selling_partner_idThe identifier of the shipper OR selling partner who is authorizing your application.
spapi_oauth_codeThe Login with Amazon (LWA) authorization code that you exchange for an LWA refresh token. For more information, see Step 4. Your application exchanges the LWA authorization code for a LWA refresh token.
Note: An LWA authorization code expires after five minutes. Be sure to exchange it for an LWA refresh token before it expires.

For example:

https://client-example.com?selling_partner_id=sellingpartneridexample&spapi_oauth_code=spapioauthcodeexample&state=state-example
  1. Your application validates the state value.

  2. Your application saves the selling_partner_id and spapi_oauth_code values.

  3. Your website's landing page displays.

Step 4. Your application exchanges the LWA authorization code for a LWA refresh token

The Login with Amazon SDK for JavaScript can help you with the exchange of an LWA authorization code for an LWA refresh token.

Note: An LWA authorization code expires after five minutes. Be sure to exchange it for an LWA refresh token before it expires.

For more information, see the Login with Amazon documentation:

To exchange an LWA authorization code for an LWA refresh token

  1. Your application calls the Login with Amazon (LWA) authorization server (https://api.amazon.com/auth/o2/token) to exchange the LWA authorization code for an LWA refresh token. The call must include the following query parameters:
ParameterDescription
grant_typeThe type of access grant requested. Must be authorization_code.
codeThe LWA authorization code that you received in Step 3. Amazon sends you the authorization information.
redirect_uriThe redirect URI for your application.
client_idPart of your LWA credentials. To get this value, see Viewing your developer information.
client_secretPart of your LWA credentials. To get this value, see Viewing your developer information.

For example:

POST /auth/o2/token HTTP/l.l
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
grant_type=authorization_code&code=SplxlOexamplebYS6WxSbIA&client_id=foodev&client_secret=Y76SDl2F
  1. The LWA Authorization Server returns the LWA refresh token. The response is in JSON and includes the following elements.
ParameterDescription
access_tokenA token that authorizes your application to take certain actions on behalf of a selling partner. See Connecting to the Selling Partner API.
token_typeThe type of token returned. Should be bearer.
expires_inThe number of seconds before the access token becomes invalid.
refresh_tokenA long-lived token that can be exchanged for a new access token. See Connecting to the Selling Partner API.
HTTP/l.l 200 OK
Content-Type: application/json;
charset UTF-8
Cache-Control: no-store
Pragma: no-cache
{
  "access_token":"Atza|IQEBLjAsAexampleHpi0U-Dme37rR6CuUpSR",
  "token_type":"bearer",
  "expires_in":3600,
  "refresh_token":"Atzr|IQEBLzAtAhexamplewVz2Nn6f2y-tpJX2DeX"
}
  1. Your application saves the refresh_token value.

  2. The browser displays a page to the shipper OR selling partner that indicates next steps for using your application.

An LWA refresh token is a long-lived token that you exchange for an LWA access token. An access token obtained through this token exchange must be included with calls to all SP-API operations except restricted operations and grantless operations, which use somewhat different authorization models. After an access token is issued it is valid for one hour. The same access token can be used for multiple API calls, until it expires.

To exchange a refresh token for an access token using a generated SDK, see Connecting to the Selling Partner API using a generated Java SDK. To manually exchange a refresh token for an access token, see Connecting to the Selling Partner API.

Developer Central: Application_ID

Developer Central: Application Creation > Redirect URI