Amazon Vendor Coupon Performance Report

This is the first-party coupon report. Amazon serves sellers and vendors from the same report type and answers each with a completely different document. The one Vendor Central credentials get back is a list of campaigns, each carrying a vendor_code, campaign-level total_clips and total_redemptions, and a nested list of coupons whose own asins[] hold the per-ASIN discount. The seller version is a flat list of coupons with no campaign layer and no vendor code at all.

Because of that nesting, one file is not one row grain. It is three: the campaign, the coupon inside it, and the discount applied to each ASIN inside that. The document splits into three tables accordingly — ten campaign columns, fourteen coupon columns, five ASIN columns — and all twenty-nine are documented in that order. The coupon is the row most people mean when they ask about coupon performance, and it is the primary grain of the three.

The columns fall into four groups. Identity and settings — campaign_name, name, website_message, is_subscribe_and_save, is_once_per_customer, the start and end timestamps. Engagement — clips and redemptions at the coupon level, total_clips and total_redemptions at the campaign level above it. Money — budget, budget_spent, budget_remaining, budget_percentage_used and total_discount, all in the campaign's currency_code. And the per-ASIN discount, discount_type and discount_amount, which is where a single coupon stops being a single number.

There is no reporting date column anywhere in the three tables. creation_date_time, last_updated_date_time, start_date_time and end_date_time are all lifecycle timestamps describing the coupon, not the period its counts cover. Reading the file is reading the state of your coupons at the moment you pulled it.

Because nothing in the document dates a row, a stored copy needs context columns of its own: a marketplace, a country and a snapshot date. Only the first has any counterpart in Amazon's document — the schema marks a campaign-level marketplaceId required, though it is not among the columns measured off the production file — and a snapshot date is where a stored series gets its dates from. None of the three is in the column list for this report, because none of them comes out of the report.

Through the Selling Partner API, you request the report type GET_COUPON_PERFORMANCE_REPORT, poll it until Amazon has it ready, and download the JSON document. There is no separate vendor report type: the same identifier serves both, and it is the credentials on the request that decide which schema comes back.

That is the trap, and it is what makes the vendor variant worth documenting on its own. Code written against the seller response — a flat coupons[] array — does not merely lose detail on the vendor response, it finds nothing at all, because the vendor document's top level is campaigns[]. The two schemas share no envelope. Give the vendor variant its own report key and its own tables, so the two never land under one warehouse prefix and get read as one dataset.

The second trap is the nesting. The document has to be flattened three times, once per grain, and the ASIN rows only exist two levels down inside their coupon. A parser that reads campaigns[] and stops has the budget numbers but not a single ASIN.

There is a window on the request, and it is not the window you might expect. Amazon requires campaignStartDateFrom and campaignStartDateTo in reportOptions, and they select which campaigns come back — every campaign whose start date-time, meaning the earliest start of any of its coupons, falls inside the range, reaching up to two years back. They do not date the rows. The returned rows carry no data date range at all, so what you get is the current state of the campaigns you selected, and a history is still something you keep rather than something you request.

Main table

coupons

asins

Separating a clip problem from a redemption problem. clips says shoppers saw the offer and saved it; redemptions says they bought. A coupon with heavy clips and thin redemptions has a price, availability or detail-page problem downstream of the offer, and discounting harder will not fix it. A coupon with few clips has a visibility problem instead, and the two calls are opposites.

Knowing which coupons actually stopped. budget_remaining at zero means Amazon has stopped serving the coupon regardless of what end_date_time says. Ranking live coupons by budget_remaining against the days left in their window is the only way to see, from the file alone, which ones will die early — on campaigns where budget_type is PER_INDIVIDUAL_COUPON, which are the only ones whose coupons carry a budget of their own.

Auditing discount depth per ASIN. The ASIN grain carries discount_type and discount_amount per asin, so a campaign that looks like one offer can be discounting individual items at very different depths. This is where an overspend usually comes from.

Splitting Subscribe and Save from ordinary coupons. is_subscribe_and_save separates two mechanics that convert nothing alike. Blending them gives an average redemption rate that describes neither.

Checking what the offer actually said. website_message is the shopper-facing text, and it is the only column that records the offer as it was presented. When two coupons with similar budgets performed very differently, this and is_once_per_customer are the first two columns to read.

Reconciling campaign totals to coupon rows. total_clips and total_redemptions sit at the campaign level, clips and redemptions at the coupon level. Summing the coupon rows within a campaign_id and comparing is a cheap integrity check on any pipeline that flattens this file.

One report type, two incompatible schemas. Sellers and vendors both pull GET_COUPON_PERFORMANCE_REPORT, and the documents share nothing but the name. Anything that stores both under one table, or infers the schema from the report type rather than from the account, will silently produce an empty or half-empty dataset for one of them.

Joining the three grains fans out the money. A coupon covering five ASINs becomes five rows when you join the coupon table to the ASIN table, and budget_spent is repeated on every one of them. Summing after that join multiplies your spend by the ASIN count. Aggregate the money at the coupon grain first.

It is a snapshot, not a series. With no reporting date in the file, the clip and redemption counts are one number per coupon as of the pull. Amazon describes that number as cumulative for the campaign up until the day prior to your request — so it is a running total, not a window, and it is final only once the campaign has been over for a day or more. A day-over-day trend has to be built by keeping the snapshots; comparing two pulls is the only way to get a delta, and a coupon edited between them will move for reasons the counts do not show.

total_discount and budget_spent are not interchangeable. Amazon defines the first as what customers saved and the second as what the vendor spent, fees included — two sides of the same redemption, separated by the clip and redemption fees. Both are gross of returns and cancellations. Pick one deliberately for any number you publish, and do not let a query switch between them.

Money has one currency column and it lives on the campaign. currency_code is a campaign column; every money column at the coupon grain inherits it. A pull spanning vendor codes in different marketplaces will mix currencies, and nothing at the coupon grain warns you.

Amazon's schema defines fields this file does not carry. The published vendorCouponReport schema has a few columns beyond the twenty-nine here — a per-coupon customer_segment, a promotions_api_mapping_id that cross-references the Promotions API, and the campaign-level total_budget, total_budget_spent and total_budget_remaining that hold a SHARED_BUDGET campaign's cap. The columns above are the ones measured off a real production file, and they are what you should expect to land. Do not write a pipeline that requires the others, and do not assume a shared-budget campaign's cap is recoverable from this report.

Vendor coupon numbers do not benchmark against seller ones. Different schema, different account type, different placement of the offer. Comparing a 1P redemption rate to a 3P one is comparing two reports that only share a name.