Skip to main content

Amazon Ads API

The Amazon Ads API is a REST interface for programmatically managing Amazon advertising, including Sponsored Products, Sponsored Brands, and Sponsored Display campaigns, Amazon DSP advertisers and reporting, budget rules, Amazon Marketing Cloud (AMC) workflows, and Amazon Marketing Stream subscriptions. It lets you automate campaign management and pull performance data for analytics and reporting. Access is authorized with Login with Amazon (LWA) using the OAuth2 authorization code flow.

Amazon Ads API icon

Power end-to-end data operations for your Amazon Ads API API with Nexla. Our bi-directional Amazon Ads API connector is purpose-built for Amazon Ads API, making it simple to ingest data, sync it across systems, and deliver it anywhere — all with no coding required. Nexla turns API-sourced data into ready-to-use, reusable data products and makes it easy to send data to Amazon Ads API or any other destination. With comprehensive monitoring, lineage tracking, and access controls, Nexla keeps your Amazon Ads API workflows fast, secure, and fully governed.

Features

Type: API

SourceDestination

  • Seamless API Integration: Connect to any endpoint as source or destination without coding, with automatic data product creation
  • Visual Composition & Chaining: Build complex integrations using visual templates, chain API calls, and compose workflows with data validation and filtering
  • API Proxy: Expose curated slices of your data securely with a secure and customizable API proxy that validates and transforms data on the fly
  • Request optimization with intelligent batching, retry, and caching to minimize API calls and costs

Prerequisites​

Before creating an Amazon Ads API credential, you need an Amazon Ads account with API access enabled and a Login with Amazon (LWA) application from which you can obtain a Client ID, Client Secret, and a refresh token. The Amazon Ads API uses the OAuth2 authorization code flow: the Client ID is also sent as the Amazon-Advertising-API-ClientId header on every request, and requests scoped to a specific advertising account also send the profile ID in the Amazon-Advertising-API-Scope header.

To obtain your Amazon Ads API credentials, follow these steps:

  1. Complete Amazon Ads API onboarding to gain API access. Follow the steps in the Amazon Ads API onboarding overview to request access for your Amazon Ads account and associate it with a Login with Amazon application.

  2. Sign in to the Amazon Developer Console with your Amazon account, and select Login with Amazon from the top navigation.

  3. Click Create a New Security Profile, and enter a name, description, and consent privacy notice URL for your application. This security profile represents the LWA application that will call the Amazon Ads API.

  4. Locate your security profile in the list, and click Show Client ID and Client Secret to reveal the Client ID and Client Secret. Copy both values and store them securely.

  5. Confirm that Amazon Ads API access is assigned to your Login with Amazon application as part of onboarding, so the security profile is authorized to call the Amazon Ads API.

  6. Complete the OAuth2 authorization code flow to obtain a Refresh Token. Using the Client ID and Client Secret, generate an authorization grant by consenting to the profile and advertising::campaign_management scopes for the Amazon Ads account, then exchange the returned authorization code at https://api.amazon.com/auth/o2/token for an access token and refresh token. See Retrieve an access token and refresh token for details.

  7. Store the Refresh Token securely. Amazon may issue a new refresh token when you exchange one for a fresh access token, so always persist the most recent refresh token.

  8. Retrieve your Profile ID by calling GET https://advertising-api.amazon.com/v2/profiles with a valid access token and the Amazon-Advertising-API-ClientId header. Each profile represents an advertising account in a specific marketplace; use the profile ID for the account whose data you want to access.

For complete details about authorization, token exchange, and refresh tokens, see the Amazon Ads API authorization overview.

Authenticate​

Credentials required​

FieldRequiredSecretDescription
Client IDYesNoLWA Client ID for the Amazon Ads API app (from the Security Profile at developer.amazon.com). Also sent as the Amazon-Advertising-API-ClientId header on every request.
Client SecretYesYesLWA Client Secret paired with the Client ID, used during the authorization_code token exchange at api.amazon.com/auth/o2/token.
Refresh TokenYesYesOAuth2 refresh token obtained after completing the LWA authorization_code flow (profile and advertising::campaign_management scopes), used to mint new access tokens.
Profile IDNoNoAdvertising profile ID to scope requests to (sent as Amazon-Advertising-API-Scope). Obtain via GET /v2/profiles; not required for the profiles-list call itself.

Create a credential in Nexla​

  1. After selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.

  2. Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.

  3. Enter the Client ID for your Login with Amazon application. This value authenticates your app and is also sent as the Amazon-Advertising-API-ClientId header on every Amazon Ads API request.

  4. Enter the Client Secret paired with your Client ID. This value is used during the OAuth2 token exchange and should be kept confidential.

  5. Enter the Refresh Token obtained from the LWA authorization code flow. Nexla uses this token to mint new access tokens as needed.

  6. Optionally, enter the Profile ID for the advertising account you want to access. This value is sent as the Amazon-Advertising-API-Scope header for profile-scoped endpoints. It is not required for the profiles-list call.

    If your Client Secret or Refresh Token is compromised, revoke access and generate new credentials from your Login with Amazon security profile. For detailed information about authorization and token management, see the Amazon Ads API authorization overview.

  7. Click the Save button at the bottom of the overlay. The newly added credential will now appear in a tile on the Authenticate screen during data source/destination creation.

Use as a data source​

