[Deprecated Content]

[Tong8s]

Orders API Guide: How to get latest orders update in an efficient way content is now moved here.

We understand keeping your orders data up to date is very important to your business model, Up-to-date orders data can help SP-API developers build more reliable and efficient applications for sellers. This hot topic will discuss how we can use our APIs to efficiently get latest order updates.

Authored by: @Tong8s Solutions Architect, Selling Partner Developer Services

Up-to-date orders data can help you provide your sellers with:

• 🚚 Accurate fulfillment: Up-to-date order information ensures that sellers can process and ship orders correctly and on time.
• 📦 Inventory management: Timely order data helps sellers manage their inventory more effectively, preventing overselling or stockouts.
• 💰 Financial tracking: Accurate order data is vital for proper accounting, revenue recognition, and financial reporting. It allows sellers to reconcile their sales, fees, and payments with Amazon.
• 📈 Business insights: Current order data allows sellers to analyze sales trends, customer behavior, and product performance, informing business decisions and strategies.

Do you know that there are three ways to get orders data update?

• GetOrders + GetOrderItems API Call
• ORDER_CHANGE notification
• Orders Report

Each of these ways will have its benefits and fits into different business scenarios:

GetOrders + GetOrderItems API Call

// Get orders
GetOrdersResponse orderList = ordersApi.getOrders(lastUpdatedAfter: "2025-01-01T00:20:15Z");
// For each orderID, get Order Item asynchronously
GetOrderItemsResponse orderItems = ordersApi.getOrderItems(order.getOrderId(), null);

Applied Scenario

• Seller's maximum daily order amount is less than 20K.
• No peak shopping event such as prime day

By using these two APIs, you can get complete order info, including fulfillment info, shipping info, payment info etc.

Through getOrders API call, you’ll be able to get all the updated orders from the time you specified in lastUpdatedAfter until 2 minutes ago — Keep in mind that the orders data will be available after two minutes when your order is created or last updated.

For each "orderId", you will need to call getOrderItems to get item details, including orderItem ID, item price, shipping info etc. These API operations are synchronous and instant, you can expect the response to be returned in milliseconds. To find more information about how to use these two APIs, please see our use case guide.

One thing to be noticed is that these APIs are rate restricted:

• getOrders has a default rate limit value of 1/min with a burst value of 20, and getOrderItems has a default rate limit value of 0.5/s with a burst value of 30.
• We are conducting dynamic usage plan (DUP) on these API operations, which means your usage plan will be automatically adjusted based on your current and historical business data.
• Behind the scene, we have multiple tiers, the rate limit you can see in our developer doc is the lowest usage plan tier we provide. So your rate limit can increase if we believe you need more rate limit after evaluation.

We have a guide on how to optimize your rate limits and your application workloads, in this guidance, you can find:

• How to set a rate limiter to smooth your calling pattern.
• How to monitor API activity against your rate limit using x-amz-rate-limit response header .
• How to introduce retry techniques to handle throttling errors.

this is especially useful when dealing with DUP APIs.

ORDER_CHANGE notification

ObjectMapper mapper = new ObjectMapper();

//SPAPINotification is a java class defines SQS message body data types 
SPAPINotification notification = mapper.readValue(sqsMessage.getBody());

//Only process the notification if it is of type 'ORDER_CHANGE'
if ("ORDER_CHANGE".equals(notification.getNotificationType())) {
    processNotificationAndExtractOrderData(notification.getPayload());
}

Applied Scenario

• Seller's maximum daily order amount is more than 20K
• Or there is a peak shopping event such as Prime Day, which makes more sense to use event-driven

ORDER_CHANGE notification allows you to adopt a push model for orders update, which means you don’t need to worry about throttling issues. Whenever the key attributes is changed for an order such as order status change or buyer requested change (such as cancel order), seller can receive a notification with key information about the updated order and order items.

There some key things you need to be aware when using ORDER_CHANGE notification:

• The ORDER_CHANGE SQS message does NOT contain full information about orders and order items, for example, it does not contain order item titles, price and payment information. To fill this gap, what you can do is after receiving the notification, call getOrder for that specific order and then call getOrderItems to acquire more information, so potentially you will still be bounded by orders API rate limit if you want to get complete information.
• You must onboard AWS SQS service in order to receive ORDER_CHANGE notification, you need to create one queue for each seller. So extra costs are needed, for SQS cost details, here we have a youtube video guiding you how to calculate costs for SP-API notifications. you can also take a look at our SQS pricing page.
• Delay of notification is usually trivial (in seconds), however, on prime day or other selling event, the delay can be up to 2 minutes.

Orders Report

