Amazon Selling Partner API - spapi.vip

Tokens API Use Case Guide

AmazonSPAPI

# What is the Tokens API?

The Selling Partner API for Tokens (Tokens API) provides a secure way to access a customer's Personally Identifiable Information (PII). You can call the createRestrictedDataToken (opens new window) operation of the Tokens API to get a Restricted Data Token (RDT) for one or more restricted resources that you specify. Or, if you have a "delegatee application," you can get an RDT from a "delegator application" owned by a developer that you work closely with (see Delegating authorization). In either case, an RDT authorizes you to make calls to operations that return restricted data. For definitions, see Terminology.

When you call a restricted operation, you include an RDT in the x-amz-access-token header. This is in contrast to other Selling Partner API operations, where you include an LWA access token in the x-amz-access-token header. For more information, see Step 3. Add headers to the URI (opens new window) in the Selling Partner API Developer Guide.

# Delegating authorization

With the Tokens API, a delegator application can get an RDT that delegates authorization to access PII to a delegatee application. The delegator application is authorized by the selling partner and is the application that the selling partner interacts with. The delegatee application performs a specialized function that requires PII, such as shipping, tax invoicing, or tax remittance services. These two applications are owned by different developers and are closely integrated, such that the delegator application can securely transmit an RDT to the delegatee application. For more information about delegating authorization using an RDT, see Tutorial: Delegate authorization to access PII.

# Terminology

  • Restricted Data Token (RDT). A short-lived access token that authorizes calls restricted operations. An RDT remains valid for one hour.

  • Restricted operation. An operation that returns restricted data, such as PII. You need an RDT to call a restricted operation.

  • Restricted resource. An HTTP method and path that represent a restricted operation.

  • Restricted report type. A report type that contains PII. See Restricted report types.

  • Delegator application. An application that gets an RDT and passes it to a delegatee application. The selling partner authorizes and interacts with the delegator application.

  • Delegatee application. An application that gets authorization to call restricted operations from an RDT that is passed to it by a delegator application. A delegatee application performs a specialized function that requires PII, such as shipping, tax invoicing, or tax remittance services, and is not directly authorized by the selling partner.

  • Specific path. A path in a restricted resource that contains a specific order or shipment identifier. For example, orders/v0/orders/902-3159896-1390916/address

  • Generic path. A path in a restricted resource that contains a generic identifier, such as {orderId} or {shipmentId}. For example, orders/v0/orders/{orderId}/address

# Restricted operations

Restricted operations return customers' Personally Identifiable Information (PII). You need an RDT to call a restricted operation.

Here is list of restricted operations, grouped by API:

Direct Fulfillment Orders API:

  • getOrders
  • getOrder

Direct Fulfillment Shipping API:

  • getShippingLabels
  • getPackingSlips
  • getCustomerInvoices

Merchant Fulfillment API:

  • getShipment
  • cancelShipment
  • cancelShipmentOld
  • createShipment

Orders API:

  • getOrders
  • getOrder
  • getOrderItems
  • getOrderRegulatedInfo

Reports API:

  • getReportDocument

    Notes.

    • The getReportDocument operation is considered a restricted operation only when a restricted report type is specified. See the list of restricted report types.
    • When calling the createRestrictedDataToken operation to get an RDT for the getReportDocument operation, the specified restricted resource can contain only a specific path, not a generic path. For definitions, see Terminology.

Shipment Invoicing:

  • getShipmentDetails

Shipping API:

  • getShipment

# Restricted report types

Restricted report types contain PII. When specifying a restricted report type in a call to the getReportDocument operation, you must pass in an RDT with the call.

