Amazon Promotion API Documentation Read an Amazon promotion or coupon: title, saving, expiry date and terms as plain text, plus the products in it with price, list price, unit price, rating, Prime, lightning deal and delivery text. Take the id from amzn1.promotion.<id> on Amazon search results and product pages. The first answer holds the terms and the first products. Pass next_page_token as page_token for the next products. Title, saving and expiry come from Amazon for some markets only (US, CA, IN): other fields are null. A promotion can have no products. Supported on US, CA, IN, DE, IT, JP and AU. Costs 1 credit per successful request.
Run this endpoint
Endpoint
Parameters
Start with the required fields, then add optional filters only when your use case needs them.
Runnable path
1 required parameter needed before sending a request.
2 optional filters available.
string
Required
Promotion id in the path, with or without the amzn1.promotion. prefix. Example: A1E42UE9V21EFJ.
example
string
Optional
Amazon marketplace. Supported here: US, CA, IN, DE, IT, JP, AU. Default: US.
example.com
string
Optional
The next_page_token of the previous answer. Returns the next products and no terms.
example
Response Schema
Example response fields are illustrative; inspect the JSON before integrating.
Example response fields
Scan these fields before integrating.
data
meta
success
{
"data": {
"terms": "Each coupon applies only to one or more specified items.\nHow to redeem a coupon:\n- Apply the coupon to your account.",
"title": "Save 10% on Puori Favorites",
"domain": "US",
"products": [
{
"url": "https://www.amazon.com/dp/B0D63MXRF1",
"asin": "B0D63MXRF1",
"brand": "Puori",
"image": "https://m.media-amazon.com/images/I/412478yoa8L.jpg",
"price": {
"whole": "32",
"amount": 32,
"symbol": "$",
"display": "$32.00",
"currency": "USD",
"fraction": "00"
},
"prime": true,
"title": "Puori 5g Creatine Monohydrate Powder with Added Taurine, 60 Servings",
"rating": 4.7,
"list_price": null,
"unit_price": "$2.81/ounce",
"availability": null,
"reviews_count": 321,
"strikethrough": false,
"lightning_deal": false,
"delivery_message": null
}
],
"expiration": "2026-11-13",
"source_url": "https://www.amazon.com/promotion/psp/A1E42UE9V21EFJ",
"saving_info": "10% extra savings on the first order, applied at checkout.",
"terms_title": "Coupon Terms",
"promotion_id": "A1E42UE9V21EFJ",
"has_next_page": true,
"products_count": 16,
"expiration_text": "Coupon Expiry Date November 13, 2026",
"next_page_token": "eyJkIjoiVVMiLCJpIjoiQTFFNDJVRTlWMjFFRkoiLCJzIjoyNjg5ODAuMjV9"
},
"meta": {
"cached": false,
"domain": "US",
"currency": "USD",
"language": "en_US",
"timestamp": "2026-11-03T22:00:00.000000Z",
"response_time_ms": 4200
},
"success": true
}Errors
Handle these documented responses before retrying or showing customer-facing failures.
Not Found
The promotion does not exist on this marketplace. This response is not billable.
{
"error": "Not found on Amazon: promotion.",
"success": false
}Validation Error
The domain is not supported, the promotion id is malformed or the page_token does not belong to this promotion. This response is not billable.
{
"errors": {
"page_token": [
"The page_token is not valid for this promotion and domain. Use the next_page_token of a previous answer."
]
},
"message": "Validation failed"
}Service Unavailable
Amazon could not be reached after several tries. This response is not billable. Retry shortly.
{
"code": "transport_unavailable",
"error": "Amazon could not be reached right now. Try again shortly. No credits were used.",
"success": false
}Generate Code with AI
Copy a ready-made prompt with all the endpoint details, parameters, and example responses. Paste it into ChatGPT, Claude, or any AI assistant to instantly generate working code.
Try It Live
Test this endpoint in our interactive playground with real data.