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.
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
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:
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.
Sign in to the Amazon Developer Console with your Amazon account, and select Login with Amazon from the top navigation.
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.
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.
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.
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.
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.
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.
LWA 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 Secret
Yes
Yes
LWA Client Secret paired with the Client ID, used during the authorization_code token exchange at api.amazon.com/auth/o2/token.
Refresh Token
Yes
Yes
OAuth2 refresh token obtained after completing the LWA authorization_code flow (profile and advertising::campaign_management scopes), used to mint new access tokens.
Profile ID
No
No
Advertising 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.
After selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.
Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.
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.
Enter the Client Secret paired with your Client ID. This value is used during the OAuth2 token exchange and should be kept confidential.
Enter the Refresh Token obtained from the LWA authorization code flow. Nexla uses this token to mint new access tokens as needed.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Lists brands (ID and name) that Amazon recommends excluding with Sponsored Brands negative targeting. The list includes your own brands. Results are paged.
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.
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.
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.
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).
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.
Report ID: reportId returned when the Brand Metrics report was requested.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.