Here is a list of restricted report types:

  • GET_AMAZON_FULFILLED_SHIPMENTS_DATA_INVOICING
  • GET_AMAZON_FULFILLED_SHIPMENTS_DATA_TAX
  • GET_FLAT_FILE_ACTIONABLE_ORDER_DATA_SHIPPING
  • GET_FLAT_FILE_ORDER_REPORT_DATA_SHIPPING
  • GET_FLAT_FILE_ORDER_REPORT_DATA_INVOICING
  • GET_FLAT_FILE_ORDER_REPORT_DATA_TAX
  • GET_FLAT_FILE_ORDERS_RECONCILIATION_DATA_TAX
  • GET_FLAT_FILE_ORDERS_RECONCILIATION_DATA_INVOICING
  • GET_FLAT_FILE_ORDERS_RECONCILIATION_DATA_SHIPPING
  • GET_ORDER_REPORT_DATA_INVOICING
  • GET_ORDER_REPORT_DATA_TAX
  • GET_ORDER_REPORT_DATA_SHIPPING
  • GET_EASYSHIP_DOCUMENTS
  • GET_GST_MTR_B2B_CUSTOM
  • GET_VAT_TRANSACTION_DATA
  • SC_VAT_TAX_REPORT

# Tutorial: Get authorization to access PII for bulk orders

You can get an RDT that provides authorization to access Personally Identifiable Information (PII) for bulk orders. The dataElements values that you specify (using the restrictedResources (opens new window) parameter of the createRestrictedDataToken operation) determine the type of restricted data that the RDT authorizes your application to access. In this tutorial we request an RDT that authorizes access to both buyer information and shipping address information.

Prerequisites

To complete this tutorial, you will need:

  • Authorization from the selling partner for whom you are making calls. See the Selling Partner API Developer Guide (opens new window) for more information.

  • Approval for the roles that are required to access buyer information and/or shipping address information. These are:

    • Direct-to-consumer shipping. Required to access shipping address information.
    • Tax remittance. Required to access buyer information.
    • Tax invoicing. Required to access buyer information.

    To request access to these roles, see Registering as a developer (opens new window) in the Selling Partner API Developer Guide and update your developer profile.

# Step 1. Get an RDT

Call the createRestrictedDataToken operation to get an RDT.

  1. Call the createRestrictedDataToken (opens new window) operation, passing the following parameters:

Body parameter:

Parameter Description Required
restrictedResources

Model of a restricted resource. Maximum: 50

Type: RestrictedResource

 Yes

Request Example:

POST https://sellingpartnerapi-na.amazon.com/tokens/2021-03-01/restrictedDataToken
{
  "restrictedResources": [
    {
      "method": "GET",
      "path": "/orders/v0/orders",
      "dataElements": ["buyerInfo", "shippingAddress"]
    }
  ]
}
1
2
3
4
5
6
7
8
9
10

# Response

A successful response includes the following:

Name Description
restrictedDataToken

A Restricted Data Token (RDT). This is a short-lived access token that authorizes a call to the restricted operations represented by the restricted resources that you specified. Pass this value in the x-amz-access-token header when making subsequent calls to the restricted operations.

Type: string

expiresIn

The lifetime of the RDT, in seconds.

Type: integer

Response Example:

{
  "restrictedDataToken": "Atz.sprdt|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR",
  "expiresIn": 3600
}
1
2
3
4
  1. Save the restrictedDataToken value (the RDT) to use in Step 2. Include the RDT with a call to the getOrders operation

# Step 2. Include the RDT with a call to the getOrders operation

Call the getOrders (opens new window) operation of the Orders API, specifying the appropriate parameters to filter for the orders that you want. Be sure to include the RDT from Step 1. Get an RDT in the x-amz-access-token header of your call to getOrders. Because you specified both buyerInfo and shippingAddress in Step 1. Get an RDT, your call to getOrders is authorized to return both buyer information and shipping address information for each order. Had you specified only buyerInfo in Step 1, getOrders would be authorized to return only buyer information for each order. Had you specified only shippingAddress in Step 1, getOrders would be authorized to return only shipping address information for each order.

# Tutorial: Get authorization to access PII for the order items in an order

