Automating Amazon's Request a Review Button with the Solicitations API

In Seller Central there is a Request a Review button on each order. Clicking it makes Amazon send the buyer a templated review request — Amazon writes it, Amazon translates it, you cannot change a word of it.

The Solicitations API is that button, callable. Which makes it the only compliant way to ask for reviews at volume, because it does not let you do any of the things that get sellers suspended.

Step zero, and the one that decides whether this project is a week or a quarter.

Solicitations requires the Buyer Solicitation role, or Product Listing. If your app has Buyer Communication — which sounds like the right one and is not — you do not have access. The probe is free and read-only:

GET /solicitations/v1/orders/{amazonOrderId}?marketplaceIds=ATVPDKIKX0DER

A 403 means the role is missing. And adding a role is not a checkbox:

1. You request the role on the application

   Which triggers an Amazon re-review of the app.

2. Every connected seller must re-authorise

   Existing refresh tokens do not gain the new scope. Each account goes through consent again to mint a token that carries it.

Ask what you can do:

GET /solicitations/v1/orders/{orderId}?marketplaceIds={one}

Eligible means productReviewAndSellerFeedback appears in _links.actions. Ineligible is a 200 with an empty actions list, not an error — so a naive "did it throw?" check will treat every ineligible order as eligible.

Send it:

POST /solicitations/v1/orders/{orderId}/solicitations/
     productReviewAndSellerFeedback?marketplaceIds={one}

201 on success, with no body.

That third row causes real damage if you get it wrong. A 403 on create means the order has already had its one request. Treat it as a retryable error and you will hammer that endpoint forever on orders that are permanently done.

Also: marketplaceIds takes exactly one marketplace per call. Not a list.

Requests are only valid in a window: from 5 days after the earliest delivery date, to 30 days after the latest delivery date. Call outside it and you get an error.

Which raises the obvious question — how do you know when it was delivered? And here is the part that catches people:

Amazon order status never says Delivered. It tops out at Shipped. There is no status transition to trigger from. If you fulfil through FBA you have no carrier tracking of your own either.

So the design Amazon's own documentation points at: compute a candidate window from the promised delivery dates on the order, then call the eligibility endpoint and believe it. Your window narrows the candidates; the API makes the decision.

1 request per second, burst 5 — per seller account. That last part is the useful bit: twenty accounts are twenty independent buckets, not one shared one.

Practically, that means a per-account throttle rather than a global one, and it means a backlog on one account cannot starve the others. If you already have a throttling wrapper for other SP-API calls, reuse it; this needs nothing special beyond correct scoping.

Two more constraints worth designing around:

• One solicitation per order, for its lifetime — and that allowance is shared with the Messaging API's proactive message. You get one or the other, never both. If you also send proactive messages, they compete for the same slot.
• API sends do not grey out the Seller Central button. Someone clicking it later just gets "already requested", which is harmless but confusing. Worth telling your ops team once.

The reason this API is safe to automate is precisely that it takes the dangerous choices away from you.

• You cannot write the message. Amazon composes and translates it.
• You cannot select happy buyers. Filtering to customers you think will leave five stars is review manipulation, and building that filter is the risk, not the API.
• You cannot ask twice. One per order, enforced server-side.

So the only real decision your code makes is which orders to attempt and when — and the honest answer is "all eligible ones, once, inside the window".

What does the Amazon Solicitations API do?

It is the API behind the Request a Review button in Seller Central. It sends a templated, Amazon-composed review and seller-feedback request to the buyer for a given order. The content is not customisable.

Which role does the Solicitations API need?

Buyer Solicitation, or Product Listing. Buyer Communication is a different role and does not grant access. Adding a role triggers an Amazon re-review of your application and requires every connected seller account to re-authorise.

Why does the create call return 403?

On the POST, a 403 normally means the order has already been solicited. That is a terminal state, not a transient error — mark the order done and never retry it. A 403 on the GET eligibility call means your app lacks the required role.

When can I send a review request?

Between 5 days after the order's earliest delivery date and 30 days after its latest delivery date. Calling outside that window errors.

How do I know an Amazon order was delivered?

You generally cannot from the order alone — Amazon order status tops out at Shipped and never reports Delivered. Compute a candidate window from the promised delivery dates and use getSolicitationActionsForOrder as the authority on eligibility.

Can I send review requests only to happy customers?

No. Selecting buyers by expected sentiment is review manipulation under Amazon's policies. The API deliberately gives you no way to do it — you choose which eligible orders to request, not what the message says or who is likely to be positive.