Selltics Docs

English

Русский

English

Русский

Appearance

API constraints ​

Updated

Two rules of the Amazon Ads API v1: one ad product per query filter, and one identity header per request.

As Amazon publishes it

Every statement on this page restates Amazon's public documentation and the published Amazon Ads API v1 OpenAPI specification, linked under Sources.

In short ​

  • adProductFilter.include takes exactly one ad product; reading several ad products takes one query per ad product.
  • A request carries Amazon-Advertising-API-Scope or Amazon-Ads-AccountId, not both.
  • Amazon-Ads-AccountId holds an account id, not a profile id.

adProductFilter.include takes exactly one ad product ​

The v1 query operations require an adProductFilter in the request body:

  • POST /adsApi/v1/query/campaigns
  • /adGroups
  • /ads
  • /targets
  • /adExtensions

Its include array is declared in the published OpenAPI specification with minItems: 1 and maxItems: 1:

json
{ "adProductFilter": { "include": ["SPONSORED_PRODUCTS"] } }
  • include names one value of the AdProduct enum: SPONSORED_PRODUCTS, SPONSORED_BRANDS, SPONSORED_DISPLAY, SPONSORED_TELEVISION or AMAZON_DSP.
  • Batch size limits of these operations are specific to each ad product.

One ad product per query

A request that lists two or more ad products violates the schema and is rejected. Reading several ad products takes one query per ad product.

One identity header per request: Amazon-Advertising-API-Scope or Amazon-Ads-AccountId ​

Every v1 request carries Amazon-Ads-ClientId and Authorization. On top of those, Amazon defines two different identity headers for two different scopes:

  • Amazon-Advertising-API-Scope — carries a profile id: one advertiser in one marketplace. Required for most sponsored-ads requests.
  • Amazon-Ads-AccountId — carries an advertising account id. Required for Amazon DSP and cross-product requests.

The headers are alternatives, not a pair:

  • A sponsored-ads query scoped to one marketplace is sent with Amazon-Advertising-API-Scope alone.
  • Amazon-Ads-AccountId is for requests that address the account across products or marketplaces.

Never both headers

Amazon's reporting migration guide states it directly for the two headers: "You should only use one of these headers, not both, per request."

The value of Amazon-Ads-AccountId is an account id, not a profile id; a profile id in that header is a documented cause of failed calls.

Sources ​