Skip to main content

Amazon Ads

This connector captures data from Amazon Ads into Flow collections via the Amazon Ads API.

It is available for use in the Flow web application. For local development or open-source workflows, ghcr.io/estuary/source-amazon-ads:dev provides the latest version of the connector as a Docker image. You can also follow the link in your browser to see past image versions.

This connector is based on an open-source connector from a third party, with modifications for performance in the Flow system. You can find their documentation here, but keep in mind that the two versions may be significantly different.

Supported data resources

The following data resources are supported:

By default, each resource is mapped to a Flow collection through a separate binding.

Prerequisites

This connector uses OAuth2 to authenticate with Amazon. You can do this in the Flow web app, or configure manually if you're using the flowctl CLI.

Using OAuth2 to authenticate with Amazon in the Flow web app

You'll need an Amazon user account with access to the Amazon Ads account from which you wish to capture data.

You'll use these credentials to sign in.

Authenticating manually using the CLI

When you configure this connector manually, you provide the same credentials that OAuth2 would automatically fetch if you used the web app. These are:

  • Client ID
  • Client secret
  • Refresh token

To obtain these credentials:

  1. Complete the Amazon Ads API onboarding process.

  2. Retrieve your client ID and client secret.

  3. Retrieve a refresh token.

Selecting data region and profiles

When you configure the endpoint for this connector, you must choose an Amazon region from which to capture data. Optionally, you may also select profiles from which to capture data.

The region must be one of:

  • NA (North America)
  • EU (European Union)
  • FE (Far East)

These represent the three URL endpoints provided by Amazon through which you can access the marketing API. Each region encompasses multiple Amazon marketplaces, which are broken down by country. See the Amazon docs for details.

If you run your Amazon ads in multiple marketplaces, you may have separate profiles for each. If this is the case, you can specify the profiles from which you wish to capture data by supplying their profile IDs. Be sure to specify only profiles that correspond to marketplaces within the region you chose.

Configuration

You configure connectors either in the Flow web app, or by directly editing the catalog specification file. See connectors to learn more about using connectors. The values and specification sample below provide configuration details specific to the Amazon Ads source connector.

Properties

Endpoint

The properties in the table below reflect the manual authentication method. If you're working in the Flow web app, you'll use OAuth2, so many of these properties aren't required.

PropertyTitleDescriptionTypeRequired/Default
/credentialsobjectRequired
/credentials/auth_typeAuth TypeSet to oauth2.0 for manual integration (in this method, you're re-creating the same credentials of the OAuth user interface, but doing so manually)string
/credentials/client_idClient IDThe client ID of your Amazon Ads developer application.stringRequired
/credentials/client_secretClient SecretThe client secret of your Amazon Ads developer application.stringRequired
/credentials/refresh_tokenRefresh TokenAmazon Ads refresh token.stringRequired
/profilesProfile IDs (Optional)Profile IDs you want to fetch data for.array
/regionRegion *Region to pull data from (EU/NA/FE).string"NA"
/report_generation_max_retriesReport Generation Maximum Retries *Maximum retries the connector will attempt for fetching report data.integer5
/report_wait_timeoutReport Wait Timeout *Timeout duration in minutes for reports.integer60
/start_dateStart Date (Optional)The start date for collecting reports, in YYYY-MM-DD format. This should not be more than 60 days in the past.string

Bindings

PropertyTitleDescriptionTypeRequired/Default
/streamStreamAmazon Ads resource from which a collection is captured.stringRequired
/syncModeSync ModeConnection method.stringRequired

Sample

This sample specification reflects the manual authentication method.

captures:
${PREFIX}/${CAPTURE_NAME}:
endpoint:
connector:
image: ghcr.io/estuary/source-amazon-ads:dev
config:
credentials:
auth_type: oauth2.0
client_id: amzn1.application-oa2-client.XXXXXXXXX
client_secret: <secret>
refresh_token: Atzr|XXXXXXXXXXXX
region: NA
report_generation_max_retries: 5
report_wait_timeout: 60
start_date: 2022-03-01

bindings:
- resource:
stream: profiles
syncMode: full_refresh
target: ${PREFIX}/profiles
{}