Skip to main content

Amazon Ads

Availability
Available CoreAvailable StandardAvailable PlusAvailable ProAvailable Enterprise FlexAvailable PyAirbyte
Support Level
Airbyte
Connector Version
9.0.7 (last updated 22 days ago)
Sync Success Rate
High
Usage Rate
High
Data workers used
0.2 per sync (Learn more)
Definition ID
c6b0a29e-1da9-4512-9002-7bfd0cba2246

This page contains the setup guide and reference information for the Amazon Ads source connector.

Prerequisites​

  • Client ID
  • Client Secret
  • Refresh Token
  • Region
  • Start Date (Optional)
  • Profile IDs (Optional)
  • Marketplace IDs (Optional)
  • Look Back Window (Optional)
  • Number of concurrent threads (Optional)

Setup guide​

Step 1: Set up Amazon Ads​

Create an Amazon user with access to an Amazon Ads account.

For Airbyte Open Source: To use the Amazon Ads API, you must first complete the onboarding process. The onboarding process has several steps and may take several days to complete. After completing all steps you will have to get the Amazon client application's Client ID, Client Secret and Refresh Token.

Step 2: Set up the Amazon Ads connector in Airbyte​

For Airbyte Cloud:​

  1. Log into your Airbyte Cloud account.
  2. Click Sources and then click + New source.
  3. On the Set up the source page, select Amazon Ads from the Source type dropdown.
  4. Enter a name for the Amazon Ads connector.
  5. Click Authenticate your Amazon Ads account.
  6. Log in and Authorize to the Amazon account.
  7. Select Region to pull data from North America (NA), Europe (EU), Far East (FE). See docs for more details.
  8. Start Date (Optional) is used for generating reports starting from the specified start date. Use YYYY-MM-DD format. If not specified, the connector defaults to yesterday's date (UTC). Dates older than 60 days are automatically adjusted to 60 days ago, because Amazon Ads does not retain report data beyond that window. The date is treated in the timezone of the processed profile.
  9. Profile IDs (Optional) you want to fetch data for. The Amazon Ads source connector supports only profiles with seller and vendor type, profiles with agency type will be ignored. See docs for more details.
  10. Marketplace IDs (Optional) you want to fetch data for. Note: If Profile IDs are also selected, profiles will be selected if they match the Profile ID OR the Marketplace ID.
  11. Look Back Window (Optional) is the number of days the connector re-syncs on each run to capture late-arriving data. Defaults to 3. Increase this value if your reports frequently receive delayed updates.
  12. Number of concurrent threads (Optional) controls how many report requests the connector runs in parallel. Defaults to 14, with a minimum of 2 and a maximum of 20. See Rate limits before you change it.
  13. Click Set up source.

For Airbyte Open Source:​

  1. Navigate to the Airbyte Open Source dashboard.
  2. Set the name for your source.
  3. Client ID of your Amazon Ads developer application. See onboarding process for more details.
  4. Client Secret of your Amazon Ads developer application. See onboarding process for more details.
  5. Refresh Token. See onboarding process for more details.
  6. Select Region to pull data from North America (NA), Europe (EU), Far East (FE). See docs for more details.
  7. Start Date (Optional) is used for generating reports starting from the specified start date. Use YYYY-MM-DD format. If not specified, the connector defaults to yesterday's date (UTC). Dates older than 60 days are automatically adjusted to 60 days ago, because Amazon Ads does not retain report data beyond that window. The date is treated in the timezone of the processed profile.
  8. Profile IDs (Optional) you want to fetch data for. The Amazon Ads source connector supports only profiles with seller and vendor type, profiles with agency type will be ignored. See docs for more details.
  9. Marketplace IDs (Optional) you want to fetch data for. Note: If Profile IDs are also selected, profiles will be selected if they match the Profile ID OR the Marketplace ID.
  10. Look Back Window (Optional) is the number of days the connector re-syncs on each run to capture late-arriving data. Defaults to 3. Increase this value if your reports frequently receive delayed updates.
  11. Number of concurrent threads (Optional) controls how many report requests the connector runs in parallel. Defaults to 14, with a minimum of 2 and a maximum of 20. See Rate limits before you change it.
  12. Click Set up source.
note