To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Select the Amazon Ads API connector tile, then select the credential that will be used to connect to Amazon Ads, and click Next; or, create a new Amazon Ads API credential for use in this flow.

Endpoint templates​

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common Amazon Ads API endpoints. Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below.

Templates are grouped by area below. Settings that most templates share:

  • API URL: the Amazon Ads API host for your account's region: https://advertising-api.amazon.com (North America, the default), https://advertising-api-eu.amazon.com (Europe) or https://advertising-api-fe.amazon.com (Far East).
  • Profile ID: the advertising profile (advertiser account and marketplace) to read, sent as the Amazon-Advertising-API-Scope header. Use the List Profiles template to find it.
  • Older templates name these settings Api Url and Profileid. Their Api Url has no default, so enter the host for your region. Their Access Token and Client Id settings are not used in the request and can be left empty.

Many list, recommendation, forecast and eligibility templates are reads that Amazon serves as POST requests; they do not change anything in your account. A few older source templates do create objects in Amazon Ads every time the source runs. Those are marked Side effect below.

Accounts and profiles​

List Profiles

Lists the advertising profiles (one per advertiser account and marketplace) that the credential can access, with profile ID, country, currency and account type. Use the profile ID as the Profile ID in other templates.

List Advertising Accounts

Lists the global advertising accounts the signed-in user can reach, with account ID, name, alternate IDs per country and status. Results are paged.

  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: List Advertising Accounts

Get Advertising Account

Retrieves one global advertising account: name, status, alternate IDs per country and errors.

  • Advertising Account ID: Global advertising account id (amzn1.ads-account.g.…) from List Advertising Accounts.
  • Amazon reference: Get Advertising Account

List SP campaigns

Lists the Sponsored Products campaigns in a profile. Reads the first page of results only.

  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.

List Sponsored Products Ad Groups

Lists the Sponsored Products ad groups in a profile, with campaign ID, name, state and default bid. Results are paged.

List Sponsored Products Keywords

Lists the bid keywords in Sponsored Products ad groups, with keyword text, match type (broad, phrase or exact), bid and state. Results are paged.

List SP Ad Group Negative Keywords

Lists the negative keywords set on Sponsored Products ad groups (negative exact or phrase), with ad group, campaign and state. Results are paged.

List SP Campaign Negative Keywords

Lists the negative keywords set at Sponsored Products campaign level, with keyword text, match type and state. Results are paged.

List Sponsored Products Product Ads

Lists the product ads (advertised ASIN or SKU) in Sponsored Products ad groups, with campaign, ad group and state. Results are paged.

List Sponsored Products Targets

Lists the product, category and auto targeting clauses in Sponsored Products ad groups, with expression, bid and state. Results are paged.

List SP Ad Group Negative Targets

Lists the negative product or brand targets on Sponsored Products ad groups, with expression and state. Results are paged.

List SP Campaign Negative Targets

Lists the negative product or brand targets set at Sponsored Products campaign level, with expression and state. Results are paged.

List SP Targetable Categories

Retrieves the category tree that Sponsored Products can target, with category IDs and names. Amazon returns the tree as a JSON string in the categoryTree field.

Get SP Category Refinements

Lists the brands, age ranges and genres available to refine a Sponsored Products category target.

Get SP Targetable ASIN Count

Returns the estimated range (minimum and maximum) of ASINs that Sponsored Products can target in a category.

  • Category ID: Category node id (from List SP Targetable Categories or List SP Category Targeting Recommendations).
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: Get SP Targetable ASIN Count

List SB campaigns

Lists the Sponsored Brands campaigns in a profile (Sponsored Brands v4 API). Reads the first page of results only.

  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.

List Sponsored Brands Ad Groups

Lists the Sponsored Brands ad groups in a profile, with campaign ID, name and state. Results are paged.

List Sponsored Brands Ads

Lists Sponsored Brands ads (product collection, video and store spotlight), with ad group, campaign, landing page and state. Results are paged.

  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: List Sponsored Brands Ads

List SB Ad Creatives

Lists the creative versions of one Sponsored Brands ad, with type, status, moderation state and creative properties. Results are paged.

  • Ad ID: Sponsored Brands adId (from List SB ads).
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: List SB Ad Creatives

List SB Targetable Categories

Lists the categories that Sponsored Brands can target, with refinement ID, name, parent and whether each is targetable. Results are paged.

Get SB Category Refinements

Lists the brands, age ranges and genres available to refine a Sponsored Brands category target (first page of each list).

Get SB Targetable ASIN Count

Returns the estimated range (minimum and maximum) of ASINs that Sponsored Brands can target in a category.

  • Category Refinement ID: Category refinement id (from List SB Targetable Categories).
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: Get SB Targetable ASIN Count

Get SB Campaign Forecast

Forecasts weekly impressions, clicks and spend for a planned Sponsored Brands product-collection campaign that advertises one ASIN with one keyword.

  • ASIN: Advertised product ASIN (from List SP product ads or the Product Metadata endpoint).
  • Keyword: Keyword the planned campaign bids on.
  • Daily Budget: Planned daily budget in the marketplace currency. Default: 50.
  • Keyword Bid: Planned keyword bid in the marketplace currency. Default: 1.0.
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed. The campaign is not created.
  • Amazon reference: Get SB Campaign Forecast

List SD campaigns

Lists the Sponsored Display campaigns in a profile.

Portfolios and budget usage​

