Availability

Airbyte Cloud Airbyte OSS PyAirbyte

Support Level

Certified

Latest Version

5.0.0

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. In the left navigation bar, click Sources. In the top-right corner, click + new source.
3. On the source setup page, select Amazon Ads from the Source type dropdown and enter a name for this connector.
4. Click Authenticate your Amazon Ads account.
5. Log in and Authorize to the Amazon account.
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. 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. 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.

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:

• Profiles
• Portfolios
• Sponsored Brands Campaigns
• Sponsored Brands Ad groups
• Sponsored Brands Keywords
• Sponsored Display Campaigns
• Sponsored Display Ad groups
• Sponsored Display Product Ads
• Sponsored Display Targetings
• Sponsored Display Creatives
• Sponsored Display Budget Rules
• Sponsored Products Campaigns
• Sponsored Products Ad groups
• Sponsored Products Ad Group Bid Recommendations
• Sponsored Products Ad Group Suggested Keywords
• Sponsored Products Keywords
• Sponsored Products Negative keywords
• Sponsored Products Campaign Negative keywords
• Sponsored Products Ads
• Sponsored Products Targetings
• Brands Reports
• Brand Video Reports
• Display Reports (Contextual targeting only)
• Products Reports
• Attribution Reports

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 mapping

Integration Type	Airbyte Type
string	string
int, float, number	number
date	date
datetime	datetime
array	array
object	object

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

Version	Date	Pull Request	Subject
5.0.0	2024-03-22	36169	Update SponsoredBrand and SponsoredProduct streams due to API endpoint deprecation
4.1.0	2024-03-19	36267	Pin airbyte-cdk version to ^0
4.0.4	2024-02-23	35481	Migrate source to YamlDeclarativeSource with custom check_connection
4.0.3	2024-02-12	35180	Manage dependencies with Poetry
4.0.2	2024-02-08	35013	Add missing field to sponsored_display_budget_rules stream
4.0.1	2023-12-28	33833	Updated oauth spec to put region, so we can choose oauth consent url based on it
4.0.0	2023-12-28	33817	Fix schema for streams: SponsoredBrandsAdGroups and SponsoredBrandsKeywords
3.4.2	2023-12-12	33361	Fix unexpected crash when handling error messages which don't have requestId field
3.4.1	2023-10-19	31599	Base image migration: remove Dockerfile and use the python-connector-base image
3.4.0	2023-06-09	25913	Add Stream DisplayCreatives
3.3.0	2023-09-22	30679	Fix unexpected column for SponsoredProductCampaigns and SponsoredBrandsKeywords
3.2.0	2023-09-18	30517	Add suggested streams; fix unexpected column issue
3.1.2	2023-08-16	29233	Add filter for Marketplace IDs
3.1.1	2023-08-28	29900	Add 404 handling for no associated with bid ad groups
3.1.0	2023-08-08	00000	Add T00030 tactic support for sponsored_display_report_stream
3.0.0	2023-07-24	27868	Fix attribution report stream schemas
2.3.1	2023-07-11	28155	Bugfix: validation error when record values are missing
2.3.0	2023-07-06	28002	Add sponsored_product_ad_group_suggested_keywords, sponsored_product_ad_group_bid_recommendations streams
2.2.0	2023-07-05	27607	Add stream for sponsored brands v3 purchased product reports
2.1.0	2023-06-19	25412	Add sponsored_product_campaign_negative_keywords, sponsored_display_budget_rules streams
2.0.0	2023-05-31	25874	Type portfolioId as integer
1.1.0	2023-04-22	25412	Add missing reporting metrics
1.0.6	2023-05-09	25913	Small schema fixes
1.0.5	2023-05-08	25885	Improve error handling for attribution_report(s) streams
1.0.4	2023-05-04	25792	Add availability strategy for basic streams (not including report streams)
1.0.3	2023-04-13	25146	Validate pk for reports when expected pk is not returned
1.0.2	2023-02-03	22355	Migrate products_report stream to API v3
1.0.1	2022-11-01	18677	Add optional config report_record_types
1.0.0	2023-01-30	21677	Fix bug with non-unique primary keys in report streams. Add asins_keywords and asins_targets
0.1.29	2023-01-27	22038	Set AvailabilityStrategy for streams explicitly to None
0.1.28	2023-01-18	19491	Add option to customize look back window value
0.1.27	2023-01-05	21082	Fix bug with handling: "Report date is too far in the past." - partial revert of #20662
0.1.26	2022-12-19	20662	Fix bug with handling: "Report date is too far in the past."
0.1.25	2022-11-08	18985	Remove "report_wait_timeout", "report_generation_max_retries" from config
0.1.24	2022-10-19	17475	Add filters for state on brand, product and display campaigns
0.1.23	2022-09-06	16342	Add attribution reports
0.1.22	2022-09-28	17304	Migrate to per-stream state.
0.1.21	2022-09-27	17202	Improved handling if known reporting errors
0.1.20	2022-09-08	16453	Increase report_wait_timeout 30 -> 60 minutes
0.1.19	2022-08-31	16191	Improved connector's input configuration validation
0.1.18	2022-08-25	15951	Skip API error "Tactic T00020 is not supported for report API in marketplace A1C3SOZRARQ6R3."
0.1.17	2022-08-24	15921	Skip API error "Report date is too far in the past."
0.1.16	2022-08-23	15822	Set default value for region if needed
0.1.15	2022-08-20	15816	Update STATE of incremental sync if no records
0.1.14	2022-08-15	15637	Generate slices by lazy evaluation
0.1.12	2022-08-09	15469	Define primary_key for all report streams
0.1.11	2022-07-28	15031	Improve report streams date-range generation
0.1.10	2022-07-26	15042	Update additionalProperties field to true from schemas
0.1.9	2022-05-08	12541	Improve documentation for Beta
0.1.8	2022-05-04	12482	Update input configuration copy
0.1.7	2022-04-27	11730	Update fields in source-connectors specifications
0.1.6	2022-04-20	11659	Add adId to products report
0.1.5	2022-04-08	11430	Add support OAuth2.0
0.1.4	2022-02-21	10513	Increasing REPORT_WAIT_TIMEOUT for supporting report generation which takes longer time
0.1.3	2021-12-28	8388	Add retry if recoverable error occurred for reporting stream processing
0.1.2	2021-10-01	6367	Add option to pull data for different regions. Add option to choose profiles we want to pull data. Add lookback
0.1.1	2021-09-22	6367	Add seller and vendor filters to profiles stream
0.1.0	2021-08-13	5023	Initial version