The Amazon Ads source connector supports only seller and vendor profile types. Profiles with the agency type are not compatible with the Sponsored Products, Sponsored Brands, and Sponsored Display APIs and will be ignored. See Amazon Ads profile documentation for more details.

Both view and edit access levels are supported. Accounts with view-only permissions (common for Vendor Central accounts) will retrieve profiles and sync data normally.

Supported sync modes​

The Amazon Ads source connector supports the following sync modes:

  • Full Refresh
  • Incremental

Supported Streams​

This source is capable of syncing the following streams:

note

The Attribution report streams (attribution_report_products, attribution_report_performance_adgroup, attribution_report_performance_campaign, and attribution_report_performance_creative) require Amazon Attribution access on each Amazon Ads profile. Profiles without Attribution access are silently skipped, and the sync continues with the remaining authorized profiles. If a sync produces no Attribution records, verify that Amazon Attribution is enabled on at least one profile in your account.

note

As of connector version 5.0.0, the Sponsored Products Ad Group Bid Recommendations stream provides bid recommendations and impact metrics for an existing automatic targeting ad group. The stream returns bid recommendations for match types CLOSE_MATCH, LOOSE_MATCH, SUBSTITUTES, and COMPLEMENTS per theme. For more detail on theme-based bid recommendations, review Amazon's Theme-base bid suggestions - Quick-start guide.

Connector-specific features and highlights​

All the reports are generated relative to the target profile's timezone.

Campaign reports may sometimes have no data or may not appear in records. This can occur when there are no clicks or views associated with the campaigns on the requested day. For details, see Why is my report empty?

Amazon Ads retains report data for 60 days. The connector automatically caps the start date to 60 days ago, so any configured or saved start date older than that is adjusted at sync time. For details, see Get started with v3 reporting.

Report stream variants​

Each report stream is available in two variants:

  • A summary variant (for example, sponsored_brands_v3_report_stream) that uses timeUnit=SUMMARY. These streams use reportDate as the primary key and cursor, where reportDate reflects the end of the report's time window.
  • A daily variant with a _daily suffix (for example, sponsored_brands_v3_report_stream_daily) that uses timeUnit=DAILY for more granular, per-day data. As of connector version 8.0.0, daily variants use the API-native date field (the actual report date) as the primary key and cursor. If you are upgrading from an earlier version, see the migration guide.

For more information on time units, see the Amazon Ads documentation on timeUnit and supported columns.

warning

Amazon may incorrectly detect duplicate report requests when syncing both summary and daily versions of the same report type simultaneously (for example, sponsored_brands_v3_report_stream and sponsored_brands_v3_report_stream_daily). If you encounter this issue, create a separate source with only the needed report streams and set the Number of concurrent threads to 2 to ensure sequential processing.

The connector provides four types of Sponsored Brands V3 reports, each using a different Amazon Ads report type:

Stream prefixReport typeUse case
sponsored_brands_v3_report_streamsbPurchasedProductPurchased-product attribution data. Does not include cost, clicks, or impressions.
sponsored_brands_campaigns_report_streamsbCampaignsCampaign-level spend, traffic, conversion, and video metrics.
sponsored_brands_adgroups_report_streamsbAdGroupAd-group-level spend, traffic, conversion, and video metrics.
sponsored_brands_ads_report_streamsbAdsAd-level metrics, keyed by adId. Join to sponsored_brands_ads to attribute metrics to a creative.

Each stream above is available in both summary and daily variants.

Identifying Sponsored Brands Video campaigns​

Sponsored Brands V3 reports do not carry a creative-type or ad-format column. Creative type moved to the ad entity when Amazon released Sponsored Brands V4, so use the sponsored_brands_ads stream: its creative.type field is one of AUTO_COLLECTION, BRAND_VIDEO, MANUAL_COLLECTION, PRODUCT_COLLECTION, STORE_SPOTLIGHT, or VIDEO. Join sponsored_brands_ads.adId to sponsored_brands_ads_report_stream.adId to split reporting by creative type.