You can get an RDT that provides authorization to access Personally Identifiable Information (PII) in the order items in a specified order. In this workflow you specify dataElements=buyerInfo to indicate that the RDT will authorize your application to access buyer information for the order items.

Prerequisites

To complete this tutorial, you will need:

  • Authorization from the selling partner for whom you are making calls. See the Selling Partner API Developer Guide (opens new window) for more information.

  • Approval for the roles that are required to access buyer information. These are:

    • Tax remittance
    • Tax invoicing

    You might need approval for only one of these roles, depending on your use case. To request access to these roles, see Registering as a developer (opens new window) in the Selling Partner API Developer Guide and update your developer profile.

# Step 1. Get an order ID

You need an order ID to identify an order for which you want order item information. You also need an order ID to get an RDT that authorizes your application to access buyer information for the order items. You can use the getOrders operation of the Orders API to get a list of orders, from which you can get an order ID for the order that you are interested in.

  1. Call the getOrders (opens new window) operation of the Orders API, specifying the appropriate parameters to filter for the order that you want.

    The operation returns orders that match your request. Each order includes an order ID.

  2. From the orders that are returned, identify the order for which you want order item information.

  3. Save the order ID for the order that you want, to use in Step 2. Get an RDT and Step 3. Include the RDT with a call to the getOrderItems operation.

# Step 2. Get an RDT

Call the createRestrictedDataToken operation to get an RDT. In the path property of the restrictedResources parameter, include the order ID from Step 1. Get an order ID. In this workflow we will specify the buyerInfo value of the dataElements parameter. This indicates that the RDT should provide authorization to access PII for use cases such as tax and gift wrapping.

Call the createRestrictedDataToken operation to get an RDT.

  1. Call the createRestrictedDataToken (opens new window) operation, passing the following parameter:

Body parameter:

Parameter Description Required
restrictedResources

Model of a restricted resource. Maximum: 50

Type: RestrictedResource

 Yes

Request Example:

POST https://sellingpartnerapi-na.amazon.com/tokens/2021-03-01/restrictedDataToken
{
  "restrictedResources": [
    {
      "method": "GET",
      "path": "/orders/v0/orders/123-1234567-1234567/orderItems",
      "dataElements": ["buyerInfo"]
    }
  ]
}
1
2
3
4
5
6
7
8
9
10

# Response

A successful response includes the following:

Name Description
restrictedDataToken

A Restricted Data Token (RDT). This is a short-lived access token that authorizes a call to the restricted operations represented by the restricted resources that you specified. Pass this value in the x-amz-access-token header when making subsequent calls to the restricted operations.

Type: string

expiresIn

The lifetime of the RDT, in seconds.

Type: integer

Response Example:

{
  "restrictedDataToken": "Atz.sprdt|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR",
  "expiresIn": 3600
}
1
2
3
4
  1. Save the restrictedDataToken value (the RDT) to use in Step 3. Include the RDT with a call the getOrder operation.

# Step 3. Include the RDT with a call to the getOrderItems operation

Call the getOrderItems (opens new window) operation of the Orders API, specifying the order ID that you identified in Step 1. Get an order ID. Be sure to include the RDT from Step 1 in the x-amz-access-token header of your call to getOrderItems.

# Tutorial: Delegate authorization to access PII

You can delegate authorization to call restricted operations to a "delegatee application," which is an application that performs a specialized function for a selling partner (such as shipping, tax invoicing, or tax remittance services) but is not directly authorized by the selling partner. You delegate authorization in this way by

  1. Calling the createRestrictedDataToken (opens new window) operation of the Tokens API (specifying the application ID of the delegatee application),
  2. Getting an RDT from the createRestrictedDataToken response, and
  3. Passing the RDT to the delegatee application.

The RDT authorizes the delegatee application to call restricted operations that return the PII required to perform functions on behalf of the selling partner. For definitions, see Terminology.

Prerequisites

