Amazon promotion details API
GET /promo-code-details reads an Amazon promotion page by its ID, the code in an amazon.com/promotion/psp/<promo_id> link that product pages show next to coupons and “Buy more & save” offers. It returns the title, banner, schedule when Amazon shows one, the how-to-claim steps, the note under them and the ID of the seller running it. The list of qualifying products is not returned, because Amazon loads it only in the browser.
Part of Amazon Data API, sold on RapidAPI with a free plan of 100 requests a month. Endpoint details checked 2026-11-03.
What GET /promo-code-details returns
An Amazon promotion by its ID (the code in an amazon.com/promotion/psp/<promo_id> link, shown on product pages next to coupons and 'Buy more & save' offers): title, banner, schedule, how-to-claim steps, the note under them and the seller running it. The promotion's product list is not returned: Amazon loads it only in the browser. Every response is checked to come from the requested marketplace. An unknown or ended promotion returns 404 not_found.
Parameters
| Name | Required | Values | Notes |
|---|---|---|---|
promo_id | yes | matches ^[A-Za-z0-9]{8,20}$ | The promotion ID from an amazon.com/promotion/psp/<promo_id> link. |
country | no | US, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZA | Amazon marketplace, as an ISO country code. GB is amazon.co.uk. Default US (amazon.com). |
Example request
Every parameter that has an example, with country set explicitly. Send your key in X-RapidAPI-Key.
curl --request GET \
--url 'https://amazon-data-api-search-product-reviews-best-sellers.p.rapidapi.com/promo-code-details?promo_id=A2BCF666XZ7UFF&country=US' \
--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
--header 'X-RapidAPI-Host: amazon-data-api-search-product-reviews-best-sellers.p.rapidapi.com'import requests
resp = requests.get(
"https://amazon-data-api-search-product-reviews-best-sellers.p.rapidapi.com/promo-code-details",
params={"promo_id": "A2BCF666XZ7UFF", "country": "US"},
headers={
"X-RapidAPI-Key": "YOUR_RAPIDAPI_KEY",
"X-RapidAPI-Host": "amazon-data-api-search-product-reviews-best-sellers.p.rapidapi.com",
},
timeout=30,
)
resp.raise_for_status()
body = resp.json()
if "error" in body: # bad input or not found: HTTP 200 with an error body
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"])const url = new URL('https://amazon-data-api-search-product-reviews-best-sellers.p.rapidapi.com/promo-code-details');
url.search = new URLSearchParams({ promo_id: 'A2BCF666XZ7UFF', country: 'US' });
const res = await fetch(url, {
headers: {
'X-RapidAPI-Key': process.env.RAPIDAPI_KEY,
'X-RapidAPI-Host': 'amazon-data-api-search-product-reviews-best-sellers.p.rapidapi.com',
},
});
const { data, meta } = await res.json();
console.log(data, meta.fetched_at);Example response
A recorded response, shortened to 3 items per list.
{
"data": {
"promo_id": "A2BCF666XZ7UFF",
"title": "Buy 5 to get 5% off",
"banner": "Buy More & Save",
"schedule": null,
"how_to_claim": [
"Add 5 or more items from the products on this page to your Cart and unlock a 5% discount.",
"The offer will be applied automatically at checkout if eligible."
],
"note": "Offer valid for products on this page, subject to updates.",
"seller_id": "A3DWYIK6Y9EEQB",
"url": "https://www.amazon.ca/promotion/psp/A2BCF666XZ7UFF"
},
"meta": {
"country": "CA",
"cached": false,
"fetched_at": "2026-11-03T05:00:00.000Z"
}
}What people use it for
Show the terms of a multi-buy or voucher offer next to the product in your own app.
Track which sellers run promotions, and how often, in a category.
Check whether a promotion has an end date before you plan around it.
FAQ
- Where do I find a promo_id?
- On an Amazon product page, the promotion link next to a coupon or “Buy more & save” offer goes to /promotion/psp/<promo_id>. The part after psp/ is the ID.
- Does it return the products in the promotion?
- No. Amazon loads the qualifying products in the browser, so they are not in the page the API reads. seller_id tells you whose products they are; /seller-products lists that seller’s catalog.
Related endpoints
See all 17 endpoints and 23 marketplaces on the Amazon product API page.