The connector does not set creativeVersionToReturn on the ads request, so Amazon returns its default LATEST creative for each ad — the newest revision, which may still be moderation-pending or rejected rather than the one that served during the report period. creative.type is fixed when an ad is created and is unaffected, but the editable fields (creative.headline, creative.asins, creative.customImageUrl, and so on) can describe an unapproved revision. Filter on creative.creativeStatus and creative.creativeVersion, both of which the stream emits, if you need only the serving creative.

note

Amazon types adId as a string on the ads entity API but as an integer in reporting v3, so the two streams land with different column types in your destination. Cast one side when joining — for example ... ON CAST(ads.adId AS STRING) = CAST(rpt.adId AS STRING). The same applies to adGroupId and campaignId.

The same cast is needed between two report streams. sponsored_brands_ads_report_stream declares campaignId, adGroupId, and adId as integers, matching Amazon's reporting v3 column reference. sponsored_brands_campaigns_report_stream and sponsored_brands_adgroups_report_stream still declare campaignId and adGroupId as strings; that typing predates these streams and cannot be corrected without a breaking schema change, so it is scheduled for the next major version. Until then, cast both sides when rolling ad-level metrics up to ad group or campaign level.

Ads that belong to a legacy version 3 (non-multi-ad-group) Sponsored Brands campaign carry no adId and no name — Amazon lists only adGroupId, campaignId, and state as required on the Ad object and repeats the caveat in Managing Sponsored Brands campaigns. Those rows arrive with adId null, so they never match the join above, and the sponsored_brands_ads primary key (campaignId + adGroupId + adId) effectively degrades to campaignId + adGroupId for them — pick a deduplicating destination sync mode for this stream only if one row per (campaignId, adGroupId) is acceptable for your legacy campaigns. This is the same population the sbAds preview excludes (see the warning below), so while the preview is in effect those ads have no report rows to join to anyway.

The sbCampaigns, sbAdGroup, and sbAds reports carry the video metrics that the removed V2 sponsored_brands_video_report_stream returned. These are video-only metrics, so they are populated only for video creatives. Amazon does not offer every metric on every report type:

MetricsbCampaignssbAdGroupsbAds
video5SecondViews, video5SecondViewRate, videoCompleteViews, videoFirstQuartileViews, videoMidpointViews, videoThirdQuartileViews, videoUnmutes✅✅✅
viewabilityRate (V2 vtr)✅✅✅
viewableImpressions✅—✅
viewClickThroughRate (V2 vctr)✅——

Amazon's own references disagree on three of those cells. The ad group and ad report-type pages leave viewableImpressions and viewClickThroughRate out of the sbAdGroup metric list and viewClickThroughRate out of the sbAds list, while the column reference lists sbAdGroups and sbAds under the "Report types" of both metrics. The connector follows the report-type pages, because Amazon rejects an entire report request when one column is not accepted for that report type, so guessing wrong returns no rows at all rather than one empty column. If you need these metrics at the ad group or ad level, open an issue and we will confirm against a live account.

warning

Amazon ships the sbCampaigns, sbAdGroup, and sbAds report types in preview. While they are in preview, Amazon excludes all data for Sponsored Brands campaigns whose isMultiAdGroupsEnabled flag is false, as noted on the campaign, ad group, and ad report-type pages. Those campaigns return no rows and the sync still succeeds, so the gap is silent. Sync the sponsored_brands_campaigns stream and check its isMultiAdGroupsEnabled field to see which of your campaigns are excluded; enabling multiple ad groups on a campaign in the Amazon Ads console brings it into V3 reporting. When a campaign becomes V3-eligible — because you enabled multiple ad groups, or because Amazon ends the preview — clear the state of the affected report streams and resync. These streams are incremental with a 3-day lookback (look_back_window), so without a state reset they resume from the current cursor and the newly-available history inside Amazon's 60-day retention window is never fetched. sponsored_brands_v3_report_stream (sbPurchasedProduct) is not in preview and is unaffected.

Performance considerations​

Report generation can take up to three hours. For details, see the Amazon Ads developer notes.

Rate Limits​

The Amazon Ads API uses dynamic rate limiting that varies by region and system load. Rate limits are not publicly documented with specific numbers. For more details, see the Amazon Ads API Rate Limiting documentation.

Adjusting Concurrency Settings:

The Number of concurrent threads setting defaults to 14 and accepts values from 2 to 20.

If you experience rate limiting errors (429 status codes) during syncs, decrease this setting to reduce the load on the API.