To complete this tutorial, you will need:

  • Authorization from the selling partner for whom you are making calls. See the Selling Partner API Developer Guide (opens new window) for more information.

  • To have indicated in the App registration form that you want to delegate access to PII to another application. For instructions for updating the App registration form, see Registering your application (opens new window) in the Selling Partner API Developer Guide. Indicate in the form the types of PII that you want to delegate.

  • The order ID for an order that requires shipping or tax functionality.

  • A partnership with a developer with a delegatee application.

  • The application ID of the delegatee application.

  • A secure means to transmit an RDT and an order ID to a delegatee application.

In addition, the developer with the delegatee application in Step 3. The delegatee application calls the getOrder operation will need to:

# Step 1. Get an RDT

Call the createRestrictedDataToken operation to get an RDT. In the path property of the restrictedResources parameter, include the order ID of the order for which PII is required. In this workflow we will specify both the buyerInfo and shippingAddress values of the dataElements parameter. This indicates that the RDT should include authorization to access PII for use cases such as tax and shipping. In your own workflow you might specify only one value, depending on the PII your use case requires.

  1. Call the createRestrictedDataToken (opens new window) operation, passing the following parameters:

Body parameters:

Parameter Description Required
restrictedResources

Model of a restricted resource. Maximum: 50

Type: RestrictedResource

 Yes
targetApplication

The application ID for the target application to which access is being delegated.

Type: string

No

Request Example:

POST https://sellingpartnerapi-na.amazon.com/tokens/2021-03-01/restrictedDataToken
{
  "restrictedResources": [
    {
      "method": "GET",
      "path": "/orders/v0/orders/123-1234567-1234567",
      "dataElements": ["buyerInfo", "shippingAddress"]
    }
  ],
  "targetApplication": "amzn1.sellerapps.app.target-application"
}
1
2
3
4
5
6
7
8
9
10
11

# Response

A successful response includes the following:

Name Description
restrictedDataToken

A Restricted Data Token (RDT). This is a short-lived access token that authorizes a call to the restricted operations represented by the restricted resources that you specified. Pass this value in the x-amz-access-token header when making subsequent calls to the restricted operations.

Type: string

expiresIn

The lifetime of the RDT, in seconds.

Type: integer

Response Example:

{
  "restrictedDataToken": "Atz.sprdt|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR",
  "expiresIn": 3600
}
1
2
3
4
  1. Save the restrictedDataToken value (the RDT) to provide to the delegatee application in the following step.

# Step 2. Pass the RDT and order ID to the delegatee application

Securely transmit the RDT and order ID to the delegatee application. The application will use these when calling the getOrder operation in the following step.

# Step 3. The delegatee application calls the getOrder operation

The delegatee application calls the getOrder (opens new window) operation of the Orders API, specifying in the path the order ID from Step 2. Pass the RDT and order ID to the delegatee application. The call must include the RDT (also from Step 2) in the x-amz-access-token header of the call. Because both buyerInfo and shippingAddress were specified in Step 1. Get an RDT, the call to getOrder returns both buyer information and shipping address information for the order.

  1. The delegatee application calls the getOrder (opens new window) operation, passing the following parameters:

Body parameters:

Parameter Description Required
orderId

An Amazon-defined order identifier, in 3-7-7 format.

Type: string

 Yes

Request Example:

GET https://sellingpartnerapi-na.amazon.com/orders/v0/orders/123-1234567-1234567
1

# Response

A successful response includes the following:

Name Description
payload

The payload for the getOrder operation.

Type: Order

Response Example:

