All Collections
Data Sources
Amazon
Amazon Orders API Connector
Amazon Orders API Connector
Openbridge Support avatar
Written by Openbridge Support
Updated over a week ago

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;

  • Orders (sp_orders)

  • Order Items (sp_order_items)

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.

Order API vs. Sales (Order Tracking) Reports

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.

Order Status

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.

Important: Order API Limits

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

"A dynamic usage plan is one that is automatically adjusted to each selling partner based on the current and historical business needs of that business. The default rate limits published in the API Reference documentation can be used to plan your application. However, because the purpose of dynamic usage plans is to right-size those limits over time, the rates may change. A variety of selling partner business metrics influence rate adjustments. These are business metrics only and do not include a historical number of API requests. Rates will not dynamically increase because an application sends API requests more frequently. If you find that dynamic rates are insufficient for your use case, petition for an override by opening a support ticket with our developer support team."

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.

API Limit backoff, queues, and retries

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.

Primary Rate Limits Impact: Order items

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.

Order Item Request Priorities

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.

  • Shipped (All items in the order have been shipped.) (Prioritized)

  • Unshipped (Payment has been authorized, and the order is ready for shipment, but no items in the order have been shipped.)

  • PartiallyShipped (One or more, but not all, items in the order have been shipped.)

  • InvoiceUnconfirmed (All items in the order have been shipped. The seller has not yet given confirmation to Amazon that the invoice has been shipped to the buyer.)

  • Canceled (The order has been canceled.)

  • Unfulfillable (The order cannot be fulfilled. This state applies only to Multi-Channel Fulfillment orders.)

  • PendingAvailability (This status is available for pre-order only. The order has been placed, payment has not been authorized, and the item's release date is in the future.)

  • Pending (The order has been placed, but payment has not been authorized.)

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.


Alternatives Suggested By Amazon

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.

Requesting Limit Increases

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.

Did this answer your question?