If you need better sync performance and are not experiencing rate limiting errors, increase it to improve throughput.

Data type map​

Integration TypeAirbyte Type
stringstring
int, float, numbernumber
datedate
datetimedatetime
arrayarray
objectobject

IP allow list​

If you use Airbyte Cloud and your organization restricts access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.

Reference​

Config fields reference

Field
Type
Property name
string
client_id
string
client_secret
string
refresh_token
"oauth2.0"
auth_type
integer
look_back_window
array<string>
marketplace_ids
integer
num_workers
array<integer>
profiles
string
region
string
start_date

Changelog​

Expand to review
VersionDatePull RequestSubject
9.1.12026-08-2684981Bump base image to source-declarative-manifest 7.28.2
9.1.02026-08-2083744Add sponsored_brands_ads (POST /sb/v4/ads/list), sponsored_brands_ads_report_stream, and sponsored_brands_ads_report_stream_daily; request the full documented column set for the sbCampaigns, sbAdGroup, and sbAds report types, which restores the removed V2 sponsored_brands_video_report_stream video metrics in full on sbCampaigns, all but viewClickThroughRate (V2 vctr) on sbAds, and all but viewClickThroughRate and viewableImpressions on sbAdGroup — Amazon's report-type pages do not list those columns for those report types, and the V2 keyword grain has no V3 equivalent (see Identifying Sponsored Brands Video campaigns); add goal, isMultiAdGroupsEnabled, kpi, siteRestrictions, and targetedPGDealId to the sponsored_brands_campaigns schema; retry throttling and server errors on the entity streams instead of treating them as an empty page. All changes are additive — refresh the source schema in each connection to pick up the new fields.
9.0.72026-08-1183379Update dependencies
9.0.62026-07-2882817Update dependencies
9.0.52026-07-2182341Update dependencies
9.0.42026-07-1481732Update dependencies
9.0.32026-07-0181333Use min_datetime to cap report start date to Amazon's 60-day data retention limit, fixing off-by-one that requested 61 days back
9.0.22026-06-3080957Update dependencies
9.0.12026-06-2380363Update dependencies
9.0.02026-06-1880201Migrate sponsored_product_ad_group_suggested_keywords stream from deprecated V2 Suggested Keywords API to Keyword Recommendations API (/sp/targets/keywords/recommendations).
8.1.42026-06-1880175Fixed sponsored_display_targets_report_stream_daily schema: moved date field into properties block so the primary key is recognized by destinations
8.1.32026-06-1779679Add accessLevel=view to profiles endpoint so Vendor Central accounts with view-level OAuth grants return profiles
8.1.22026-06-1679761Update dependencies
8.1.12026-06-0979217Update dependencies
8.1.02026-06-0278487Added Sponsored Brands campaign and ad group report streams with spend and performance metrics.
8.0.42026-06-0278596Update dependencies
8.0.32026-05-1878162Promoted release candidate to GA
8.0.3-rc.22026-05-1378055Concurrency tuning iteration 2: bump default num_workers from 12 to 14 for progressive rollout
8.0.3-rc.12026-05-1178010Concurrency tuning iteration 1: bump default num_workers from 10 to 12 for progressive rollout
8.0.22026-05-0577660Skip profiles without Amazon Attribution access on attribution report performance streams instead of failing the sync
8.0.12026-04-2877149Update dependencies
8.0.02026-04-2275490Use date field from API response as cursor and primary key for daily report streams instead of synthetic reportDate. Fixes ~96% data loss from incorrect deduplication.
7.3.192026-04-2176501Update dependencies
7.3.182026-04-1576333Fix cursorId pagination for all attribution report streams: ensure cursorId remains a string and stop pagination on null cursor
7.3.172026-04-1376276Rename "concurrent workers" to "concurrent threads" in connector spec
7.3.162026-03-3074313Fix profile ID type mismatch in record filter
7.3.152026-03-1774975Update dependencies
7.3.142026-02-2473761Update dependencies
7.3.132026-02-1073018Update dependencies
7.3.122026-01-1471502Update dependencies
7.3.112026-01-1271266Cap start date to 60 days to match Amazon Ads API limitation
7.3.102025-12-1970937Update dependencies
7.3.92025-12-1169836Increase max concurrency to 20 and add rate limits documentation
7.3.82025-11-2569911Update dependencies
7.3.72025-10-2969040Update dependencies
7.3.62025-10-2168579Raise report creation errors as customer config errors instead of system errors.
7.3.52025-09-3066760Update dependencies
7.3.42025-09-0965992Update to CDK v7
7.3.32025-09-0966032Update dependencies
7.3.22025-08-0964654Update dependencies
7.3.12025-07-1960633Update dependencies
7.3.02025-07-0762839Promoting release candidate 7.3.0-rc.1 to a main version.
7.3.0-rc.12025-06-2661707Convert to manifest-only format
7.2.32025-06-2361652Add error handling for 425 errors With Report Streams & Configurable Concurrency Levels
7.2.22025-05-1059332Update dependencies
7.2.12025-04-2855745Enable max concurrent async job count configurability
7.2.02025-04-2859121Promoting release candidate 7.2.0-rc.2 to a main version & 7.2.0-rc.1 since they were merged at the same time.
7.2.0-rc.22025-04-2358610Used latest version of Python cdk (6.45.10)
7.2.0-rc.12025-04-2255217Add daily versions of reports streams & Auto-update start_date if past lookback window
7.1.72025-04-1257591Update dependencies
7.1.62025-04-0557138Update dependencies
7.1.52025-03-2956554Update dependencies
7.1.42025-03-2256155Update dependencies
7.1.32025-03-0855352Update dependencies
7.1.22025-02-2453692Added handling 401 error for Polling Requester
7.1.12025-03-0154895Update dependencies
7.1.02025-02-2453692Migrate stream Portfolios to Portfolios API v3
7.0.12025-02-2252918Update dependencies
7.0.02025-02-0648449Migrate *-report streams to low-code
6.2.72025-01-2552210Update dependencies
6.2.62025-01-1851722Update dependencies
6.2.52025-01-1151239Update dependencies
6.2.42025-01-0450902Update dependencies
6.2.32024-12-2850478Update dependencies
6.2.22024-12-2150202Update dependencies
6.2.12024-12-1448229Starting with this version, the Docker image is now rootless. Please note that this and future versions will not be compatible with Airbyte versions earlier than 0.64
6.2.02024-11-1248116Migrate REST streams to low-code
6.1.42024-11-1248471Bumped automatically in the pull request, please see PR description
6.1.32024-11-0548343Set is_resumable only for FullRefresh streams
6.1.22024-11-0448138Add error message for TooManyRequests exception
6.1.12024-11-0448128Fix date parse in report streams
6.1.02024-11-0147940Bump CDK to ^5
6.0.02024-10-2847366Migrate stream SponsoredDisplayReportStream to Amazon Ads Reports v3
5.0.202024-10-2947032Update dependencies
5.0.192024-10-1246860Update dependencies
5.0.182024-10-0546451Update dependencies
5.0.172024-09-2845794Update dependencies
5.0.162024-09-1445548Update dependencies
5.0.152024-09-0745308Update dependencies
5.0.142024-08-3145051Update dependencies
5.0.132024-08-2444648Update dependencies
5.0.122024-08-1743845Update dependencies
5.0.112024-08-1243354Fix download request for sponsored_products_report_stream
5.0.102024-08-1042162Update dependencies
5.0.92024-07-1341876Update dependencies
5.0.82024-07-1041487Update dependencies
5.0.72024-07-0941143Update dependencies
5.0.62024-07-0640798Update dependencies
5.0.52024-06-2540403Update dependencies
5.0.42024-06-2139926Update dependencies
5.0.32024-06-0438962[autopull] Upgrade base image to v1.2.1
5.0.22024-05-2938737Update authenticator to requests_native_auth package
5.0.12024-04-2937655Update error messages and spec with info about agency profile type.
5.0.02024-03-2236169Update SponsoredBrand and SponsoredProduct streams due to API endpoint deprecation
4.1.02024-03-1936267Pin airbyte-cdk version to ^0
4.0.42024-02-2335481Migrate source to YamlDeclarativeSource with custom check_connection
4.0.32024-02-1235180Manage dependencies with Poetry
4.0.22024-02-0835013Add missing field to sponsored_display_budget_rules stream
4.0.12023-12-2833833Updated oauth spec to put region, so we can choose oauth consent url based on it
4.0.02023-12-2833817Fix schema for streams: SponsoredBrandsAdGroups and SponsoredBrandsKeywords
3.4.22023-12-1233361Fix unexpected crash when handling error messages which don't have requestId field
3.4.12023-10-1931599Base image migration: remove Dockerfile and use the python-connector-base image
3.4.02023-06-0926203Add Stream DisplayCreatives
3.3.02023-09-2230679Fix unexpected column for SponsoredProductCampaigns and SponsoredBrandsKeywords
3.2.02023-09-1830517Add suggested streams; fix unexpected column issue
3.1.22023-08-1629233Add filter for Marketplace IDs
3.1.12023-08-2829900Add 404 handling for no associated with bid ad groups
3.1.02023-08-0829212Add T00030 tactic support for sponsored_display_report_stream
3.0.02023-07-2427868Fix attribution report stream schemas
2.3.12023-07-1128155Bugfix: validation error when record values are missing
2.3.02023-07-0628002Add sponsored_product_ad_group_suggested_keywords, sponsored_product_ad_group_bid_recommendations streams
2.2.02023-07-0527607Add stream for sponsored brands v3 purchased product reports
2.1.02023-06-1925412Add sponsored_product_campaign_negative_keywords, sponsored_display_budget_rules streams
2.0.02023-05-3125874Type portfolioId as integer
1.1.02023-04-2225412Add missing reporting metrics
1.0.62023-05-0925913Small schema fixes
1.0.52023-05-0825885Improve error handling for attribution_report(s) streams
1.0.42023-05-0425792Add availability strategy for basic streams (not including report streams)
1.0.32023-04-1325146Validate pk for reports when expected pk is not returned
1.0.22023-02-0322355Migrate products_report stream to API v3
1.0.12022-11-0118677Add optional config report_record_types
1.0.02023-01-3021677Fix bug with non-unique primary keys in report streams. Add asins_keywords and asins_targets
0.1.292023-01-2722038Set AvailabilityStrategy for streams explicitly to None
0.1.282023-01-1819491Add option to customize look back window value
0.1.272023-01-0521082Fix bug with handling: "Report date is too far in the past." - partial revert of #20662
0.1.262022-12-1920662Fix bug with handling: "Report date is too far in the past."
0.1.252022-11-0818985Remove "report_wait_timeout", "report_generation_max_retries" from config
0.1.242022-10-1917475Add filters for state on brand, product and display campaigns
0.1.232022-09-0616342Add attribution reports
0.1.222022-09-2817304Migrate to per-stream state.
0.1.212022-09-2717202Improved handling if known reporting errors
0.1.202022-09-0816453Increase report_wait_timeout 30 -> 60 minutes
0.1.192022-08-3116191Improved connector's input configuration validation
0.1.182022-08-2515951Skip API error "Tactic T00020 is not supported for report API in marketplace A1C3SOZRARQ6R3."
0.1.172022-08-2415921Skip API error "Report date is too far in the past."
0.1.162022-08-2315822Set default value for region if needed
0.1.152022-08-2015816Update STATE of incremental sync if no records
0.1.142022-08-1515637Generate slices by lazy evaluation
0.1.122022-08-0915469Define primary_key for all report streams
0.1.112022-07-2815031Improve report streams date-range generation
0.1.102022-07-2615042Update additionalProperties field to true from schemas
0.1.92022-05-0812541Improve documentation for Beta
0.1.82022-05-0412482Update input configuration copy
0.1.72022-04-2711730Update fields in source-connectors specifications
0.1.62022-04-2011659Add adId to products report
0.1.52022-04-0811430Add support OAuth2.0
0.1.42022-02-2110513Increasing REPORT_WAIT_TIMEOUT for supporting report generation which takes longer time
0.1.32021-12-288388Add retry if recoverable error occurred for reporting stream processing
0.1.22021-10-016461Add option to pull data for different regions. Add option to choose profiles we want to pull data. Add lookback
0.1.12021-09-226367Add seller and vendor filters to profiles stream
0.1.02021-08-135023Initial version
Was this page helpful?