Skip to main content

Amazon Ads

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)

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. This should be in YYYY-MM-DD format and not more than 60 days in the past. If a date is not specified, today's date is used. 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. 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. This should be in YYYY-MM-DD format and not more than 60 days in the past. If a date is not specified, today's date is used. 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. Click Set up source.

For Airbyte Open Source:

  1. Client ID of your Amazon Ads developer application. See onboarding process for more details.
  2. Client Secret of your Amazon Ads developer application. See onboarding process for more details.
  3. Refresh Token. See onboarding process for more details.
  4. Select Region to pull data from North America (NA), Europe (EU), Far East (FE). See docs for more details.
  5. Start Date (Optional) is used for generating reports starting from the specified start date. This should be in YYYY-MM-DD format and not more than 60 days in the past. If a date is not specified, today's date is used. The date is treated in the timezone of the processed profile.
  6. 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.
  7. 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.
note

The Amazon Ads source connector uses Sponsored Products, Sponsored Brands, and Sponsored Display APIs which are not compatible with agency account type. See docs for more details. If you have only agency profile, please use accounts associated with the profile of seller/vendor type.

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

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 be presenting in records. This can occur when there are no clicks or views associated with the campaigns on the requested day - details.

Report data synchronization only covers the last 60 days - details.

Performance considerations

Information about expected report generation waiting time can be found here.

Data type map

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

Reference

Config fields reference

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

Changelog

Expand to review
VersionDatePull RequestSubject
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-0925913Add 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-016367Add 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