Amazon Ads CLI

数据分析需配置 API Key

通过 amazon-ads-open-cli 拉取 Amazon 广告数据并生成报告，用于检查广告表现、提取 Sponsored Products/Brands/Display 等广告报告。

报表生成数据洞察网页抓取

346

下载量

安装量

收藏量

★ 5.0

综合评分ⓘ

概述

更多信息

Amazon Ads CLI Skill#

You have access to amazon-ads-open-cli, a read-only CLI for the Amazon Advertising API (v2/v3). Use it to list advertising profiles, inspect Sponsored Products/Brands/Display campaigns and their hierarchy, browse DSP orders and creatives, manage audiences, and request async performance reports across Amazon marketplaces.

Quick start#

bash

# Check if the CLI is available
amazon-ads-open-cli --help

# List advertising profiles (marketplaces)
amazon-ads-open-cli profiles

# List Sponsored Products campaigns
amazon-ads-open-cli sp-campaigns

If the CLI is not installed, install it:

bash

npm install -g amazon-ads-open-cli

Authentication#

The CLI requires an Amazon OAuth2 access token and client ID from a Login with Amazon app. Credentials are resolved in this order:

--credentials <path> flag (per-command) -- reads the specified JSON file
Auto-detected file: ~/.config/amazon-ads-open-cli/credentials.json
Environment variables: AMAZON_ADS_ACCESS_TOKEN + AMAZON_ADS_CLIENT_ID

Note: when a credentials file is found (either via --credentials or at the default path), its profile_id can be overridden by the AMAZON_ADS_PROFILE_ID environment variable if the file does not contain one. If the credentials file is not found or does not contain valid access_token + client_id, the CLI falls through to environment variables.

The credentials JSON file format:

json

{
  "access_token": "your_access_token",
  "client_id": "your_client_id",
  "profile_id": "your_profile_id"
}

Environment variables:

AMAZON_ADS_ACCESS_TOKEN -- OAuth2 access token
AMAZON_ADS_CLIENT_ID -- Login with Amazon client ID
AMAZON_ADS_PROFILE_ID -- marketplace profile ID (required for most commands)

Before running any command, verify credentials are configured by running amazon-ads-open-cli profiles. If it fails with a credentials error, ask the user to set up authentication.

Most commands require a profile ID (marketplace-specific). Use the profiles command first to discover profile IDs, then set AMAZON_ADS_PROFILE_ID.

Entity hierarchy#

text

Profile (marketplace: US, UK, DE, JP, etc.)
 +-- Sponsored Products
 |    +-- Campaign -> Ad Group -> Product Ad / Keyword / Target
 +-- Sponsored Brands
 |    +-- Campaign -> Ad Group -> Keyword / Target
 +-- Sponsored Display
 |    +-- Campaign -> Ad Group -> Product Ad / Target
 +-- DSP (programmatic)
      +-- Advertiser -> Order -> Line Item -> Creative
      +-- Audience (configured at Line Item level)

Output format#

All commands output pretty-printed JSON (2-space indent) by default. Use --format compact for single-line JSON (useful for piping).

Global options available on every command:

--format <format> -- output format: json (default) or compact
--credentials <path> -- path to credentials JSON file

All listing commands support offset-based pagination via --start-index and --count parameters.

Commands reference#

Profiles#

bash

# List all advertising profiles (marketplaces) -- no profile ID required
amazon-ads-open-cli profiles

# Get a specific profile -- no profile ID required
amazon-ads-open-cli profile 1234567890

The profiles and profile commands do not require AMAZON_ADS_PROFILE_ID to be set. All other commands do.

Performance reports (async)#

Reports are requested asynchronously. You submit a report request and receive a report ID, then poll for completion.

Report status

bash

# Check report status and get download URL
amazon-ads-open-cli report-status amzn1.report.abc123

The response includes the report status and, when complete, a download URL. Poll this command until the status indicates the report is ready.

DSP orders#

bash

# List DSP orders (programmatic display/video)
amazon-ads-open-cli dsp-orders
amazon-ads-open-cli dsp-orders --start-index 0 --count 50

