Amazon Ads Migration Guide

Availability

Core Standard Plus Pro Enterprise Flex Self-Managed Enterprise PyAirbyte

Support Level

Airbyte

Connector Version

8.0.0 (last updated 2 days ago)

Definition ID

c6b0a29e-1da9-4512-9002-7bfd0cba2246

Upgrading to 8.0.0

Daily report streams now use the date field from the Amazon Ads API response as the cursor and primary key instead of the synthetic reportDate field.

Previously, all rows within a 30-day reporting window were incorrectly assigned the same reportDate value (the stream interval end date), causing approximately 96% of data to be lost during deduplication when using incremental + dedup sync mode. This version fixes the issue by using the actual date field returned by the API.

Affected streams

All daily report streams are affected:

• sponsored_brands_v3_report_stream_daily
• sponsored_display_campaigns_report_stream_daily
• sponsored_display_adgroups_report_stream_daily
• sponsored_display_productads_report_stream_daily
• sponsored_display_targets_report_stream_daily
• sponsored_display_asins_report_stream_daily
• sponsored_products_campaigns_report_stream_daily
• sponsored_products_adgroups_report_stream_daily
• sponsored_products_keywords_report_stream_daily
• sponsored_products_targets_report_stream_daily
• sponsored_products_productads_report_stream_daily
• sponsored_products_asins_keywords_report_stream_daily
• sponsored_products_asins_targets_report_stream_daily

Primary key and cursor changes

Change	Before	After
Cursor field	reportDate (synthetic)	date (from API response)
Primary key date component	reportDate	date

Non-daily (SUMMARY) report streams are not affected and continue to use reportDate.

note

The reportDate field is still present on daily stream records but is no longer used as the primary key or cursor. After this upgrade, reportDate on daily streams reflects the stream interval end date rather than the actual report date. Use the date field instead for accurate daily date values. Downstream queries or dashboards that reference reportDate on daily streams should be updated to use date.

Refresh affected schemas and reset data

1. Select Connections in the main nav bar.
   1. Select the connection(s) affected by the update.
2. Select the Schema tab.
   1. Select Refresh source schema.
   2. Select OK.

note

Any detected schema changes will be listed for your review.

1. Select Save changes at the top right of the page.
   1. Ensure the Reset affected streams option is checked.

note

Depending on destination type you may not be prompted to reset your data.

1. Select Save connection.

note

This will reset the data in your destination and initiate a fresh sync.

For more information on resetting your data in Airbyte, see this page.

Upgrading to 7.0.0

• The stream SponsoredDisplayReportStream is split into five:

  • sponsored_display_campaigns_report_stream
  • sponsored_display_adgroups_report_stream
  • sponsored_display_productads_report_stream
  • sponsored_display_targets_report_stream
  • sponsored_display_asins_report_stream

• The stream SponsoredProductsReportStream is split into seven:

  • sponsored_products_campaigns_report_stream
  • sponsored_products_adgroups_report_stream
  • sponsored_products_keywords_report_stream
  • sponsored_products_targets_report_stream
  • sponsored_products_productads_report_stream
  • sponsored_products_asins_keywords_report_stream
  • sponsored_products_asins_targets_report_stream

• Changes for all *-report streams:

  • They have new primary keys (see the following table).
  • metrics have been moved to the root of the schema.
  • metrics have been reset to the proper field type (previously, they were all stored as strings).

Primary Key changes

Stream Name	Old Primary Key	New Primary key
sponsored_brands_v3_report_stream	["profileId", "recordType", "reportDate", "recordId"]	["profileId", "reportDate", "purchasedAsin"]
SponsoredDisplayReportStream (deprecated)	["profileId", "recordType", "reportDate", "recordId"]
- sponsored_display_campaigns_report_stream		["profileId", "reportDate", "campaignId"]
- sponsored_display_adgroups_report_stream		["profileId", "reportDate", "adGroupId"]
- sponsored_display_productads_report_stream		["profileId", "reportDate", "adId"]
- sponsored_display_targets_report_stream		["profileId", "reportDate", "targetingId"]
- sponsored_display_asins_report_stream		["profileId", "reportDate", "promotedAsin"]
SponsoredProductsReportStream (deprecated)	["profileId", "recordType", "reportDate", "recordId"]
- sponsored_products_campaigns_report_stream		["profileId", "reportDate", "campaignId"]
- sponsored_products_adgroups_report_stream		["profileId", "reportDate", "adGroupId"]
- sponsored_products_keywords_report_stream		["profileId", "reportDate", "keywordId"]
- sponsored_products_targets_report_stream		["profileId", "reportDate", "keywordId"]
- sponsored_products_productads_report_stream		["profileId", "reportDate", "adId"]
- sponsored_products_asins_keywords_report_stream		["profileId", "reportDate", "advertisedAsin"]
- sponsored_products_asins_targets_report_stream		["profileId", "reportDate", "advertisedAsin"]

Upgrading to 6.0.0

The SponsoredDisplayReportStream stream now has an updated schema, thanks to a recent change in the Amazon Ads API. You can find more details in the Amazon Migration Guide (metrics).

Please note that SponsoredBrandsReportStream and SponsoredBrandsVideoReportStream will become unavailable as a result of the deprecation of API V2. We recommend switching to SponsoredBrandsV3ReportStream as a great alternative. see Amazon Migration Guide (metrics) for more info.

