Get orders with filtering criteria

Learn how to use the Orders API to retrieve a list of orders that match the criteria you specify.

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.
• At least one of the following roles assigned to your developer profile and selected in the app registration page:
  • The Amazon Fulfillment role.
  • The Buyer Communication role.
  • The Buyer Solicitation role.
  • The Finance and Accounting role.
  • The Inventory and Order Tracking role.
  • The Pricing role.
  • The Product Listing role.
  • The Professional Services (Restricted) role.
  • The Selling Partner Insights role.
  • The Direct to Consumer Shipping (Restricted) role.
  • The Tax Invoicing (Restricted) role.
  • The Tax Remittance (Restricted) role.

To access Personally Identifiable Information (PII), 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.

You do not need a Restricted Data Token to access PII with the Orders API v2026-01-01.

Search for orders with basic information

Call the searchOrders operation. If you do not include includedData, the response will include only basic information about the orders, such as orderId, createdTime, salesChannel, programs, orderItemId, product, and other relevant details.

Search for orders with custom data sets

Call the searchOrders operation and include the includedData parameter with the information you want the response to include.

📘

Note

The searchOrders operation uses pagination when there are too many results to include in a single response. When this happens, the response includes a pagination object, which includes a nextToken value. To get the next page of results, make the same API call and use the nextToken value as the value for the paginationToken query parameter. All values in the subsequent request must remain the same as in the first request, with the exception of maxResultsPerPage and includedData, which may be modified between requests.

The nextToken returned by searchOrders expires after 24 hours.