Tokens API Use Case Guide

API Version: 2021-03-01

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 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 (refer to Delegating authorization). In either case, an RDT authorizes you to make calls to operations that return restricted data. For definitions, refer to 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, refer to Step 3. Add headers to the URI.

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, refer to 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. Refer to 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 Orders API v2021-12-28

• getOrders
• getOrder

Direct Fulfillment Shipping API:

• getShippingLabel
• getShippingLabels
• getPackingSlip
• getPackingSlips
• getCustomerInvoice
• getCustomerInvoices
• createShippingLabels

Direct Fulfillment Shipping API v2021-12-28

• getShippingLabel
• getCustomerInvoices
• getCustomerInvoice
• getPackingSlips
• getPackingSlip

Easy Ship API v2022-03-23

• createScheduledPackageBulk

Merchant Fulfillment API:

• getShipment
• cancelShipment
• cancelShipmentOld
• createShipment

Orders API:

• getOrders
• getOrder
• getOrderItems
• getOrderRegulatedInfo
• getOrderAddress
• getOrderBuyerInfo
• getOrderItemsBuyerInfo

Reports API:

• getReportDocument

Notes

• The getReportDocument operation is considered a restricted operation only when a restricted report type is specified. Refer to 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, refer to Terminology.
• When using RDT to access the getReportDocument operation, make sure your application has the correct right roles to access the report. Refer to Roles in the Selling Partner API for roles to reports mapping.

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 restricted report types with PII information

• The getReportDocument operation is considered a restricted operation only when a restricted report type is specified. Refer to 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, refer to Terminology.

Prerequisites

To complete this tutorial, you will need:

• Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API applications for more information.

• Approval for the following roles:

  • 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, refer to Registering as a developer and update your developer profile.

Step 1. Get an RDT

1. Call the createRestrictedDataToken operation, passing the following parameters:

Body parameter:

Request Example

POST https://sellingpartnerapi-na.amazon.com/tokens/2021-03-01/restrictedDataToken

{
  "restrictedResources": [
    {
      "method": "GET",
      "path": "/reports/2021-06-30/documents/amzn1.spdoc.1.4.eu.dca0cb77-4733-4769-8476-f09bc32be2af.T1KIM200NIMFNU.1234"
    }
  ]
}

Response

A successful response includes the following:

Response Example

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

2. Save the restrictedDataToken value (the RDT) to provide it in the getReportDocument operation.

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 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. Refer to Authorizing Selling Partner API applications for more information.

• Approval for the following roles:

  • 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, refer to Registering as a developer and update your developer profile.

Step 1. Get an RDT

Call the createRestrictedDataToken operation to get an RDT.

1. Call the createRestrictedDataToken operation, passing the following parameters:

Body parameter:

Request example

POST https://sellingpartnerapi-na.amazon.com/tokens/2021-03-01/restrictedDataToken
{
  "restrictedResources": [
    {
      "method": "GET",
      "path": "/orders/v0/orders",
      "dataElements": ["buyerInfo", "shippingAddress"]
    }
  ]
}

Response

A successful response includes the following:

Response example

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

2. 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 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. Refer to Authorizing Selling Partner API applications for more information.

• Approval for the following roles:

  • Tax remittance
  • Tax invoicing

  Depending on your use case, you might need approval for only one of these roles. To learn more about roles and request access, refer to Registering as a developer 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 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 operation, passing the following parameter:

Body parameter:

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"]
    }
  ]
}

Response

A successful response includes the following:

Response example

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

2. 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 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 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, refer to Terminology.

Prerequisites

To complete this tutorial, you will need:

• Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API applications 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, refer to Registering your application. 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:

• Register as a developer, requesting approval for the roles that are required to access buyer information and 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.

  For more information about roles, refer to Roles in the Selling Partner API.

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 operation, passing the following parameters:

Body parameters:

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"
}

Response

A successful response includes the following:

Response example

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

2. 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 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 operation, passing the following parameters:

Body parameters:

Request example

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

Response

A successful response includes the following:

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": "[email protected]",
      "BuyerName": "John Doe",
      "BuyerTaxInfo": {
        "CompanyLegalName": "A Company Name"
      },
      "PurchaseOrderNumber": "1234567890123"
    }
  }
}

2. 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. Refer to Authorizing Selling Partner API applications 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, refer to Registering as a developer 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, refer to Terminology.

1. Call the createRestrictedDataToken operation, passing the following parameter:

Body parameters:

Request example

POST https://sellingpartnerapi-na.amazon.com/tokens/2021-03-01/restrictedDataToken
{
  "restrictedResources": [
    {
      "method": "GET",
      "path": "/mfn/v0/shipments/{shipmentId}"
    }
  ]
}

Response

A successful response includes the following:

Response example

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

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

   For definitions, refer to Terminology.

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

Call the getShipment 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 this step 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 an SDK for the Tokens API

You can find steps describing how to generate an SDK for the Tokens API in Java or C# at the following:

• Generate a Java SDK with LWA token exchange
• Generate a C# SDK with LWA token generation and authentication

If you're using the Java SDK, you should also:

1. Run mvn package inside the generated SDK folder.

2. 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, refer to Terminology.

   • RestrictedDataTokenWorkflow.java. For getting an RDT and using it to authorize your own application to call one or more restricted operations.
   • DelegatedRestrictedDataTokenWorkflowForDelegator.java. For getting an RDT that delegates authorization to call restricted operations to a delegatee application.
   • DelegatedRestrictedDataTokenWorkflowForDelegatee.java. For a delegatee application that receives an RDT from a delegator application and uses it for authorization to call restricted operations.

🚧

Use the latest version of the Tokens API

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