Skip to main content

Refresh Amazon Buy Box

POST 
/api/v2/listings/buy-box/refresh

Samples Amazon's Featured Offer (Buy Box) for the ASINs behind the selected listings and stores the result against each ASIN.

Required scope: products:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

This is a read-only observation. It records who held the Featured Offer, at what price, and when the sample was taken. It never changes a price on Amazon.

The result is a point-in-time SAMPLE, not a continuous status — Amazon rotates the Featured Offer through the day. Every stored field is accompanied by the timestamp it was observed at.

Targeting modes:

  • product_listing_ids (array of integers) — refresh the ASINs behind these listings.
  • apply_to_all: true — refresh every ASIN matching the optional filters object (the same filters accepted by the listings list endpoint).

One of the two is required; a request with neither returns 422.

Behaviour:

  • Work is asynchronous. The response returns immediately with one entry per Amazon integration.
  • A selection can span several Amazon integrations. Because a sampling batch cannot cross seller credentials, the ASINs are grouped by integration and one run is started per integration. ASINs are de-duplicated per integration.
  • Only one sample run may be in flight per integration. An integration already running returns status "busy" with an explanatory message; tracked_job_log_id is null in that case, and is also null when the in-flight run was started by the recurring schedule rather than by a request.
  • Listings that are not Amazon listings, or that have no ASIN, are counted in skipped_non_amazon rather than silently dropped.

Status codes:

  • 202 Accepted — at least one run was started (a partial conflict is still a success).
  • 409 Conflict — every targeted integration already had a run in flight.
  • 422 Unprocessable Entity — nothing in the selection was an Amazon listing with an ASIN, or neither targeting mode was supplied.

Requires a Personal Access Token with products read/write scope.

Request​

Responses​

Accepted

Response Headers
    Content-Type