Streams SponsoredBrandsReportStream SponsoredBrandsVideoReportStream will become unavailable. It is recommended to use SponsoredBrandsV3ReportStream as an alternative.

Refresh affected schemas and reset data

1. Select Connections in the main navbar.
   1. Select the connection(s) affected by the update.
2. Select the Replication tab.
   1. Select Refresh source schema.
   2. Select OK.

Any detected schema changes will be listed for your review.

3. Select Save changes at the bottom of the page.
   1. Ensure the Reset affected streams option is checked.

Depending on destination type you may not be prompted to reset your data.

4. Select Save connection.

This will reset the data in your destination and initiate a fresh sync.

For more information on resetting your data in Airbyte, see this page.

Upgrading to 5.0.0

The following streams have updated schemas due to a change with the Amazon Ads API:

• SponsoredBrandsCampaigns
• SponsoredBrandsAdGroups
• SponsoredProductsCampaigns
• SponsoredProductsAdGroupBidRecommendations

Schema Changes - Removed/Added Fields

Stream Name	Removed Fields	Added Fields
SponsoredBrandsCampaigns	serviceStatus, bidOptimization, bidMultiplier, adFormat, bidAdjustments, creative, landingPage, supplySource	ruleBasedBudget, bidding, productLocation, costType, smartDefault, extendedData
SponsoredBrandsAdGroups	bid, keywordId, keywordText, nativeLanuageKeyword, matchType	extendedData
SponsoredProductsCampaigns	campaignType, dailyBudget, ruleBasedBudget, premiumBidAdjustment, networks	dynamicBidding, budget, extendedData
SponsoredProductsAdGroupBidRecommendations	suggestedBid	theme, bidRecommendationsForTargetingExpressions

Refresh affected schemas and reset data

1. Select Connections in the main navbar.
   1. Select the connection(s) affected by the update.
2. Select the Replication tab.
   1. Select Refresh source schema.
   2. Select OK.

Any detected schema changes will be listed for your review.

3. Select Save changes at the bottom of the page.
   1. Ensure the Reset affected streams option is checked.

Depending on destination type you may not be prompted to reset your data.

4. Select Save connection.

This will reset the data in your destination and initiate a fresh sync.

For more information on resetting your data in Airbyte, see this page.

Upgrading to 4.0.0

Streams SponsoredBrandsAdGroups and SponsoredBrandsKeywords now have updated schemas.

Refresh affected schemas and reset data

1. Select Connections in the main navbar.
   1. Select the connection(s) affected by the update.
2. Select the Replication tab.
   1. Select Refresh source schema.
   2. Select OK.

Any detected schema changes will be listed for your review.

3. Select Save changes at the bottom of the page.
   1. Ensure the Reset affected streams option is checked.

Depending on destination type you may not be prompted to reset your data.

4. Select Save connection.

This will reset the data in your destination and initiate a fresh sync.

For more information on resetting your data in Airbyte, see this page.

Upgrading to 3.0.0

A major update of attribution report stream schemas. For a smooth migration, a data reset and a schema refresh are needed.

Connector upgrade guide

Review the following information to prepare for and execute your upgrade.

Review the changelog

Before updating a connector, review the changelog to understand the changes and their potential impact on your existing connections. Find the changelog for any connector by navigating to the bottom of the documentation for that connector. Major version releases also include a migration guide.

Plan for major updates

Major updates may require you to adjust connection settings or even make changes to your data pipelines. Allocate enough time and resources for this. Use the migration guide to ensure your transition process goes smoothly.

Airbyte provides tooling that guarantees safe connector version bumps and enforces automated version bumps for minor and patch updates. You always need to manually update for major version bumps.

Self-managed plans: pin a specific version if you can't update

If you're unable to upgrade to the new version of a connector, you can pin that connector to a specific version.

1. In the navigation bar:

   • If you're on the Self-Managed Enterprise plan, click Organization settings > Sources/Destinations.

   • If you're on any other plan, click Workspace settings > Sources/Destinations.

2. Edit the entry for the connector you want to pin.

3. Set the Default Version to the version you want to use.

Self-managed plans: update the local connector image

If you self-manage Airbyte, you must manually update the connector image in your local registry before proceeding with the migration. Follow the steps below.

1. In the navigation bar:

   • If you're on the Self-Managed Enterprise plan, click Organization settings > Sources/Destinations.

   • If you're on any other plan, click Workspace settings > Sources/Destinations.

2. Find the connector you want to update in the list of connectors.

   note

   Airbyte lists two versions, the current in-use version and the latest version available.

3. Click Change to update your OSS version to the latest available version.

Update the connector version

Update each instance of the connector separately. If you have multiple instances of a connector, updating one doesn't affect the others.

1. In the navigation bar:

   • If you're on the Self-Managed Enterprise plan, click Organization settings > Sources/Destinations.

   • If you're on any other plan, click Workspace settings > Sources/Destinations.

2. Select the instance of the connector you wish to upgrade.

3. Select Upgrade.

4. Follow the prompt to confirm you are ready to upgrade to the new version.

Clear data from affected streams

After upgrading a connector with a breaking change, you must refresh affected schemas and clear your data.

1. In the nav bar, click Connections.

2. Find the connection affected by the upgrade.

3. Click the Schema tab.

4. Click Refresh source schema (looks like ). When Airbyte finishes, it shows you any detected schema changes.

5. Click OK.

6. Click Save changes

7. Clear the data for the streams affected by this upgrade.

Once the clear is complete, you can begin syncing your data again as usual.