Orders API v0 Use Case Guide

API Version: v0

What is the Orders API?

Use the Orders API to programmatically retrieve and submit order information. This API is designed to help Selling Partners develop fast and flexible custom applications that facilitate order synchronization, order research, and demand-based decision support tools.

📘

Note

Orders more than two years old will not show in the API response, except for the SG, JP, and AU marketplaces, which support orders from 2016 and after.

For information about authentication and authorization, refer to Authorizing Selling Partner API Applications. For information about regulated orders, refer to the Regulated Orders guide.

Key features

• Retrieve orders information with filtering criteria: The getOrders operation of the Orders API returns orders created or updated during the time frame or other filtering criteria indicated by the specified parameters. If NextToken is present, it is used to retrieve the orders instead of other criteria.
• Retrieve specified order information: The getOrder operation of the Orders API returns order information that you specify.
• Retrieve order item information for the specified order: The getOrderItems operation of the Orders API returns detailed order item information for the order that you specify. If NextToken is provided, it is used to retrieve the next page of order items.
• Confirm shipment for the specified order: The confirmShipment operation of the Orders API confirms the shipment status for a specified order. It can also be used to edit shipment details of orders that have been shipped.

Tutorial 1: Retrieve orders information with filtering criteria

The getOrders operation of the Orders API returns orders created or updated during the time frame or other filtering criteria indicated by the specified parameters. If NextToken is present, that will be used to retrieve the orders instead of other criteria.

🚧

Warning

The getOrders operation has a systematic delay in data retrieval. Most updated orders data will be available 2 minutes after an order is created or last updated. To ensure that you retrieve the latest orders data, call the operation 2 minutes after the order is created or updated.

Prerequisites

To successfully complete this tutorial, you must have:

• Authorization from the selling partner for whom you are making calls. Refer to the Authorizing Selling Partner API applications for more information.
• Approval for the Inventory and Order Tracking role in your developer profile.
• The Inventory and Order Tracking role selected in the App registration page for your application.

To access buyer and shipping address information, you must:

• Have approval for the following roles:

  • Direct-to-Consumer Delivery (Restricted) role is required to access shipping address information.
  • The Tax Remittance (Restricted) role is required to access buyer information.
  • The Tax Invoicing (Restricted) role is required to access buyer information.

• Use a Restricted Data Token (RDT)

  • Follow the Tutorial: Get authorization to access PII for bulk orders to get an RDT that provides authorization to access Personally Identifiable Information (PII) for bulk orders.
  • Use any of the following values in the dataElements parameter in the createRestrictedDataToken operation to access the getOrders operation:
    • buyerInfo
    • shippingAddress
    • buyerTaxInformation

getOrders Request

Call the getOrders operation.

Query parameters

Request example

GET https://sellingpartnerapi-eu.amazon.com/orders/v0/orders?
    MarketplaceIds=ATVPDKIKX0DER
    &CreatedAfter=2020-10-10
    &MaxResultPerPage=2

Response

A successful response includes the following:

Response examples

The following is an example of a general response from the getOrders operation.

{
  "payload": {
    "NextToken": "2YgYW55IGNhcm5hbCBwbGVhc3VyZS4",
    "Orders": [
      {
        "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",
          "GiftCertificate"
        ],
        "MarketplaceId": "ATVPDKIKX0DER",
        "ShipmentServiceLevelCategory": "Standard",
        "OrderType": "StandardOrder",
        "EarliestShipDate": "2017-01-20T19:51:16Z",
        "LatestShipDate": "2017-01-25T19:49:35Z",
        "IsBusinessOrder": false,
        "IsPrime": false,
        "IsAccessPointOrder": false,
        "IsGlobalExpressEnabled": false,
        "IsPremiumOrder": false,
        "IsSoldByAB": false,
        "IsIBA": 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"
        }
      }
    ]
  }
}

When an order is shipped to a Brazil address, you might also receive additional address fields, (for example, StreetName, StreetNumber, Complement, and Neighborhood) as shown in the following example.

{
      "ShippingAddress": {
        "Name": "Brazil address",
        "AddressLine1": "Street 9 450",
        "AddressLine2": "Suite 30 Central",
        "ExtendedFields": {
          "StreetName": "Street 9",
          "StreetNumber": "450",
          "Complement": "Suite 30",
          "Neighborhood": "Central"
        },
        "City": "Rio de Janeiro",
        "StateOrRegion": "RJ",
        "PostalCode": "48817",
        "CountryCode": "BR"
      } 
}

For more information on when shipping addresses contain extended fields, refer to the Order schema in the Orders API v0 reference.

For a list of possible extended fields, refer to AddressExtendedFields in the Orders API v0 reference.