List Portfolios

Lists the portfolios in a profile, with name, state and budget policy. Use the portfolio ID to group or filter campaigns. Results are paged.

  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: List Portfolios

Get Portfolio Budget Usage

Returns the current budget usage percentage and budget of one portfolio, with the time it was last updated.

  • Portfolio ID: portfolioId (from List Portfolios).
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: Get Portfolio Budget Usage

Get SP Campaign Budget Usage

Returns the current budget usage percentage and budget of one Sponsored Products campaign.

  • Campaign ID: Sponsored Products campaignId (from List SP campaigns).
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: Get SP Campaign Budget Usage

Get SB Campaign Budget Usage

Returns the current budget usage percentage and budget of one Sponsored Brands campaign.

  • Campaign ID: Sponsored Brands campaignId (from List SB campaigns).
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: Get SB Campaign Budget Usage

Sponsored Products

Returns budget usage for Sponsored Products campaigns.

  • Campaignids: Campaign identifiers as a JSON array of strings. Obtain them from the Sponsored Products campaign list endpoint.
  • This older template sends the campaign IDs as a quoted string rather than a JSON array. Prefer Get SP Campaign Budget Usage.
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.

Sponsored Brands

Intended to return budget usage for Sponsored Brands campaigns.

  • Campaignids: Campaign identifiers as a JSON array of strings. Obtain them from the Sponsored Brands campaign list endpoint.
  • This older template calls the Sponsored Products budget usage path (/sp/campaigns/budget/usage), not the Sponsored Brands one. Use Get SB Campaign Budget Usage for Sponsored Brands campaigns.
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.

Sponsored Display

Returns budget usage for Sponsored Display campaigns.

  • Campaignids: Campaign identifiers as a JSON array of strings. Obtain them from the Sponsored Display campaign list endpoint.
  • This older template sends the campaign IDs as a quoted string rather than a JSON array.
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.

Budget rules​

Get budget rules

Lists the Sponsored Products budget rules in a profile. Reads one page of results.

  • Pagesize: Page size sent to Amazon (default 30). The template reads one page only.

All budget rules (Budget Rules Sp)

Lists all Sponsored Products budget rules in a profile. Reads one page of results.

  • Pagesize: Page size sent to Amazon (default 30). The template reads one page only.

All budget rules (Budget Rules Sb)

Lists all Sponsored Brands budget rules in a profile. Reads one page of results.

  • Pagesize: Page size sent to Amazon (default 30). The template reads one page only.

All budget rules (Budget Rules Sd)

Lists all Sponsored Display budget rules in a profile. Reads one page of results.

  • Pagesize: Page size sent to Amazon (default 30). The template reads one page only.

Get SP Budget Rule

Retrieves one Sponsored Products budget rule by ID: rule type, recurrence, budget increase and performance condition.

  • Budget Rule ID: ruleId from All budget rules (Budget Rules Sp).
  • Amazon reference: Get SP Budget Rule

Get SB Budget Rule

Retrieves one Sponsored Brands budget rule by ID: rule type, recurrence, budget increase and performance condition.

  • Budget Rule ID: ruleId from All budget rules (Budget Rules Sb).
  • Amazon reference: Get SB Budget Rule

Get SD Budget Rule

Retrieves one Sponsored Display budget rule by ID: rule type, recurrence, budget increase and performance condition.

  • Budget Rule ID: ruleId from All budget rules (Budget Rules Sd).
  • Amazon reference: Get SD Budget Rule

List Campaigns of SP Budget Rule

Lists the Sponsored Products campaigns a budget rule is attached to, with each campaign's rule status. Results are paged.

List Campaigns of SB Budget Rule

Lists the Sponsored Brands campaigns a budget rule is attached to, with each campaign's rule status. Results are paged.

List Campaigns of SD Budget Rule

Lists the Sponsored Display campaigns a budget rule is attached to, with each campaign's rule status. Results are paged.

List Budget Rules of SP Campaign

Lists the budget rules attached to one Sponsored Products campaign, with rule details and status.

List Budget Rules of SB Campaign

Lists the budget rules attached to one Sponsored Brands campaign, with rule details and status.

List Budget Rules of SD Campaign

Lists the budget rules attached to one Sponsored Display campaign, with rule details and status.

Create budget rules (Sponsored Products Budget Rules)

Creates Sponsored Products budget rules and returns the result for each rule.

  • Budgetrulesdetails: The budget rule definitions, as a JSON array of rule objects (name, ruleType, duration, recurrence, budgetIncreaseBy). The setting's default value shows the shape.
  • Side effect: every run of this source creates the budget rules in the Budgetrulesdetails setting in your Amazon Ads account, so a scheduled source creates them again on each run.

Create budget rules (Budget Rules Sp)

Creates Sponsored Products budget rules and returns the result for each rule. To create rules from Nexset records instead, use the Create Sponsored Products Budget Rules destination.

  • Budgetrulesdetails: The budget rule definitions, as a JSON array of rule objects (name, ruleType, duration, recurrence, budgetIncreaseBy). The setting's default value shows the shape.
  • Side effect: every run of this source creates the budget rules in the Budgetrulesdetails setting in your Amazon Ads account, so a scheduled source creates them again on each run.

Create budget rules (Budget Rules Sb)

