Amazon Ads API v1 Report Template

Equivalent to v3 Sponsored_Products_Audience_report — 16 v3 columns mapped to v1 fields

Summary

This template replicates the v3 Sponsored Products Audience report on the Amazon Ads API v1 cross-product reporting endpoint (CreateReport). 15 of 16 v3 columns map cleanly to v1 fields; 1 ('Retailer') has no v1 equivalent.

The single most important mapping decision in this report: 'Audience Name' maps to target.value, NOT audienceSegment.name. The v1 audienceSegment. dimension family is for Amazon DSP, and the validator explicitly rejects every combination of audienceSegment with conversion metrics. Using the wrong field family would silently break the report.*

The 19-field payload was validated against the packaged v1 catalog: zero unknown fields, zero missing required, zero incompatible pairs.

Why 'Audience Name' is target.value

Sponsored Products has three target types: keywords, products, and audiences. All three are stored in the same dimensional family — target.value (the targeting expression) and target.matchType (the modifier, when applicable). When an audience-type target serves an impression, target.value carries the audience expression — typically something like views(asin="B0...") for retargeting, purchases(asin="B0...") for cross-sell, or lookalike(...) for similar-shopper targeting.

The v1 catalog also has an audienceSegment.* family (audienceSegment.id, audienceSegment.name, audienceSegment.type, audienceSegment.classCode, audienceSegment.marketplace, etc.). These are used in Amazon DSP audience-segment reporting, where audience segments are an independent dimensional axis from campaigns and ads. Validator probes confirm: audienceSegment.id and audienceSegment.name are INCOMPATIBLE with metric.sales, metric.purchases, metric.unitsSold, metric.roas, and every Halo/Promoted/FromClicks variant. They cannot be used in an SP audience report.

If you need to produce a report ONLY for audience targets (not keyword or product targets), the cleanest approach is to filter target.value downstream by audience-expression prefix. SP audience expressions typically start with views(, purchases(, lookalike(, similarToPurchasers(, or matchProduct(. The exact prefixes can vary; sample your campaign data to confirm the patterns in use.

Field list (grouped by role)

Time dimension (exactly one required)

• date.value

Level-of-detail dimensions

• portfolio.portfolioId

• portfolio.name

• campaign.id

• campaign.name

• campaign.currencyCode

• country.code

• country.name

• target.value

Required supporting field

• budgetCurrency.value

Delivery & conversion metrics

• metric.impressions

• metric.clicks

• metric.ctr

• metric.cpc

• metric.totalCost

• metric.sales

• metric.purchases

• metric.unitsSold

• metric.roas

Filter (limits the report to SP)

• adProduct.value = SPONSORED_PRODUCTS

v3 → v1 field mapping

Yellow row: Retailer has no v1 equivalent. The Audience Name row is highlighted because the mapping is non-obvious and getting it wrong silently breaks the report.

Critical differences from the v3 report

Operational notes

• Recovering an audience-only slice: in the warehouse, use a filter like:

WHERE target.value LIKE 'views(%'
   OR target.value LIKE 'purchases(%'
   OR target.value LIKE 'lookalike(%'
   OR target.value LIKE 'similarToPurchasers(%'

Confirm the prefix list against your campaign data — Amazon's audience expression syntax can include other variants.

• Reusing this template: this is essentially a slimmed SP Targeting report. If you also need keyword and product targets in the same query, drop the audience-expression filter downstream. If you need separate reports per target type, run this query once and partition target.value into three groups (keyword expressions, product targets like asin=, audience expressions) in the warehouse.