Amazon Services
Amazon Marketplace Web Service (Amazon MWS) Documentation
Amazon MWS Documentation

What you should know about the Orders API section

With the Orders API section of Amazon Marketplace Web Service (Amazon MWS), you can build simple applications that retrieve only the order information that you need. This enables you to develop fast, flexible, custom applications in areas like order synchronization, order research, and demand-based decision support tools.

The following operations are included in the Orders API section:

Operation Description Availability
ListOrders Returns orders created or updated during a time frame that you specify. All marketplaces.
ListOrdersByNextToken Returns the next page of orders using the NextToken parameter. All marketplaces.
GetOrder Returns orders based on the AmazonOrderId values that you specify. All marketplaces.
ListOrderItems Returns order items based on the AmazonOrderId that you specify. All marketplaces.
ListOrderItemsByNextToken Returns the next page of order items using the NextToken parameter. All marketplaces.
GetServiceStatus Returns the operational status of the Orders API section. All marketplaces.

You can retrieve order item information by first using the ListOrders operation to find orders created or updated during a time frame that you specify. An AmazonOrderId is included with each order that is returned. You can then use these AmazonOrderId values with the ListOrderItems operation to get detailed order item information for each order.

To determine the URL to use when sending requests to the Orders API section, add "/Orders/2013-09-01" to the endpoint for your marketplace. For example, if your marketplace is US, the URL would be https://mws.amazonservices.com/Orders/2013-09-01

When to use the Orders API section

The Orders API section is optimized for data synchronization, retrieving order updates in real-time, and order research. For bulk order data reporting, you should create order reports with the Reports API section. For more information about the Reports API section, see the Reports API section documentation.

Terminology

The following table defines terminology for this API section:

Term Definition
Order item An item and a quantity. For example, if a customer buys three copies of a particular book, the order contains one order item with a quantity of three. If one of the copies is to be gift wrapped, the order now contains the following two order items:
  • Gift wrapped book, quantity of one
  • Non-gift wrapped book, quantity of two
Order The following are both considered orders:
  • A collection of order items sold on Amazon with identical values for the following attributes:
    • Shipping address
    • Shipping speed
    • Seller
  • A Multi-Channel Fulfillment order (an order not sold on Amazon's retail website but fulfilled using your Fulfillment by Amazon inventory).
Pre-order An order that contains items with a manufacturer's release date that is in the future. Note that pre-orders are available only in Japan.
Standard order An order that contains items with available inventory.

Note for Fulfillment by Amazon (FBA) sellers who use Multi-Channel Fulfillment: If you submit a removal order and do not include ShippingAddress, the Orders API section will not return ShippingAddress for that order. For more information about Multi-Channel Fulfillment, see the Help pages for the Amazon Seller Central website in your marketplace.

Throttling

The following list explains Amazon MWS throttling concepts:

Request quota
The number of requests that you can submit at one time without throttling. The request quota decreases with every request you submit. The request quota increases at the restore rate.
Restore rate
The rate at which your request quota increases over time, up to the maximum request quota.
Maximum request quota
The maximum size that the request quota can reach.

User scenarios

The following scenarios are supported by the Orders API section:
  • Data synchronization:
    • Synchronize Amazon order data with order data in your local ordering system
    • Get order status data on your Amazon sales so you can fulfill your orders using your own fulfillment system
    • Migrate your historical order data to a third-party integrator solution
  • Order research and customer service:
    • Get order details for researching issues and answering customer questions
You can perform the following business analytics with the synchronization data that the Orders API section makes available:
  • Support for FBA replenishment and removal decisions:
    • Find SKUs with high or low sales volumes
    • Monitor sales trends by SKU
  • Support for sales channel and fulfillment channel decisions:
    • Find SKU sales trends by sales channel and by fulfillment channel
    • Monitor sales trends by SKU
  • Issue monitoring:
    • Find SKUs that have been in a given state for too long
    • Find unexpected changes in sales trends by SKU