Creates Sponsored Brands budget rules and returns the result for each rule.

  • Budgetrulesdetails: The budget rule definitions, as a JSON array of rule objects (name, ruleType, duration, recurrence, budgetIncreaseBy). The setting's default value shows the shape.
  • Side effect: every run of this source creates the budget rules in the Budgetrulesdetails setting in your Amazon Ads account, so a scheduled source creates them again on each run.

Create budget rules (Budget Rules Sd)

Creates Sponsored Display budget rules and returns the result for each rule.

  • Budgetrulesdetails: The budget rule definitions, as a JSON array of rule objects (name, ruleType, duration, recurrence, budgetIncreaseBy). The setting's default value shows the shape.
  • Side effect: every run of this source creates the budget rules in the Budgetrulesdetails setting in your Amazon Ads account, so a scheduled source creates them again on each run.

Recommendations​

List Recommendations

Lists Amazon's actionable recommendations across ad products, with type, status, campaign, summary and estimated impact. Results are paged.

  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: List Recommendations

Get SP Campaign Recommendations

Lists Amazon's recommended changes for Sponsored Products campaigns (budget, bids and targeting), with estimated impact. Results are paged.

List SP Campaign Recommendations by Type

Lists Amazon's recommendations of one type (for example bidding strategy, budget, keywords or placement bids) for one Sponsored Products campaign, with estimated impact.

  • Campaign ID: Sponsored Products campaignId (from List SP campaigns).
  • Recommendation Type: Kind of recommendation to fetch. Options: BUDGET_STRATEGY, BIDDING_STRATEGY, KEYWORD, KEYWORD_GROUP, PLACEMENT_BIDDING, SHOPPER_COHORT. Default: BUDGET_STRATEGY.
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: List SP Campaign Recommendations by Type

Get SP Bid Recommendations

Returns theme-based suggested bids (low, median and high) with impact metrics for the auto-targeting expressions of an existing Sponsored Products ad group.

  • Campaign ID: Sponsored Products campaignId (from List SP campaigns).
  • Ad Group ID: Sponsored Products adGroupId in that campaign (from List SP ad groups).
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: Get SP Bid Recommendations

Get SP Multi-Country Bid Recommendations

Returns theme-based suggested bids per country for an existing multi-country (global) Sponsored Products ad group.

  • Global Ads Account ID: Global advertising account id (amzn1.ads-account.g.…), sent as Amazon-Ads-AccountId. Get it from List Advertising Accounts.
  • Global Campaign ID: campaignId of a global (multi-country) Sponsored Products campaign.
  • Global Ad Group ID: adGroupId of an ad group in that global campaign.
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: Get SP Multi-Country Bid Recommendations

Get SP Budget Recommendations

Returns the recommended daily budget and estimated missed impressions, clicks and sales for one Sponsored Products campaign.

  • Campaign ID: Sponsored Products campaignId (from List SP campaigns).
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: Get SP Budget Recommendations

Get SP New Campaign Budget Recommendation

Returns a recommended daily budget, benchmark metrics and upcoming special events for a new auto-targeted Sponsored Products campaign that advertises the given ASIN.

  • ASIN: Advertised product ASIN (from List SP product ads or the Product Metadata endpoint).
  • Bidding Strategy: Bidding strategy of the planned campaign. Options: LEGACY_FOR_SALES, AUTO_FOR_SALES, MANUAL, RULE_BASED. Default: LEGACY_FOR_SALES.
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed. The campaign is not created.
  • Amazon reference: Get SP New Campaign Budget Recommendation

List SP Budget Rule Recommendations

Lists special events, with a suggested date range and budget increase, that a budget rule could cover for one Sponsored Products campaign.

  • Campaign ID: Sponsored Products campaignId (from List SP campaigns).
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: List SP Budget Rule Recommendations

List SP Keyword Recommendations

Lists ranked keyword targets recommended for an existing Sponsored Products ad group, with match type, rank and theme-based suggested bids.

  • Campaign ID: Sponsored Products campaignId (from List SP campaigns).
  • Ad Group ID: Sponsored Products adGroupId in that campaign (from List SP ad groups).
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: List SP Keyword Recommendations

List SP Multi-Country Keyword Recommendations

Lists keyword targets recommended per country for an existing global Sponsored Products ad group. Amazon returns them as a map keyed by country code.

  • Global Ads Account ID: Global advertising account id (amzn1.ads-account.g.…), sent as Amazon-Ads-AccountId. Get it from List Advertising Accounts.
  • Global Campaign ID: campaignId of a global (multi-country) Sponsored Products campaign.
  • Global Ad Group ID: adGroupId of an ad group in that global campaign.
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: List SP Multi-Country Keyword Recommendations

List SP Keyword Group Recommendations

Lists keyword groups (themes of related search terms) recommended for an ASIN in Sponsored Products. Results are paged.

  • ASIN: Advertised product ASIN (from List SP product ads or the Product Metadata endpoint).
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: List SP Keyword Group Recommendations

List SP Category Targeting Recommendations

Lists product categories recommended for Sponsored Products category targeting, based on the given ASIN.

  • ASIN: Advertised product ASIN (from List SP product ads or the Product Metadata endpoint).
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: List SP Category Targeting Recommendations

List SP Product Targeting Recommendations

Lists the ASINs Amazon suggests targeting in a Sponsored Products product-targeting campaign for an advertised ASIN. Results are paged.

  • ASIN: Advertised product ASIN (from List SP product ads or the Product Metadata endpoint).
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: List SP Product Targeting Recommendations

