Incorrect restore rates for Orders API

[YuriiHerasymchuk]

Selling Partner API for Orders

I spent a lot of time testing restore rates for Orders API and I want to share what I found out.

In the documentation, it says the restore rate is 0.0055 which means one request every 180 seconds. Very soon I realized that this is not the case, it would take forever to load accounts with tens of thousands of orders.

I tested restore rates with getOrders (requesting 50 orders at a time) on 3 different accounts: 150, 500 and 12.000 orders/month.

Conclusions after testing:

1. The size of the account doesn’t affect the restore rate.

2. If you don’t want to have throttled requests:

   You need to have 5 seconds delay between each request.

   • ~5 seconds restoration for 1 request. Real restore rate is ~0.2
   • ~100 seconds to restore 20 requests (Burst amount)

3. If you don’t care about extra traffic from throttled requests:

   • You can spam requests every second getting 1 successful response every ~2.39 seconds.
   • It’s not consistent, sometimes it takes 10 throttled requests in a row to restore 1-2 requests and sometimes it takes one second to restore 3-7 requests.

4. Amount of orders requested doesn’t affect restore rate

5. Restore rates from different operations (getOrders, getOrder, getOrderBuyerInfo, etc) are different. This means you can run them in parallel and they will not affect each other.

By default, this library waits 180 seconds for Orders API when throttled and Amazon never returns the header x-amzn-ratelimit-limit it means that on every throttled request it will wait 180 seconds.

I will create a pull request with the “correct” restore rate. If someone wants more testing data - let me know, I tried to keep the post as concise as possible.

[YuriiHerasymchuk]

I would appreciate someone else testing it on other Amazon accounts as well to double-check. But for now, I created a pull request with restore rates that I calculated after testing on different accounts.

[amz-tools]

Hi @YuriiHerasymchuk,

thanks for sharing your test results here. We have checked this with some accounts of different order amounts as well (ranging from a few per month to accounts with high 5 figures per month).

What we can confirm is basically your points 1, 3, 4 and 5 and we also never received the x-amzn-ratelimit-limit for orders operations.

However what we can't really confirm is the 5 second restore rate. As you stated in your point 3 is that restoring doesn't seem to be very evenly distributed which is what we also noticed. Sometimes not even 20 seconds between two requests is enough to prevent throttling, sometimes 2 seconds are fine. To us its not clear why the API behaves like this. We have already discussed this here previously (see #78), but didn't really come to a conclusion.

Anyway, at least for the accounts we tested setting the restore rate to 5 seconds does result in quite a lot of throttling. But even if 5 seconds would always work fine we would still want to stay with the "documentation"-limit of 180 seconds. Setting it to something that's not in the docs might end up in having a lot of confusion, especially if this is the case in more parts of the module.

Users still have the opportunity of setting auto_request_throttled to false and then handle the throttling on their own end to speed up things if possible and necessary. But for the definition inside the module we should stick with what Amazons docs tell us, even though it does not 100% map the real experience.

[vhle-ms]

For anyone looking for a workaround, you can specify your own restore_rate if you invoke callAPI like this:

const res: GetOrderItemsResponse = await sellingPartner.callAPI({
  api_path: `/orders/v0/orders/${order.AmazonOrderId}/orderItems`,
  method: "GET",
  restore_rate: 5,
} as never as SellingPartnerAPI.ReqParams<string>);

The key here is to manually specify an api_path, rather than using the endpoint/operation params.

A 180-second delay for orderItems is completely unworkable in practice. With the MWS API, the rate limit for the equivalent operation is 1800 per hour (1 every 2 seconds). While I understand the need to default to the "official" rate limit stated in the documentation, I believe a happy compromise would be to let the user specify the restore_rate as part of callAPI, even when it is called with the "standard" endpoint/operation params.

@amz-tools - if you're happy with this approach, I can submit a PR for this.

[amz-tools]

@vhle-ms,

would absolutely support it. This would enable a simple workaround for the issue without having to directly change the official restore rate.

[YuriiHerasymchuk]

@vhle-ms thanks for the workaround. Let me know if you need any help with the PR, I will for sure use the feature.