Tutorial 2: Retrieve order information

The tutorial shows you how to use the getOrder operation of the Orders API to retrieve order information that you specify.

Prerequisites

To successfully complete this tutorial, you must have:

• Authorization from the selling partner for whom you are making calls. Refer to the Authorizing Selling Partner API applications for more information.
• Approval for the Inventory and Order Tracking role in your developer profile.
• The Inventory and Order Tracking role selected in the App registration page for your application.

To access buyer and shipping address information, you must:

• Have approval for the following roles:

  • Direct-to-Consumer Delivery (Restricted) role is required to access shipping address information.
  • The Tax Remittance (Restricted) role is required to access buyer information.
  • The Tax Invoicing (Restricted) role is required to access buyer information.

• Use a Restricted Data Token (RDT):

  • Follow the Tokens API Use Case Guide to get an RDT that provides authorization to access Personally Identifiable Information (PII) for an operation.
  • Use any of the following values in the dataElements parameter in the createRestrictedDataToken operation to access the getOrder operation:
    • buyerInfo
    • shippingAddress
    • buyerTaxInformation

Request

Request example

GET https://sellingpartnerapi-eu.amazon.com/orders/v0/orders/205-1725759-9209952/

Response

A successful response includes the following:

Refer to Order in the API reference for details about the possible objects and properties in an order.

Response example

{
  "payload": {
    "BuyerInfo": {},
    "AmazonOrderId": "026-1520163-6049104",
    "EarliestShipDate": "2022-03-10T00:00:00Z",
    "SalesChannel": "Amazon.co.uk",
    "AutomatedShippingSettings": {
      "HasAutomatedShippingSettings": false
    },
    "OrderStatus": "Canceled",
    "NumberOfItemsShipped": 0,
    "OrderType": "StandardOrder",
    "IsPremiumOrder": false,
    "IsPrime": false,
    "FulfillmentChannel": "MFN",
    "NumberOfItemsUnshipped": 0,
    "HasRegulatedItems": true,
    "IsReplacementOrder": false,
    "IsSoldByAB": false,
    "LatestShipDate": "2022-03-10T23:59:59Z",
    "ShipServiceLevel": "Std UK Dom_1",
    "IsISPU": false,
    "MarketplaceId": "A1F83G8C2ARO7P",
    "PurchaseDate": "2022-03-09T22:03:02Z",
    "IsAccessPointOrder": false,
    "IsBusinessOrder": false,
    "OrderTotal": {
      "CurrencyCode": "GBP",
      "Amount": "20.00"
    },
    "PaymentMethodDetails": [
      "Standard"
    ],
    "IsGlobalExpressEnabled": false,
    "LastUpdateDate": "2022-03-14T22:05:14Z",
    "ShipmentServiceLevelCategory": "Standard"
  }
}

Tutorial 3: Retrieve detailed order item information

The tutorial shows you how to use the getOrderItems operation of the Orders API to retrieve order information that you specify.

Prerequisites

To successfully complete this tutorial, you must have:

• Authorization from the selling partner for whom you are making calls. Refer to the Authorizing Selling Partner API applications for more information.
• Approval for the Inventory and Order Tracking role in your developer profile.
• The Inventory and Order Tracking role selected in the App registration page for your application.

To access buyer and shipping address information, you must:

• Have approval for the following roles:

  • Direct-to-Consumer Delivery (Restricted) role is required to access shipping address information.
  • The Tax Remittance (Restricted) role is required to access buyer information.
  • The Tax Invoicing (Restricted) role is required to access buyer information.

• Use a Restricted Data Token (RDT)

  • Follow the Tutorial: Get authorization to access PII for the order items in an order to get an RDT that provides authorization to access Personally Identifiable Information (PII) for the order items in an order.
  • Use buyerInfo as a value in the dataElements parameter in the createRestrictedDataToken operation to access the getOrderItems operation.

Request

Request example

GET https://sellingpartnerapi-na.amazon.com/orders/v0/orders/902-9855239-8990202/orderItems

Response

A successful response includes the following:

Response example