List SP Negative Brand Recommendations

Lists brands (ID and name) that Amazon recommends excluding with Sponsored Products negative targeting. The list includes your own brands.

Search SP Brands for Negative Targeting

Searches for up to 100 brands (ID and name) matching a keyword, for building Sponsored Products negative brand targets.

Get SB Budget Recommendations

Returns the recommended daily budget, with estimated missed opportunities, for one Sponsored Brands campaign.

  • Campaign ID: Sponsored Brands campaignId (from List SB campaigns).
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: Get SB Budget Recommendations

Get SB Cost Control Recommendation

Returns the recommended and minimum cost per click for a Sponsored Brands campaign that lands on an ASIN's detail page.

  • ASIN: Advertised product ASIN (from List SP product ads or the Product Metadata endpoint).
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: Get SB Cost Control Recommendation

List SB Budget Rule Recommendations

Lists special events, with a suggested date range and budget increase, that a budget rule could cover for one Sponsored Brands campaign.

  • Campaign ID: Sponsored Brands campaignId (from List SB campaigns).
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: List SB Budget Rule Recommendations

List SB Headline Recommendations

Lists up to 10 suggested Sponsored Brands creative headlines for an ASIN.

  • ASIN: Advertised product ASIN (from List SP product ads or the Product Metadata endpoint).
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: List SB Headline Recommendations

List SB Keyword Recommendations

Lists keywords Amazon recommends for a Sponsored Brands campaign that advertises an ASIN, with match type and impression share or rank.

  • ASIN: Advertised product ASIN (from List SP product ads or the Product Metadata endpoint).
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: List SB Keyword Recommendations

List SB Negative Brand Recommendations

Lists brands (ID and name) that Amazon recommends excluding with Sponsored Brands negative targeting. The list includes your own brands. Results are paged.

Get SD Bid Recommendations

Returns the suggested bid range for a Sponsored Display product-targeting clause that targets the given ASIN, for the chosen cost type and bid optimization.

  • ASIN: Advertised product ASIN (from List SP product ads or the Product Metadata endpoint).
  • Target ASIN: ASIN the targeting clause targets (asinSameAs).
  • Bid Optimization: Bid optimization the recommendation is for. Options: clicks, conversions, reach. Default: clicks.
  • Cost Type: Cost type the recommendation is for. Options: cpc, vcpm. Default: cpc.
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: Get SD Bid Recommendations

Get SD Budget Recommendations

Returns the recommended daily budget, with estimated missed impressions, clicks and conversions, for one Sponsored Display campaign.

  • Campaign ID: Sponsored Display campaignId (from List SD campaigns).
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: Get SD Budget Recommendations

List SD Product Targeting Recommendations

Lists products Amazon recommends targeting with Sponsored Display for an advertised ASIN.

  • ASIN: Advertised product ASIN (from List SP product ads or the Product Metadata endpoint).
  • Tactic: Sponsored Display tactic. Options: T00020, T00001, T00010, remarketing. Default: T00020.
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: List SD Product Targeting Recommendations

Audiences, locations, products and eligibility​

List Audiences

Lists the audience segments available to an advertiser for Sponsored Display, DSP or Sponsored TV, with ID, name, category, description, status and forecasts. Results are paged.

  • Ad Type: Ad program the audiences are for. Options: SD, DSP, ST. Default: SD.
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: List Audiences

List Audience Taxonomy

Lists the top-level audience categories in the audience taxonomy, with name, path and audience count. Results are paged.

  • Ad Type: Ad program the taxonomy is for. Options: SD, DSP, ST. Default: SD.
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: List Audience Taxonomy

List Overlapping Audiences

Lists the audiences that overlap most with a given audience, with affinity and overlap index. Results are paged.

  • Audience ID: audienceId (from List Audiences).
  • Ad Type: Ad program. Options: SD, DSP. Default: SD.
  • Amazon reference: List Overlapping Audiences

List Locations

Searches US locations (city, state, DMA, postal code and similar) by name, for location targeting. Results are paged.

  • Location Name: Location name to search for (fuzzy match), e.g. a city or state.
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: List Locations

List Product Metadata

Lists the products in the advertiser's inventory, with ASIN, SKU, title, image, price, availability and Sponsored Products eligibility. Results are paged.

  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: List Product Metadata

List Product Advertising Eligibility

Returns the advertising eligibility status, with reasons, of an ASIN for the chosen ad program.

  • ASIN: Advertised product ASIN (from List SP product ads or the Product Metadata endpoint).
  • Ad Type: Ad program to check. Options: sp, sb, sd, dsp. Default: sp.
  • Read-only. Amazon serves this read as a POST query; nothing is created or changed.
  • Amazon reference: List Product Advertising Eligibility

List Ad Program Eligibility

Returns whether the advertiser is eligible for each ad program in each marketplace, with reasons when not. Results are paged.

Reporting​

Get Report Status

Retrieves the status of a Sponsored Ads (v3) report: PENDING, PROCESSING, COMPLETED or FAILED, and the download URL once the report is complete. Request reports with the Request Report (v3) destination or the Create report source.

  • Report ID: reportId returned by Create Report (Sponsored Ads v3).
  • Amazon reference: Get Report Status

Create report