{
  "payload": {
    "AmazonOrderId": "902-3159896-1390916",
    "PurchaseDate": "2017-01-20T19:49:35Z",
    "LastUpdateDate": "2017-01-20T19:49:35Z",
    "OrderStatus": "Pending",
    "FulfillmentChannel": "SellerFulfilled",
    "NumberOfItemsShipped": 0,
    "NumberOfItemsUnshipped": 0,
    "PaymentMethod": "Other",
    "PaymentMethodDetails": [
      "CreditCard",
      "GiftCerificate"
    ],
    "MarketplaceId": "ATVPDKIKX0DER",
    "ShipmentServiceLevelCategory": "Standard",
    "OrderType": "StandardOrder",
    "EarliestShipDate": "2017-01-20T19:51:16Z",
    "LatestShipDate": "2017-01-25T19:49:35Z",
    "IsBusinessOrder": false,
    "IsPrime": false,
    "IsGlobalExpressEnabled": false,
    "IsPremiumOrder": false,
    "IsSoldByAB": false,
    "DefaultShipFromLocationAddress": {
      "Name": "MFNIntegrationTestMerchant",
      "AddressLine1": "2201 WESTLAKE AVE",
      "City": "SEATTLE",
      "StateOrRegion": "WA",
      "PostalCode": "98121-2778",
      "CountryCode": "US",
      "Phone": "+1 480-386-0930 ext. 73824",
      "AddressType": "Commercial"
    },
    "FulfillmentInstruction": {
      "FulfillmentSupplySourceId": "sampleSupplySourceId"
    },
    "IsISPU": false,
    "ShippingAddress": {
      "Name": "Michigan address",
      "AddressLine1": "1 Cross St.",
      "City": "Canton",
      "StateOrRegion": "MI",
      "PostalCode": "48817",
      "CountryCode": "US"
    },
    "BuyerInfo": {
      "BuyerEmail": "user@example.com",
      "BuyerName": "John Doe",
      "BuyerTaxInfo": {
        "CompanyLegalName": "A Company Name"
      },
      "PurchaseOrderNumber": "1234567890123"
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
  1. The delegatee application uses the data in the response to perform its shipping and tax functions.

# Tutorial: Get authorization to access shipment information for multiple shipments

You can get an RDT that provides authorization to get shipment information for any of a selling partner's shipments.

Prerequisites

To complete this tutorial, you will need:

  • Authorization from the selling partner for whom you are making calls. See the Selling Partner API Developer Guide (opens new window) for more information.

  • Approval for the Direct-to-consumer shipping role, which is required to access shipping address information. To request access to this role, see Registering as a developer (opens new window) in the Selling Partner API Developer Guide and update your developer profile.

  • Shipment IDs for the shipments that you want to get shipment information for.

# Step 1. Get an RDT

Call the createRestrictedDataToken operation to get an RDT. In the path property of the restrictedResources parameter that you specify, use a generic path that includes this text: {shipmentId}. For definitions, see Terminology.

  1. Call the createRestrictedDataToken (opens new window) operation, passing the following parameter:

Body parameters:

Parameter Description Required
restrictedResources

Model of a restricted resource. Maximum: 50

Type: RestrictedResource

 Yes

Request Example:

POST https://sellingpartnerapi-na.amazon.com/tokens/2021-03-01/restrictedDataToken
{
  "restrictedResources": [
    {
      "method": "GET",
      "path": "/mfn/v0/shipments/{shipmentId}"
    }
  ]
}
1
2
3
4
5
6
7
8
9

# Response

A successful response includes the following:

Name Description
restrictedDataToken

A Restricted Data Token (RDT). This is a short-lived access token that authorizes you to call the restricted operations represented by the restricted resources that you specified. Pass the RDT value in the x-amz-access-token header when making subsequent calls to the restricted operations.

Type: string

expiresIn

The lifetime of the RDT, in seconds.

Type: integer

Response Example:

{
  "restrictedDataToken": "Atz.sprdt|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR",
  "expiresIn": 3600
}
1
2
3
4

  1. Save the restrictedDataToken value (the RDT) to use in Step 2. Include the RDT with a call the getShipment operation.

    For definitions, see Terminology.

# Step 2. Include the RDT with a call the getShipment operation

Call the getShipment (opens new window) operation of the Merchant Fulfillment API, using the generic path that you specified in Step 1. Get an RDT and replacing {shipmentId} with a real shipment ID from the selling partner. For example, GET /mfn/v0/shipments/FBA1234ABC5D. Repeat for all of the shipments for which you want shipping information, specifying the appropriate shipment ID with each call. Each call must include the RDT from Step 1. Get an RDT in the x-amz-access-token header.

Note. An RDT remains valid for one hour.

# Tutorial: Generate a Java SDK for the Tokens API

With this SDK you can make calls to the Tokens API with the following code already set up for you: Login with Amazon token exchange (exchange a refresh token for an access token) and authentication.

To generate a Java SDK with LWA token exchange and authentication

  1. Install Java 8 or newer (opens new window), Apache Maven 3.6. or greater (opens new window), and GNU Wget (opens new window) and make them available in your $PATH.

  2. Go to https://github.com/amzn/selling-partner-api-models (opens new window).

  3. Clone the repository to make a local copy on your computer, if you haven't done so already.

  4. Open a command prompt window and go to a directory where you want to download the Swagger Code Generator.

  5. Download the latest version of the Swagger Code Generator.

    For example:

    wget https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.4.13/swagger-codegen-cli-2.4.13.jar -O swagger-codegen-cli.jar
    1

    swagger-codegen-cli.jar downloads to the current directory.

    Note: You can also download from maven.org by directing your browser here: https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.4.13/swagger-codegen-cli-2.4.13.jar (opens new window)

  6. Copy swagger-codegen-cli.jar into a directory structure that makes sense for you. For this example, we'll copy it to C:\SwaggerToCL.

  7. Navigate to tokens_2021-03-01.json in the selling-partner-api-models\models\tokens-api-model folder of your local copy of the repository.

  8. Copy tokens_2021-03-01.json into C:\SwaggerToCL.

  9. Generate the SDK against the templates in the selling-partner-api-models\clients\sellingpartner-api-aa-java folder of your local copy of the repository. This folder contains an authorization and authentication library, along with customized templates for the Swagger Code Generator.

    For example:

    java -jar C:\SwaggerToCL\swagger-codegen-cli.jar generate -i C:\SwaggerToCL\tokens_2021-03-01.json -l java -t [path to selling-partner-api-models\clients\sellingpartner-api-aa-java folder]\resources\swagger-codegen\templates\ -o C:\SwaggerToCL\Tokens_JavaCL
    1

    The SDK is copied to C:\SwaggerToCL\Tokens_JavaCL

  10. Build the AA Library and add it as a dependency of the SDK:

    1. Navigate to the selling-partner-api-models\clients\sellingpartner-api-aa-java folder of your local copy of the repository and run mvn package. This generates a folder named "target". In this folder is a JAR file named sellingpartnerapi-aa-java-1.0-jar-with-dependencies.jar (or something similar) and all of the required dependencies.

    2. Install the JAR file in your local Maven repository.

      For example:

      mvn install:install-file -Dfile=[path to JAR file in "target" folder] -DgroupId=com.amazon.sellingpartnerapi -DartifactId=sellingpartnerapi-aa-java -Dversion=1.0 -Dpackaging=jar
      1

      You can find the actual groupId, artifactId, and version values near the top of the pom.xml file in the selling-partner-api-models\clients\sellingpartner-api-aa-java folder.

  11. Add a dependency on the AA library in the pom.xml of the client library:

    For example:

    <dependency>
<groupId>com.amazon.sellingpartnerapi</groupId>
<artifactId>sellingpartnerapi-aa-java</artifactId>
<version>1.0</version>
</dependency>
    1
    2
    3
    4
    5

  12. Run mvn package inside the generated SDK folder.

  13. Download any of the following files and use them to build classes inside the main/java/sampleCode/ folder of the generated client library. For definitions, see Terminology.

    Note. Use the latest version of tokens_2021-03-01.json when generating your SDK to ensure that you are getting the latest functionality.

You can now start testing workflows for getting RDTs and calling restricted operations. Use this code to guide you in building your own applications.

Uploads API