Amazon Ads

The amazon_ads connector reads profiles, Sponsored Products (SP) campaigns, ad groups, product ads, and keywords from the Amazon Advertising API using Login with Amazon (LWA) OAuth credentials. It runs on StreamWright's declarative HTTP Transport (transport = "http").

Auth & HTTP Configuration

Amazon Advertising uses LWA (Login with Amazon) OAuth2 refresh tokens. StreamWright automatically exchanges and refreshes the short-lived access token using type: oauth2_refresh_token:

source.yaml

kind: source
name: amazon_ads_demo

spec:
  config:
    api_url:
      type: string
      default: "https://advertising-api.amazon.com"
      description: "Regional endpoint: https://advertising-api.amazon.com (NA), https://advertising-api-eu.amazon.com (EU), https://advertising-api-fe.amazon.com (FE)"
    profile_id:
      type: string
      required: false
      description: "Amazon Advertising Profile ID (sent as Amazon-Advertising-API-Scope)"
  secrets:
    amazon_client_id: { type: string }
    amazon_client_secret: { type: string }
    amazon_refresh_token: { type: string }

auth:
  provider: amazon_ads
  type: oauth2_refresh_token
  token_url: https://api.amazon.com/auth/o2/token
  client_id: "{{ secrets.amazon_client_id }}"
  client_secret: "{{ secrets.amazon_client_secret }}"
  refresh_token: "{{ secrets.amazon_refresh_token }}"

http:
  base_url: "{{ config.api_url }}"
  headers:
    Amazon-Advertising-API-ClientId: "{{ secrets.amazon_client_id }}"
    Amazon-Advertising-API-Scope: "{{ config.profile_id }}"
  paginator:
    type: offset
    offset_param: startIndex
    limit_param: count
    page_size: 100

Client secrets and refresh tokens are registered as secrets at connection time and redacted in log messages.

Reading data

Each stream queries its corresponding Sponsored Products endpoint, inheriting LWA authorization, client headers, and offset pagination (startIndex / count):

streams/sp_campaigns.yaml

description: Amazon Sponsored Products campaigns metadata and budgets.

requests:
  - name: raw_sp_campaigns
    http:
      path: /v2/sp/campaigns
      method: GET

transform:
  mode: page
  steps:
    - name: sp_campaigns
      select: |
        SELECT record->>'campaignId'                      AS campaign_id,
               record->>'name'                            AS campaign_name,
               record->>'campaignType'                    AS campaign_type,
               record->>'targetingType'                   AS targeting_type,
               record->>'state'                           AS state,
               (record->>'dailyBudget')::DOUBLE           AS daily_budget,
               record->>'startDate'                       AS start_date,
               record->>'endDate'                         AS end_date,
               (record->>'premiumBidAdjustment')::BOOLEAN AS premium_bid_adjustment
        FROM raw_sp_campaigns

export:
  sp_campaigns:
    step: sp_campaigns
    primary_key: [campaign_id]

Reference streams (examples)

The starter template (examples/sources/ads/amazon_ads) includes the following reference streams:

Stream	Description	Endpoint
profiles	Advertising profiles, marketplaces, and timezones	/v2/profiles
sp_campaigns	Sponsored Products campaigns, states, and daily budgets	/v2/sp/campaigns
sp_ad_groups	Sponsored Products ad groups and default bids	/v2/sp/adGroups
sp_ads	Sponsored Products product ads (SKU and ASIN)	/v2/sp/productAds
sp_keywords	Sponsored Products targeted keywords and match types	/v2/sp/keywords

Customizable Streams

These streams are reference examples. Because streams in StreamWright are declarative, you can customize columns, adjust DuckDB queries, or add new endpoints to match your upstream reporting needs.

All collection endpoints support automatic pagination and retry on transient rate limits (HTTP 429).