Requests an asynchronous Sponsored Ads (v3) report and returns its report ID. Poll Get Report Status with that ID to get the download URL.

  • Name: Report name.
  • Startdate: First day of the report date range (yyyy-MM-dd).
  • Enddate: Last day of the report date range (yyyy-MM-dd).
  • Configuration: Report configuration object: ad product, report type, groupBy, columns, time unit and format. The default requests a daily Sponsored Products campaign report.
  • Side effect: every run of this source requests a new report from Amazon.

Get Brand Metrics Report

Retrieves the status, format, download location and brands of a Brand Metrics report.

Request DSP report

Requests an Amazon DSP report for a DSP account and date range and returns the report request. Poll DSP report status for the result.

  • Dspaccountid: Amazon DSP advertiser account ID.
  • Startdate: First day of the report date range (yyyy-MM-dd).
  • Enddate: Last day of the report date range (yyyy-MM-dd).
  • Type: DSP report type (default CAMPAIGN).
  • Dimensions: DSP report dimensions (default order, line item and creative).
  • Metrics: DSP report metrics. The default lists every available metric.
  • Side effect: every run of this source requests a new DSP report from Amazon.

DSP report status

Retrieves the status and download location of a DSP report requested with Request DSP report.

  • Reportid: The reportId returned by Request DSP report.
  • Dspaccountid: Amazon DSP advertiser account ID.

Amazon Marketing Cloud (AMC)​

List all AMC accounts

Lists the Amazon Marketing Cloud (AMC) accounts the credential can access. The advertiser and marketplace IDs it returns are needed by the other AMC templates.

List AMC Instances

Lists the AMC instances an advertiser can access, with instance ID, name, type and creation status. Results are paged.

  • AMC Advertiser ID: Advertiser id of the AMC account (from List all AMC accounts); sent as Amazon-Advertising-API-AdvertiserId.
  • Marketplace ID: Marketplace id of the AMC account (from List all AMC accounts); sent as Amazon-Advertising-API-MarketplaceId.
  • Amazon reference: List AMC Instances

Get AMC Instance

Retrieves one AMC instance: name, type, creation status, data upload account and the entities with access.

  • AMC Instance ID: instanceId from List AMC Instances.
  • AMC Advertiser ID: Advertiser id of the AMC account (from List all AMC accounts); sent as Amazon-Advertising-API-AdvertiserId.
  • Marketplace ID: Marketplace id of the AMC account (from List all AMC accounts); sent as Amazon-Advertising-API-MarketplaceId.
  • Amazon reference: Get AMC Instance

List advertisers in instance

Lists the advertisers linked to an AMC instance.

  • Instanceid: AMC instance ID (from List AMC Instances).
  • Advertiser Id: Advertiser ID of the AMC account (from List all AMC accounts), sent as the Amazon-Advertising-API-AdvertiserId header.
  • Marketplace Id: Marketplace ID of the AMC account (from List all AMC accounts), sent as the Amazon-Advertising-API-MarketplaceId header.

List all workflows in a specific instance

Lists the workflows (saved AMC SQL queries) in an AMC instance. Reads the first page of results.

  • Instanceid: AMC instance ID (from List AMC Instances).
  • Marketplace Id: Marketplace ID of the AMC account (from List all AMC accounts), sent as the Amazon-Advertising-API-MarketplaceId header.
  • Advertiser Id: Advertiser ID of the AMC account (from List all AMC accounts), sent as the Amazon-Advertising-API-AdvertiserId header.

List all schedules

Lists the workflow schedules in an AMC instance.

  • Instanceid: AMC instance ID (from List AMC Instances).
  • Marketplace Id: Marketplace ID of the AMC account (from List all AMC accounts), sent as the Amazon-Advertising-API-MarketplaceId header.
  • Advertiser Id: Advertiser ID of the AMC account (from List all AMC accounts), sent as the Amazon-Advertising-API-AdvertiserId header.

Returns a list of workflow executions

Lists the executions of an AMC workflow, with status and the data time window each covers.

  • Workflowid: AMC workflow ID.
  • Includeworkflow: Whether to include each execution's workflow definition (default false).
  • Instanceid: AMC instance ID (from List AMC Instances).
  • Marketplace Id: Marketplace ID of the AMC account (from List all AMC accounts), sent as the Amazon-Advertising-API-MarketplaceId header.
  • Advertiser Id: Advertiser ID of the AMC account (from List all AMC accounts), sent as the Amazon-Advertising-API-AdvertiserId header.

Create a workflow

Creates a workflow in an AMC instance.

  • Instanceid: AMC instance ID (from List AMC Instances).
  • Marketplace Id: Marketplace ID of the AMC account (from List all AMC accounts), sent as the Amazon-Advertising-API-MarketplaceId header.
  • Advertiser Id: Advertiser ID of the AMC account (from List all AMC accounts), sent as the Amazon-Advertising-API-AdvertiserId header.
  • This template sends an empty request body. To define the workflow's ID and SQL query, use Create a workflow with custom parameters.
  • Side effect: every run of this source sends a create-workflow request to the AMC instance.

Create a workflow with custom parameters

Creates a workflow, with its SQL query and custom input parameters, in an AMC instance.

  • Instanceid: AMC instance ID (from List AMC Instances).
  • Marketplace Id: Marketplace ID of the AMC account (from List all AMC accounts), sent as the Amazon-Advertising-API-MarketplaceId header.
  • Advertiser Id: Advertiser ID of the AMC account (from List all AMC accounts), sent as the Amazon-Advertising-API-AdvertiserId header.
  • Workflowid: AMC workflow ID.
  • Sqlquery: The workflow's AMC SQL query.
  • Inputparameters: Custom parameter definitions for the workflow, as a JSON array.
  • Side effect: every run of this source sends a create-workflow request to the AMC instance.