# Get a specific DSP order
amazon-ads-open-cli dsp-order 123456

Options for dsp-orders:

--start-index <n> -- start index for pagination (default 0)
--count <n> -- results per page (default 100)

DSP commands use the v3 API endpoint.

DSP line items#

bash

# List DSP line items
amazon-ads-open-cli dsp-line-items
amazon-ads-open-cli dsp-line-items --order-id 123456

Options for dsp-line-items:

--order-id <id> -- filter by order ID
--start-index <n> -- start index for pagination (default 0)
--count <n> -- results per page (default 100)

DSP creatives#

bash

# List DSP creatives
amazon-ads-open-cli dsp-creatives
amazon-ads-open-cli dsp-creatives --start-index 0 --count 50

Options for dsp-creatives:

--start-index <n> -- start index for pagination (default 0)
--count <n> -- results per page (default 100)

Audiences#

bash

# List DSP audiences
amazon-ads-open-cli audiences
amazon-ads-open-cli audiences --start-index 0 --count 50

# Get a specific audience
amazon-ads-open-cli audience 123456

Options for audiences:

--start-index <n> -- start index for pagination (default 0)
--count <n> -- results per page (default 100)

Brand safety#

bash

# List brand safety deny lists
amazon-ads-open-cli brand-safety-lists

The brand-safety-lists command has no pagination options. It returns all deny lists.

Workflow guidance#

When the user asks for an account overview#

Run amazon-ads-open-cli profiles to discover accessible marketplaces
Set the desired profile ID, then list campaigns across ad types:
- amazon-ads-open-cli sp-campaigns --state enabled
- amazon-ads-open-cli sb-campaigns --state enabled
- amazon-ads-open-cli sd-campaigns --state enabled
Present campaign counts and statuses

When the user asks for performance data#

Use report commands to request async reports:
- amazon-ads-open-cli sp-report --record-type campaigns --start-date YYYYMMDD
Poll with amazon-ads-open-cli report-status <report-id> until complete
Download and present the report data from the returned URL

When the user asks about campaign structure#

List campaigns: amazon-ads-open-cli sp-campaigns
Drill into ad groups: amazon-ads-open-cli sp-adgroups --campaign-id <id>
Inspect ads: amazon-ads-open-cli sp-ads --adgroup-id <id>
Review keywords: amazon-ads-open-cli sp-keywords --adgroup-id <id>
Check targets: amazon-ads-open-cli sp-targets --adgroup-id <id>

When the user asks about keyword performance#

List keywords: amazon-ads-open-cli sp-keywords --campaign-id <id>
Check negative keywords: amazon-ads-open-cli sp-negative-keywords --campaign-id <id>
Request a keyword-level report: amazon-ads-open-cli sp-report --record-type keywords --start-date YYYYMMDD

When the user asks about DSP/programmatic#

List orders: amazon-ads-open-cli dsp-orders
Drill into line items: amazon-ads-open-cli dsp-line-items --order-id <id>
Review creatives: amazon-ads-open-cli dsp-creatives
Check audiences: amazon-ads-open-cli audiences
Review brand safety: amazon-ads-open-cli brand-safety-lists

When the user wants to compare ad types#

Pull campaigns for each type side by side:
- amazon-ads-open-cli sp-campaigns --state enabled
- amazon-ads-open-cli sb-campaigns --state enabled
- amazon-ads-open-cli sd-campaigns --state enabled
Request reports for each type with the same date range
Compare metrics across Sponsored Products, Brands, and Display

Error handling#

"No credentials found" -- ask the user to set AMAZON_ADS_ACCESS_TOKEN + AMAZON_ADS_CLIENT_ID env vars, or create ~/.config/amazon-ads-open-cli/credentials.json
"Profile ID required" -- the command needs AMAZON_ADS_PROFILE_ID. Run profiles first to discover available profile IDs
HTTP 401 -- access token is expired or invalid; ask the user to refresh their OAuth token
HTTP 403 -- the profile may not have access to the requested resource, or the API scope is insufficient
"Unknown command" -- verify the command name matches the reference above
Empty results -- check that the profile ID corresponds to the correct marketplace and that campaigns/entities exist