Get orders with filtering criteria

Learn how to use the Orders API to get orders with filtering criteria.

Learn how to use the Orders API to get orders 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. NextToken, when provided, overrides other criteria to retrieve orders.

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

Prerequisites

To complete this tutorial, you need:

Authorization from the selling partner for whom you are making calls. For more information, refer to Authorizing Selling Partner API applications.
The Inventory and Order Tracking role assigned to 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

Get orders

Call the getOrders operation.

`getOrders` request example

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

`getOrders` 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 a list of possible extended fields and information on when shipping addresses contain extended fields, refer to the Orders API v0 reference.

Updated about 13 hours ago

🚧Warning

Prerequisites

Get orders

getOrders request example

getOrders response examples

🚧
Warning

`getOrders` request example

`getOrders` response examples