Create a new schedule

Creates a schedule that runs an AMC workflow daily or weekly.

  • Instanceid: AMC instance ID (from List AMC Instances).
  • Marketplace Id: Marketplace ID of the AMC account (from List all AMC accounts), sent as the Amazon-Advertising-API-MarketplaceId header.
  • Advertiser Id: Advertiser ID of the AMC account (from List all AMC accounts), sent as the Amazon-Advertising-API-AdvertiserId header.
  • Scheduleid: ID for the new schedule.
  • Workflowid: AMC workflow ID.
  • Aggregationhourutc: Hour of day (UTC) the schedule runs (default 14).
  • Aggregationperiod: How often the workflow runs: Daily or Weekly (default Weekly).
  • Aggregationstartday: Day a weekly schedule starts on (default Monday).
  • Scheduleenabled: Whether the schedule is active (default true).
  • Requiresyntheticdata: Value for the schedule's requireSyntheticData flag (default true).
  • Disableaggregationcontrols: Value for the schedule's disableAggregationControls flag (default true).
  • Side effect: every run of this source sends a create-schedule request, and the schedule then runs the workflow on its own cadence.

Creates a new workflow execution

Starts an ad-hoc execution of an existing AMC workflow over the given time window. Executions are asynchronous; Amazon notes they typically take at least 15 minutes.

  • Instanceid: AMC instance ID (from List AMC Instances).
  • Marketplace Id: Marketplace ID of the AMC account (from List all AMC accounts), sent as the Amazon-Advertising-API-MarketplaceId header.
  • Advertiser Id: Advertiser ID of the AMC account (from List all AMC accounts), sent as the Amazon-Advertising-API-AdvertiserId header.
  • Workflowid: AMC workflow ID.
  • Timewindowstart: Start of the data time window for the execution.
  • Timewindowend: End of the data time window for the execution.
  • Timewindowtype: Time window type (default EXPLICIT).
  • Timewindowtimezone: Time zone of the time window (default America/New_York).
  • Side effect: every run of this source starts a new workflow execution.

Amazon Marketing Stream​

List Stream subscriptions

Lists the Amazon Marketing Stream subscriptions of a profile.

Get Stream subscription by ID

Retrieves one Amazon Marketing Stream subscription by ID.

  • Subscriptionid: Amazon Marketing Stream subscription ID (from List Stream subscriptions).

List DSP Stream Subscriptions

Lists the Amazon Marketing Stream subscriptions of a DSP advertiser account, with dataset, destination and status. Results are paged.

Once the selected endpoint template has been configured, click the Test button to the right of the endpoint selection menu to retrieve a sample of the data that will be fetched. Sample data will be displayed in the Endpoint Test Result panel on the right, allowing you to verify that the source is configured correctly before saving.

Manual configuration​

Amazon Ads API data sources can also be manually configured to ingest data from any valid Amazon Ads API endpoint, including endpoints not covered by the pre-built templates, chained API calls, or custom request parameters. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, endpoint URL, date/time and lookup macros, path to data, metadata, and request headers.

Once all of the relevant settings have been configured, click the Create button in the upper right corner of the screen to save and create the new Amazon Ads API data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.

Use as a destination​

Click the + icon on the Nexset that will be sent to the Amazon Ads API destination, and select the Send to Destination option from the menu. Select the Amazon Ads API connector from the list of available destination connectors, then select the credential that will be used to connect to Amazon Ads, and click Next; or, create a new Amazon Ads API credential for use in this flow.

Endpoint templates​

Nexla provides pre-built templates that can be used to rapidly configure destinations to send data to common Amazon Ads API endpoints. Select the endpoint to which data will be sent from the Endpoint pulldown menu. Then, click on the template in the list below to expand it, and follow the instructions to configure additional endpoint settings.

Each record in the Nexset is sent as the JSON body of one request, one record at a time. API URL, Profile ID and any ID settings are fixed on the destination and apply to every record it sends. Every destination template writes to your Amazon Ads account; see the Side effect note on each.

Create Sponsored Products Campaigns

Creates Sponsored Products campaigns and returns the new campaign IDs.

  • Each record is the request body, for example {"campaigns": [{"name": "...", "state": "PAUSED", "targetingType": "MANUAL", "budget": {"budget": 10, "budgetType": "DAILY"}}]}. A campaign created with state PAUSED does not serve.
  • Side effect: creates campaigns in your Amazon Ads account. Campaigns created as ENABLED can start serving and spending.
  • Amazon reference: Create Sponsored Products Campaigns

Create Sponsored Products Ad Groups

Creates Sponsored Products ad groups in existing campaigns and returns the new ad group IDs. Amazon answers with a multi-status (207) response that lists successes and errors per item.

  • Each record is the request body: {"adGroups": [{"campaignId": "...", "name": "...", "state": "...", "defaultBid": 1.0}]}.
  • Side effect: creates ad groups in your Amazon Ads account.
  • Amazon reference: Create Sponsored Products Ad Groups

Create Sponsored Products Keywords