{
  "payload": {
      "OrderItems": [
          {
              "TaxCollection": {
                  "Model": "MarketplaceFacilitator",
                  "ResponsibleParty": "Amazon Services, Inc."
              },
              "ProductInfo": {
                  "NumberOfItems": "1"
              },
              "BuyerInfo": {},
              "ItemTax": {
                  "CurrencyCode": "USD",
                  "Amount": "1.13"
              },
              "QuantityShipped": 1,
              "BuyerRequestedCancel": {
                  "IsBuyerRequestedCancel": "false",
                  "BuyerCancelReason": ""
              },
              "ItemPrice": {
                  "CurrencyCode": "USD",
                  "Amount": "11.00"
              },
              "ASIN": "B004RKQM8I",
              "SellerSKU": "AN-M9GI-4QE5",
              "Title": "Sony MDR-ZX100 ZX Series Headphones (White)",
              "IsGift": "false",
              "ConditionSubtypeId": "Acceptable",
              "IsTransparency": false,
              "QuantityOrdered": 1,
              "PromotionDiscountTax": {
                  "CurrencyCode": "USD",
                  "Amount": "0.00"
              },
              "AmazonPrograms": {
                  "Programs": ["SUBSCRIBE_AND_SAVE"]
              },
              "ConditionId": "Used",
              "PromotionDiscount": {
                  "CurrencyCode": "USD",
                  "Amount": "0.00"
              },
              "OrderItemId": "43345934312798"
          }
      ],
      "AmazonOrderId": "902-0300094-5705429"
  }
}

Tutorial 4: Confirm a shipment

This tutorial shows you how to confirm a shipment with the confirmShipment operation after you receive a notification that your order is ready to be fulfilled. You will not need to confirm the shipment if you purchase a shipping label through the Shipping API or buy-shipping UI. The confirmShipment operation supports all use cases that were supported in the Order Fulfillment Feeds, including supporting multiple tracking IDs per order. To submit multiple package tracking IDs, you will need to send multiple requests with the same order ID but different package reference IDs.

Example:

The package reference ID supports any positive numerical value and is meant for the purpose of editing a shipment after you have confirmed a shipment. You can submit any numerical value as packageReferenceID and we will store the data. If you need to make an edit to the shipment, submit another confirmShipment operation with the same packageReferenceID. The other shipment details will be edited upon successful submission. If you do not put any ID when you submit, Amazon will automatically assign a packageReferenceID.

Prerequisites

To successfully complete this tutorial, you must have:

• Authorization from the selling partner for whom you are making calls. Refer to the Authorizing Selling Partner API applications for more information.
• Approval for the Inventory and Order Tracking role in your developer profile.
• The Inventory and Order Tracking role selected in the App registration page for your application.

If you have been approved for the Direct-to-Consumer Delivery (Restricted) role, you will have access to the confirmShipmentoperation.

Step 1. Confirm a shipment for one order

Call the confirmShipment operation, passing the following parameters:

Path parameters

Body parameters

Request example

POST https://sellingpartnerapi-eu.amazon.com/orders/v0/orders/205-1725759-9209952/shipmentConfirmation
{
  "marketplaceId": "ATVPDKIKX0DER",
  "codCollectionMethod": "",
  "packageDetail": {
    "packageReferenceId": "123",
    "carrierCode": "UPS",
    "carrierName": "UPS",
    "shippingMethod": "SHIPPING",
    "trackingNumber": "1Z86V8030385598957",
    "shipDate": "2022-11-30T16:15:30Z",
    "shipFromSupplySourceId": "057d3fcc-b750-419f-bbcd-4d340c60c430",
    "orderItems": [
      {
        "orderItemId": "60696125413094",
        "quantity": 1
      }
    ]
  }
}

Response

Response properties:

For error status codes, descriptions and schemas, refer to Confirm Shipment Error Response.

🌟

Tip

To confirm multiple orders, use the Feeds API v2021-06-30 and pass the POST_ORDER_FULFILLMENT_DATA feed type. For more information, refer to Confirm multiple orders through the Order Fulfillment feed.

Step 2. Edit shipping information for one order

After Step 1, a package is created for the order. You can edit the shipping information like Ship date, Carrier, Shipping service (or Ship method), Tracking ID (supplied by the carrier) by calling the confirmShipment operation again.

Parameters that need to be consistent

To ensure that you are editing the same shipment, do not change the following parameters.

Request example

POST https://sellingpartnerapi-eu.amazon.com/orders/v0/orders/205-1725759-9209952/shipmentConfirmation
{
  "marketplaceId": "ATVPDKIKX0DER",
  "codCollectionMethod": "",
  "packageDetail": {
    "packageReferenceId": "123",
    "carrierCode": "USPS",
    "carrierName": "USPS",
    "shippingMethod": "SHIPPING",
    "trackingNumber": "1Z86V8030385598957",
    "shipDate": "2022-11-30T20:15:30Z",
    "shipFromSupplySourceId": "057d3fcc-b750-419f-bbcd-4d340c60c430",
    "orderItems": [
      {
        "orderItemId": "60696125413094",
        "quantity": 1
      }
    ]
  }
}

Response

Response properties:

For error status codes, descriptions and schemas, refer to Error responses and schemas.