//Take US marketplace and "GET_FLAT_FILE_ALL_ORDERS_DATA_BY_LAST_UPDATE_GENERAL" as an example.
CreateReportSpecification body = new CreateReportSpecification()
         .reportType("GET_FLAT_FILE_ALL_ORDERS_DATA_BY_LAST_UPDATE_GENERAL")
         .marketplaceIds("ATVPDKIKX0DER")
         .dataStartTime("2025-01-01T00:00:00Z")
         .dataEndTime("2025-01-30T23:59:59Z");
CreateReportResponse createReportResponse = reportsApi.createReport(body);

//getReportDocumentId, you may need to fetch iteratively to wait till the report is ready.
Report report = reportApi.getReport(createReportResponse.getReportId());

ReportDocument reportDocument = reportApi.getReportDocument(report.getReportDocumentId());

String Url = reportDocument.getUrl(); //This is the Url where you can download the report.

Applied Scenario

• Use Order reports if you do NOT require high time sensitivity on your orders data, for example, You use orders data to do weekly/monthly trend analysis.
• Use Orders reports data as a supplement/guardrail of above two means to avoid missing orders.

There are two report types you can consider, the difference between these two is the file format.

GET_FLAT_FILE_ALL_ORDERS_DATA_BY_LAST_UPDATE_GENERAL
GET_XML_ALL_ORDERS_DATA_BY_LAST_UPDATE_GENERAL

These report contains complete information about orders and corresponding order items. There are also optional columns which you can let your sellers to configure through seller central: Orders → Order Reports → Add or remove order report columns

As you can see in the code snippet, there are several API calls you need to perform, createReport → getReport → getReportDocument, usually after createReport, you will need to wait up to a few minutes based on the updated orders data size. So the latency is larger than the above two ways.

Combine and Conquer

We understand that accurate orders update information is important to your sellers, especially if you are serving big sellers who can have hundreds to thousands new orders every minute. We recommend you combine the above ways to acquire order updates for such sellers:

The above diagram is just one way of combining the orders API, ORDER_CHANGE notification and the report, you can tailor your combination strategy based on your use case. The tenet to follow is with such combination, you can get latest order updates with complete order info in low latency and high accuracy, meanwhile you don’t want to be bounded by the orders API rate limit.

Lastly, we saw your pain points of using Orders related SP-API operations, Our development teams are actively working on optimizing current Orders API to make it more accurate, efficient and user friendly.

Let us know what do you think! 👇 React or reply down below to share your feedback. Happy shopping!

• ❤️ Like what you see?

• 👍 Excited to try it out?

• 🎉 Want to see more of this?

Keywords: SellingPartnerAPI, AmazonSPAPI, Amazon, Orders

[tspicer]

@Tong8s this is a great starting point guide. One question I have is related to order items. We typically see rate limits relative to this endpoint. Since we need to call get orders to get the list of order IDs, each of those order IDs is then used to get the corresponding items. In in an hour there were 1000 order ids returned between 2 PM to 3 PM, attempting get all the corresponding items has a higher chance of getting limited. This leaves a use case where I have the order ID, but possibility a list partial order items for those IDs. Attempting to retry for items can lead to the thundering herd dynamics, even with exponential backoff.

[Tong8s]

Hi @tspicer,

If you have roughly 1000 order updates per hour, that means your daily order amount is greater than 20K or there is a peak shopping event, we recommend you using the ORDER_CHANGE notification, which can give your both order IDs and order items information. By merely using getOrders + getOrderItems calls, it's true that you are likely to be throttled. Besides retries, One work around is to add a rate limiter.The rate limiter ensures a consistent calling pattern over time, to mitigate traffic peaks and promote uniform API usage.

[kevinvenclovas]

@Tong8s, thank you for this guide!

I am currently using the GetOrders API to retrieve orders from our EU Amazon marketplaces. However, this API lacks tax information and buyer details, which are essential for issuing EU-compliant invoices. To obtain this missing data, I additionally use the GET_FLAT_FILE_ORDER_REPORT_DATA_INVOICING report.

Now, I am facing the issue that this report only returns MFN orders. Since we also use FBA, we are missing the complete buyer address and tax information for these orders.

Do you have a guide on how we can retrieve tax information and buyer data for all types of orders? The challenge here is that we need this data as soon as the order is placed, as our invoices must be recorded in our accounting system on the same day whenever possible.

Maybe you can drop by here for some more information: amzn/selling-partner-api-models#4668

[jawheral]

Hi @kevinvenclovas,

Please see my reply on invoicing here: amzn/selling-partner-api-models#4668

Thanks,
Jawher
Selling Partner Developer Services

[weilinggu]

Hi all,

As an effort to include polls in our Hot Topics, we have moved this content to #104. If you would like to retain your comment, please feel free to post there again.

Thanks
Weiling
Amazon Selling Partner Services