Creates Sponsored Products keywords in existing ad groups and returns the new keyword IDs.

  • Each record is the request body: {"keywords": [{"campaignId": "...", "adGroupId": "...", "keywordText": "...", "matchType": "EXACT", "state": "PAUSED", "bid": 1.0}]}. A keyword created with state PAUSED does not serve.
  • Side effect: creates keywords in your Amazon Ads account.
  • Amazon reference: Create Sponsored Products Keywords

Create Sponsored Products Negative Keywords

Creates Sponsored Products ad-group negative keywords.

  • Each record is the request body: {"negativeKeywords": [{"campaignId": "...", "adGroupId": "...", "keywordText": "...", "matchType": "NEGATIVE_EXACT", "state": "ENABLED"}]}. Match type is NEGATIVE_EXACT, NEGATIVE_PHRASE or NEGATIVE_BROAD; state PAUSED creates it inactive.
  • Side effect: creates negative keywords, which stop matching ads from showing for those searches when enabled.
  • Amazon reference: Create Sponsored Products Negative Keywords

Create SP Campaign Negative Keywords

Creates Sponsored Products campaign-level negative keywords.

  • Each record is the request body: {"campaignNegativeKeywords": [{"campaignId": "...", "keywordText": "...", "matchType": "NEGATIVE_EXACT", "state": "ENABLED"}]}. Match type is NEGATIVE_EXACT, NEGATIVE_PHRASE or NEGATIVE_BROAD; state PAUSED creates it inactive.
  • Side effect: creates negative keywords for the whole campaign.
  • Amazon reference: Create SP Campaign Negative Keywords

Create Sponsored Products Targets

Creates Sponsored Products product-targeting clauses in existing ad groups.

  • Each record is the request body: {"targetingClauses": [{"campaignId": "...", "adGroupId": "...", "expressionType": "MANUAL", "expression": [{"type": "ASIN_SAME_AS", "value": "..."}], "state": "PAUSED", "bid": 1.0}]}. A target created with state PAUSED does not serve.
  • Side effect: creates targeting clauses in your Amazon Ads account.
  • Amazon reference: Create Sponsored Products Targets

Create Portfolios

Creates portfolios (campaign groups with an optional budget cap) and returns the new portfolio IDs.

  • Each record is the request body: {"portfolios": [{"name": "...", "state": "ENABLED"}]}, optionally with a budget.
  • Side effect: creates portfolios in your Amazon Ads account.
  • Amazon reference: Create Portfolios

Create Sponsored Products Budget Rules

Creates Sponsored Products budget rules and returns their rule IDs. Attach a rule to a campaign with Associate Budget Rules to SP Campaign.

  • Each record is the request body: {"budgetRulesDetails": [{"name": "...", "ruleType": "SCHEDULE", "duration": ..., "recurrence": ..., "budgetIncreaseBy": ...}]}.
  • Side effect: creates budget rules in your Amazon Ads account. A rule changes no budget until it is attached to a campaign.
  • Amazon reference: Create Sponsored Products Budget Rules

Associate Budget Rules to SP Campaign

Attaches existing budget rules to one Sponsored Products campaign. A campaign can have up to 250 rules, and rule names must be unique within the campaign.

  • Campaign ID: Sponsored Products campaignId to attach the rules to (from List SP campaigns).
  • Enter the Campaign ID on the destination. Each record is the request body: {"budgetRuleIds": ["..."]}.
  • Side effect: the attached rules raise the campaign's budget when their conditions are met.
  • Amazon reference: Associate Budget Rules to SP Campaign

Request Report (v3)

Requests an asynchronous Sponsored Ads (v3) report and returns its report ID. Poll the Get Report Status source with that ID to get the download URL.

  • Each record is the request body: {"name": "...", "startDate": "yyyy-MM-dd", "endDate": "yyyy-MM-dd", "configuration": {"adProduct": "...", "reportTypeId": "...", "groupBy": [...], "columns": [...], "timeUnit": "DAILY", "format": "GZIP_JSON"}}.
  • Side effect: each record requests one report from Amazon. No campaign data is changed.
  • Amazon reference: Request Report (v3)

Create Stream subscription

Creates an Amazon Marketing Stream subscription.

  • Each record is sent as-is as the JSON request body, so it must be a complete subscription request as described in Amazon's Marketing Stream documentation.
  • Side effect: creates a subscription that starts delivering stream data to its destination.

Update Stream subscription

Updates an existing Amazon Marketing Stream subscription.

  • Enter the Subscriptionid on the destination. Each record is sent as-is as the JSON request body of the update (HTTP PUT).
  • Side effect: changes the subscription, for example its status.

Manual configuration​

Amazon Ads API destinations can also be manually configured to send data to any valid Amazon Ads API endpoint. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, data format, endpoint URL, request headers, attribute exclusions, record batching, and response webhooks.

Amazon Ads API endpoints typically expect JSON in the request body. Many endpoints also require version-specific Accept and Content-Type headers and the Amazon-Advertising-API-Scope header for profile-scoped operations.

Save & activate​

Once all endpoint settings have been configured, click the Done button in the upper right corner of the screen to save and create the destination. To send the data to the configured Amazon Ads API endpoint, open the destination resource menu, and select Activate.

The Nexset data will not be sent to the Amazon Ads API endpoint until the destination is activated. Destinations can be activated immediately or at a later time, providing full control over data movement.