Amazon Orders API Connector

The primary purpose of the Order API is to support order synchronization, order research, and demand-based decision support tools. Data is processed in near real-time, which is every hour.

There are two primary data feeds associated with the Orders API;

The connector leverages the Amazon Order API, which is different than Reports. This API provides a "live" transaction feed of activity each hour, as it occurs on Amazon. There is no historical data for live Order API feeds. For more details on the types of data returned by the API, see Amazon's Order API docs.

While sales data from the Orders API is similar to Sales reports, reports are aggregated based on settled data while Orders API is "live" transactional data.

Transactional Data

Order API transactional data reflects activity as it happens on Amazon. As a result, there is no historical data, and it may have more variability. For example, an Order transaction occurred at 11:15 AM on June 1st. Two hours later, at 1:30 PM on June 1st, the same Order changed the status to "Cancelled." This means you will have two order transactions, one at 11:15 AM and another at 1:30 PM. A Sales Report will be generated on June 2nd, with the Order having one row listed as "Cancelled."

For more information on Sales Reports for orders, see Amazon Sales Connector.

When an order is Pending (the Order has been placed, but payment has not been authorized), per Amazon, the order items will not contain information about pricing, taxes, shipping charges, gift status, or promotions for an order.

After an order leaves the Pending state (when payment has been authorized) and enters the Unshipped, Partially Shipped, or Shipped state, the Order Items will return information about pricing, taxes, shipping charges, gift status, and promotions for the order items in an order.

The Order API uses "Dynamic" API limits. This means API capacity will vary seller by seller. Per Amazon;

This means the same seller with an account in North America may have a different capacity than their European account. There is no specific documentation on what limits a Seller may have; as such, we must manage carefully how many requests are made to avoid rate limits.

The timing of data will vary due to dynamic limits by seller, region, and marketplace. If the capacity does not align with the need at any point, Amazon suggests using a "back-off" and "retry" pattern, which Openbridge does. In the event of API errors, unresponsiveness, or throttles, Openbridge will queue a request for a later retry.

Following the exponential backoff and retry pattern detailed by Amazon can and will introduce "delays" of hours or days in having data arrive. This results from having to wait for more API capacity to make requests without further incident.

However, persistent, continued capacity issues will impact data delivery, especially when requesting historical data.

Due to how the API limits are structured, Order Items (sp_order_items) are impacted more than sp_orders. Why? The API returns Orders in batches of 100. As a result, an API request can efficiently return many orders without hitting dynamic limits.

However, Order items must be requested by Order ID, requiring individual API requests to return items. For example, if we requested Orders and 100 Orders were returned, this would require at least 100 API calls to return Order Items for each Order ID. As a result, 1 API call for Orders requires at least 100 API calls for Order Items. The API capacity required to get Order Items is exponentially more than Orders alone. This is why limits can be easily hit as the volume of Orders increases.

Due to rate limits, requests for Order Items are prioritized by Order Status to avoid being throttled by the API.

Using our example of 100 orders, those with an order status Shipped are prioritized. This means API calls for Order items are priorities where status = Shipped. For other order statuses, they are requested as capacity allows.

Why is Shipped prioritized? A shipped order reflects an order that results in a recognizable financial event. All other statuses reflect transitory states. For example, a Seller will not get paid for an order that is Pending , and this state will often change to Shipped or Canceled.

For Order IDs with statuses like Pending, the data is requested as capacity is available to successfully make those requests. As a result, it is possible for other statuses, like Pending, to be in an API backoff and retry queue for 12 or 24 hours, waiting for adequate API capacity.

If the retry/backoff pattern is not sufficient, given a Seller's dynamic API limit, Amazon suggests leveraging Order reports. Amazon says that in the event of consistent limit issues, a seller should;

"Use bulk get endpoints such as reports/2020-09-04/reports, which lets a Seller get data in bulk in a single API request".

The primary alternative offered by the SP-API to the Order API is aggregated Order data via Order Tracking Reports. Order tracking reports are available via the Openbridge Amazon Sales Connector for reports.

Amazon stated it is unlikely to grant requests to change dynamic limits. However, if a request was to be made, the seller, not the app developer (Openbridge), must make the petition.