Amazon Ads Integration

Q: Are there any capabilities that are not available?

Yes. Some capabilities are not supported for safety reasons, including ads.keywords.delete, ads.product_ads.delete, ads.targeting.delete, and certain budget rule operations. These are disabled to protect buyer accounts.

Q: How do I know which capabilities my AI agent needs?

Think about what your AI Agent needs to do: read-only operations use list and get capabilities; creating new items use create capabilities; modifying existing items use update capabilities; performance data use ads.reports.* and ads.performance.fetch. See the capabilities list in this guide.

Learn how to publish AI Tools that connect to buyers' Amazon Ads accounts.

This integration allows your AI Agent automation to request campaign data, performance metrics, and manage advertising campaigns. SellerShorts makes API calls to Amazon Ads on behalf of buyers through your AI Agent automation.

Security & Privacy: All API calls are made through SellerShorts' secure infrastructure. Sellers never have direct access to buyer Amazon Ads accounts.

Access is scoped to the specific order and capabilities defined for the AI Tool. All connections are encrypted and follow Amazon Ads API security best practices.

🔒 Token & Credential Handling

AI Tool builders never receive Amazon Ads tokens, credentials, or login information. They only receive a SellerShorts job_token.
SellerShorts stores all tokens encrypted and authenticates every API call before forwarding to Amazon on the buyer's behalf.
Buyers can revoke access anytime from Connected Accounts or from their Amazon login settings.

This architecture complies with Amazon's Advertising API Terms of Use.

Overview

When you publish an AI Tool that requires Amazon Ads access, buyers will connect their own Amazon Ads accounts when they run your AI Tool.

Your AI Agent automation receives a secure token that allows it to request API calls through SellerShorts to Amazon Ads on the buyer's behalf.

All 42 available capabilities (Sponsored Products + Sponsored Brands v3 + Sponsored Display) are automatically enabled when you select Amazon Ads. No additional configuration is needed.

End-to-end flow (at a glance)

Creator setup: define required inputs and select Amazon Ads (all 42 capabilities enabled across SP, SB v3, and SD).Inputs guide
Buyer run: buyer fills the inputs and connects Amazon Ads; SellerShorts issues a job_token.
Agent execution: your automation uses the job_token to call SellerShorts, which forwards to Amazon Ads. All 42 capabilities are allowed by default.
Processing: fetch data, analyze, and generate recommendations or actions.
Return results: POST back to your callback/webhook URL with the output.Callback guide

💡 How it works

You select Amazon Ads as a required connection in the Inputs step
All 42 available capabilities are automatically enabled for your AI Agent: Sponsored Products and shared Reports/Performance/Recommendations/Budget Rules verbs (34 verbs total), Sponsored Brands v3 (3 verbs: campaigns, keywords, negative keywords), and Sponsored Display (5 verbs: campaigns, ad groups, product ads, targets, negative targets). No configuration needed.
When a buyer runs your AI Tool, they connect their Amazon Ads account
Your webhook receives a job_token in the payload
Your automation uses this token to call SellerShorts API endpoints for Amazon Ads operations
Your AI agent can use any of the 42 available capabilities. Note: Some capabilities like delete operations are intentionally disabled for safety reasons (see FAQ section for details)

Important: Amazon Ads Policy Responsibility

📜 Your AI Tool must produce Amazon-Ads-policy-compliant campaigns

The SellerShorts broker forwards your AI Tool's campaign / keyword / ad-group requests to Amazon's Ads API. Amazon's Advertising Policy, Creative Acceptance Policy, and prohibited-content rules apply. The buyer (advertiser) is responsible to Amazon for what runs on their account; as the AI Tool creator you are responsible for generating proposals that help them stay compliant.

Common Amazon Ads rules that AI Tools must respect:

Sponsored Brands creatives (headlines, custom images, video) are reviewed and may be rejected for any policy reason. The broker submits; Amazon decides.
Restricted product categories (e.g., adult, alcohol, regulated health, weapons) have additional advertising restrictions or are entirely prohibited from advertising.
Brand protection: competitor brand keyword bidding is allowed in most categories but is restricted for some (e.g., consumables) and prohibited in trademark-protected name use.
Bid and budget caps: Your AI Tool should respect the buyer-input maxDailyBudget and maxBid safety caps. The broker enforces these per-call but the buyer's stated cap is what matters for trust.
Campaign state: defaults are "paused" across SP, SB, and SD. Enabling a campaign without buyer review is risky; consider keeping campaigns paused until the buyer toggles them on.
Apply button preview must be truthful: the confirm.summary shown to the buyer must accurately describe the campaign or keyword set being created. Misleading previews are grounds for tool de-listing.

Amazon retains the right to suspend any account whose campaigns violate Advertising Policy, regardless of whether the violation came from a manual edit or an AI Tool. Build defensively, default to paused state, and surface what your campaign proposal will do before the broker call.

📚 Amazon authoritative sources: Amazon Ads policy hub · Creative acceptance policies · General policies

Setting up Amazon Ads in your AI Tool

Step 1: Select Amazon Ads provider

In the Inputs step of the AI Tool submission wizard, expand the "Authentication & Access Requirements" section.

You'll see a card for "Amazon Ads" with the description: "Buyers connect their Amazon Ads account. Your AI agent can request campaign, ad, and performance data."

Click the Amazon Ads card to select it. When selected, the card will show a green checkmark and an "Enabled" status badge.

Step 2: Understand capabilities

Capabilities are permissions that define what your AI Agent can do with a buyer's Amazon Ads account.

When you select Amazon Ads, all 42 available capabilities are automatically enabled. You don't need to configure anything. These capabilities are organized into 13 categories:

How to read the parameters:

Required fields: Must be provided in your API calls
Optional fields: Can be omitted if not needed
Enums: List the only allowed values (e.g., "state": "enabled" or "paused")
Dates: ISO format (YYYY-MM-DD, e.g., "2024-01-15") or YYYYMMDD for reports (e.g., "20240115"). Dates are interpreted as calendar dates (not timezone-specific), ensuring consistent behavior regardless of server location.
IDs: Accept string or number (e.g., "12345" or 12345)
Defaults: If a default is noted, you can omit that field and the default applies
Validation: Extra fields are rejected, and types are enforced server-side

Campaigns (4 capabilities)

Set up and manage top-level ad campaigns, including budgets, status, and scheduling.

ads.campaigns.create - Create new advertising campaigns
View parameters
Required:
- name (string) - Campaign name
- daily_budget (number) - Daily budget amount
Optional:
- campaign_type (enum) - "sponsoredProducts", "sponsoredBrands", or "sponsoredDisplay" (default: "sponsoredProducts")
- targeting_type (enum) - "manual" or "auto" (default: "manual")
- state (enum) - "enabled" or "paused" (default: "paused")
- start_date (string) - ISO date string
- end_date (string) - ISO date string
- portfolio_id (number) - Portfolio ID
- bidding (object) - Bidding strategy with optional strategy and adjustments
ads.campaigns.list - List all campaigns with optional filters
View parameters
All parameters are optional:
- maxResults (number, 1-1000) - Maximum number of results
- count (number, 1-100) - Legacy support, maps to maxResults
- nextToken (string) - Pagination token
- state_filter (enum) - "enabled", "paused", or "archived"
- name (string) - Filter by campaign name
- campaign_type (enum) - "sponsoredProducts", "sponsoredBrands", or "sponsoredDisplay"
- portfolio_id (number) - Filter by portfolio ID
- campaign_id (string|number) - Filter by specific campaign ID
ads.campaigns.update - Update existing campaigns (budget, status, settings)
View parameters
Required:
- campaign_id (string|number) - Campaign ID to update
Optional:
- name (string) - Campaign name
- state (enum) - "enabled" or "paused"
- daily_budget (number) - Daily budget amount
- start_date (string) - ISO date string
- end_date (string) - ISO date string
- portfolio_id (number) - Portfolio ID
- bidding (object) - Bidding strategy with optional strategy and adjustments
ads.campaigns.get - Get details of a specific campaign
View parameters
Required:
- campaign_id (string|number) - Campaign ID

Recommendations (4 capabilities)

Get AI-powered recommendations for keywords, product targeting, and budget optimization to improve campaign performance.

ads.keywords.recommendations - Get keyword recommendations based on ASINs or existing ad groups
View parameters
Required:
- recommendation_type (enum) - "KEYWORDS_FOR_ASINS" or "KEYWORDS_FOR_ADGROUP"
- For KEYWORDS_FOR_ASINS: asins (array of strings) - List of product ASINs
- For KEYWORDS_FOR_ADGROUP: campaign_id and ad_group_id (string|number) - Existing campaign and ad group IDs
Optional:
- targets (array) - User-defined keywords to rank alongside recommendations
- locale (string) - Locale for keyword translations
- maxRecommendations (number, 0-200) - Maximum number of recommendations (default: 200)
- sortDimension (enum) - "CLICKS", "CONVERSIONS", or "DEFAULT" (default: "DEFAULT")
ads.product_targeting.recommendations - Get product targeting recommendations based on input ASINs
View parameters
Required:
- ad_asins (array of strings, min 1) - List of input ASINs (each ASIN must be exactly 10 characters)
Optional:
- count (number, min 1) - Count of objects requested in the response. Defaults apply based on Accept header format
- cursor (string) - Cursor value for pagination (to fetch next or previous set of records)
- locale (string) - Locale for theme names and descriptions (e.g., "en_US", "en_GB", "zh_CN", "es_ES", "jp_JP", "de_DE", "fr_FR", "it_IT")
Note: This endpoint returns suggested ASINs to target based on input ASINs. Recommendations can be returned as a single list or grouped by theme (use Accept header to control format). Themes include: Top converting targets, Similar items, Complements, etc.
ads.budget.recommendations - Get budget recommendations for existing campaigns with missed opportunities analysis
View parameters
Required:
- campaign_ids (array of strings|numbers, 1-100 items) - List of campaign IDs to analyze
Returns recommended daily budget, percent time in budget, and estimated missed impressions/clicks/sales.
ads.budget.initial_recommendation - Get budget recommendation for a new campaign before creation
View parameters
Required:
- ad_groups (array) - Ad group information for the new campaign (exactly 1 item required)
- bidding (object) - Bidding strategy configuration
- targeting_type (enum) - "auto" or "manual"
Optional:
- start_date (string) - Campaign start date (ISO format or YYYYMMDD)
- end_date (string) - Campaign end date (ISO format or YYYYMMDD)

⚠️ Default behavior

All 42 capabilities (Sponsored Products + Sponsored Brands v3 + Sponsored Display) are automatically enabled when you select Amazon Ads. You don't need to configure or enable anything. Just select Amazon Ads and all capabilities are ready to use.

Using the job token in your webhook

Webhook payload structure

When a buyer runs your AI Tool that requires Amazon Ads, your webhook receives a standard payload with an additional job_token field:

{
  "short_id": "abc123",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "inputs": {
    "date_range": { "from": "2024-01-01", "to": "2024-01-31" },
    "max_daily_budget": 100
  },
  "callback_url": "https://sellershorts.com/api/orders/callback",
  "ts": 1736032405,
  "job_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

What is the job token?

The job_token is an encrypted token that contains:

The order ID and buyer's user ID
The list of allowed capabilities for this AI Tool
Security information to verify the token

Important: The job token is sensitive. Never expose it in logs, error messages, or client-side code. Treat it like a password.

The job token stays valid for the entire workflow execution (up to 24 hours), so your automation can make multiple SellerShorts API calls with the same token until the job finishes or times out.

Token expiration: After 24 hours, the token expires and API calls will fail with an INVALID_TOKEN error. If your workflow takes longer than 24 hours, you'll need to handle token expiration in your automation (e.g., notify the buyer that the workflow timed out, or design your workflow to complete within 24 hours).

API endpoint

All Amazon Ads API calls go through SellerShorts' capabilities API endpoint:

Base URL: https://sellershorts.com/api/capabilities

This is a POST endpoint that accepts JSON requests with the job token in the Authorization header.

Using the job token to call Amazon Ads API

To make Amazon Ads API calls, send requests to the capabilities API endpoint with the job token in the Authorization header:

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.campaigns.list",
  "provider": "amazon_ads",
  "params": {
    "portfolio_id": 1234567890,
    "maxResults": 10
  }
}

The API will verify that:

The job token is valid and not expired
The requested capability is in the allowed list
The buyer has a connected Amazon Ads account

If all checks pass, SellerShorts makes the actual API call to Amazon Ads on your behalf and returns the result.

Pagination with nextToken

When listing campaigns, ad groups, keywords, or other entities, Amazon Ads API returns results in pages. If there are more results available, the response includes a next_token field. Use this token to fetch the next page of results.

How pagination works:

Make your first request with maxResults (e.g., 1000)
Check if the response includes next_token
If next_token exists, make another request with the same parameters plus nextToken: {next_token}
Repeat until next_token is null or missing

Example: Fetching all campaigns

// First request
POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.campaigns.list",
  "provider": "amazon_ads",
  "params": {
    "maxResults": 1000
  }
}

// Response includes next_token if more results exist
{
  "status": "success",
  "data": {
    "campaigns": [...],
    "count": 1000,
    "next_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

// Second request (if next_token exists)
{
  "capability": "ads.campaigns.list",
  "provider": "amazon_ads",
  "params": {
    "maxResults": 1000,
    "nextToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Best practice: Always check for next_token in the response. If you have thousands of campaigns or keywords, you'll need multiple requests to fetch everything. The maxResults parameter has a maximum of 1000 per request.

Large dataset handling: When processing thousands of entities (campaigns, keywords, etc.), fetch data in batches using pagination, process each batch incrementally, and avoid loading everything into memory at once. For bulk updates or creations, consider batching operations (e.g., update 100 keywords at a time) to stay within rate limits and improve reliability.

Response format

Successful API calls return a JSON response with this structure:

{
  "status": "success",
  "data": {
    // Response data from Amazon Ads API
    // Structure varies by capability
  },
  "metadata": {
    "capability": "ads.campaigns.list",
    "provider": "amazon_ads",
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}

Failed API calls return an error response:

{
  "status": "error",
  "error": {
    "code": "LIMIT_EXCEEDED",
    "message": "daily_budget (150) exceeds your limit (100)",
    "details": {
      "field": "daily_budget",
      "value": 150
    }
  }
}

Example: ads.campaigns.list response

{
  "status": "success",
  "data": {
    "campaigns": [
      {
        "campaignId": "1234567890",
        "name": "Summer Sale Campaign",
        "campaignType": "sponsoredProducts",
        "targetingType": "manual",
        "state": "enabled",
        "dailyBudget": 50.0,
        "startDate": "20240101",
        "endDate": null,
        "portfolioId": 9876543210
      }
    ],
    "count": 1,
    "next_token": null,
    "total_results": 1
  },
  "metadata": {
    "capability": "ads.campaigns.list",
    "provider": "amazon_ads",
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}

Example: ads.reports.get response (when report is ready)

{
  "status": "success",
  "data": {
    "reportId": "amzn1.sellerapi.report.1234567890",
    "status": "SUCCESS",
    "statusDetails": "Report generation completed successfully",
    "url": "https://advertising-api.amazon.com/v2/reports/amzn1.sellerapi.report.1234567890/download",
    "startDate": "20240101",
    "endDate": "20240131"
  },
  "metadata": {
    "capability": "ads.reports.get",
    "provider": "amazon_ads",
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}

Safety limits and validation

Number input fields with limits

For AI Tools that modify budgets or bids, you can add number input fields with minimum and maximum values. These limits are enforced on the backend to prevent your AI Agent from exceeding safe spending amounts.

Supported limit fields

The system checks for these input field keys (case-insensitive, flexible naming):

Daily Budget Limits: maxDailyBudget, max_daily_budget, dailyBudgetMax, maxDailyBudgetLimit
Bid Limits: maxBid, max_bid, bidMax, maxBidLimit
Default Bid Limits: maxDefaultBid, max_default_bid

How validation works

When your AI Agent tries to create or update a campaign with a daily budget, or create/update keywords or targeting with a bid, the system:

Checks if the buyer provided a limit in their input form
Compares the requested value against the limit
If the value exceeds the limit, returns an error: {"status": "error", "error": {"code": "LIMIT_EXCEEDED", "message": "daily_budget (150) exceeds your limit (100)"}}
If no limit is set, the operation is allowed (backward compatible)

Note: The error response shown above is the technical JSON format your automation will receive. This is the standard error structure for all API errors.

Campaign enable protection

To prevent your AI Agent from automatically enabling campaigns, you can add a boolean input field with one of these keys:

allowEnableCampaigns
allow_enable_campaigns
allowCampaignEnable

If this field is set to false in the buyer's inputs, any attempt to set a campaign's state to "enabled" will be blocked with an error.

✅ Best practice

Always add number input fields with maximum limits for any AI Tool that modifies budgets or bids. This protects buyers from unexpected spending and builds trust.

Example: Add a "Maximum Daily Budget" number field with min: 1, max: 1000. Buyers can set their comfort level, and your AI Agent cannot exceed it.

Examples

Example 1: Account Performance Analyzer

Goal: Analyze your entire Amazon Ads account and get comprehensive performance data with optimization recommendations.

Required capabilities:

ads.campaigns.list - Get all campaigns across your account
ads.ad_groups.list - Get all ad groups for context
ads.keywords.list - Get all keywords for analysis
ads.product_ads.list - Get all product ads
ads.reports.create - Request comprehensive performance reports
ads.reports.get - Retrieve report data
ads.performance.fetch - Fetch detailed performance metrics

Input fields:

date_range (date_range, required) - "Analysis period (e.g., last 30 days)"
campaign_type (select, optional) - Options: "All", "Sponsored Products", "Sponsored Brands", "Sponsored Display"
include_recommendations (boolean, default: true) - "Include optimization recommendations"

Output: Comprehensive CSV or Excel report with account-wide performance metrics, campaign analysis, ad group performance, keyword performance, and actionable optimization recommendations.

Example API calls

Your automation receives job_token from the webhook. Use it to call SellerShorts API:

Step 1: List all campaigns

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.campaigns.list",
  "provider": "amazon_ads",
  "params": {
    "maxResults": 1000
  }
}

Step 2: Request performance report

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.reports.create",
  "provider": "amazon_ads",
  "params": {
    "report_type": "campaigns",
    "start_date": "20240101",
    "end_date": "20240131",
    "campaign_type": "sponsoredProducts"
  }
}

Step 3: Get report status and download URL

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.reports.get",
  "provider": "amazon_ads",
  "params": {
    "report_id": "{report_id_from_step_2}"
  }
}

Step 4: Fetch additional performance metrics

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.performance.fetch",
  "provider": "amazon_ads",
  "params": {
    "entity_type": "campaign",
    "start_date": "20240101",
    "end_date": "20240131"
  }
}

Example 2: Sponsored Products Detailed Report

Goal: Get a full detailed report of your Sponsored Products ads or entire ad account with granular insights.

Required capabilities:

ads.reports.create - Request detailed reports (filtered by Sponsored Products)
ads.reports.get - Retrieve report data and download URL
ads.campaigns.list - Get campaign details for context
ads.ad_groups.list - Get ad group details for context
ads.performance.fetch - Fetch additional performance metrics

Input fields:

date_range (date_range, required) - "Report period"
report_type (select, required) - Options: "campaigns", "adGroups", "keywords", "productAds"
campaign_ids (tags, optional) - "Specific campaign IDs to include (leave empty for all)"
include_metrics (multiselect, optional) - Options: "Impressions", "Clicks", "Spend", "Sales", "ACOS", "ROAS"

Output: Detailed report file (CSV or JSON) with comprehensive metrics, performance data, and insights for Sponsored Products campaigns. Can be filtered by specific campaigns or ad groups.

Example API calls

Your automation receives job_token from the webhook. Use it to call SellerShorts API:

Step 1: Create report request

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.reports.create",
  "provider": "amazon_ads",
  "params": {
    "report_type": "campaigns",
    "start_date": "20240101",
    "end_date": "20240131",
    "campaign_type": "sponsoredProducts",
    "metrics": ["impressions", "clicks", "cost", "sales"]
  }
}

Note: ACOS and ROAS are calculated fields, not direct API metrics. Calculate them from the report data: ACOS = (cost / sales) × 100, ROAS = sales / cost.

Step 2: Check report status (poll until ready)

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.reports.get",
  "provider": "amazon_ads",
  "params": {
    "report_id": "{report_id_from_step_1}"
  }
}

Response includes status ("SUCCESS", "IN_PROGRESS", "FAILURE") and url (download URL) when ready.

Report polling strategy

Reports are generated asynchronously. After creating a report request, you must poll the ads.reports.get endpoint until the status is "SUCCESS" or "FAILURE". Here's a recommended polling pattern:

Poll every 5-10 seconds (don't poll too frequently to avoid rate limits)
Set a maximum timeout (e.g., 5 minutes) to prevent infinite loops
If status is "IN_PROGRESS", continue polling
If status is "SUCCESS", download the report from the url field
If status is "FAILURE", check statusDetails for error information

// Example polling loop (pseudo-code)
let reportStatus = "IN_PROGRESS";
let attempts = 0;
const maxAttempts = 60; // 5 minutes at 5-second intervals

while (reportStatus === "IN_PROGRESS" && attempts < maxAttempts) {
  await sleep(5000); // Wait 5 seconds
  
  const response = await fetch("https://sellershorts.com/api/capabilities", {
    method: "POST",
    headers: {
      "Authorization": "Bearer {job_token}",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      capability: "ads.reports.get",
      provider: "amazon_ads",
      params: { report_id: "{report_id}" }
    })
  });
  
  const data = await response.json();
  reportStatus = data.data.status;
  attempts++;
  
  if (reportStatus === "SUCCESS") {
    // Download report from data.data.url
    break;
  } else if (reportStatus === "FAILURE") {
    // Handle error
    break;
  }
}

Example 3: Campaign Builder (Best Practices)

Goal: Create best-practice Amazon Ads campaigns and complete ad structure from scratch following industry best practices.

Required capabilities:

ads.campaigns.create - Create new campaigns with optimal settings
ads.ad_groups.create - Create ad groups within campaigns
ads.keywords.create - Add keywords to ad groups
ads.product_ads.create - Create product ads
ads.targeting.create - Create targeting clauses

Input fields:

campaign_name (text, required) - "Campaign name"
product_asin (text, required) - "Product ASIN to advertise"
daily_budget (number, min: 1, max: 1000, required) - "Daily budget"
max_daily_budget (number, min: 1, max: 1000, required) - "Maximum daily budget limit"
targeting_type (select, required) - Options: "Manual", "Auto"
default_bid (number, min: 0.01, max: 10, optional) - "Default bid amount"
max_bid (number, min: 0.01, max: 10, optional) - "Maximum bid limit"
keywords (tags, optional) - "Keywords to add (comma-separated)"

Output: Text report confirming created campaign structure including campaign ID, ad group IDs, keyword IDs, and product ad IDs. Includes best practice recommendations and next steps.

Example API calls

Your automation receives job_token from the webhook. Use it to call SellerShorts API:

Step 1: Create campaign

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.campaigns.create",
  "provider": "amazon_ads",
  "params": {
    "name": "{campaign_name}",
    "daily_budget": 50,
    "campaign_type": "sponsoredProducts",
    "targeting_type": "manual",
    "state": "paused"
  }
}

Note: Campaigns are created as "paused" by default for safety. Enable them manually or use the allowEnableCampaigns input field if you want campaigns to start enabled.

Step 2: Create ad group

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.ad_groups.create",
  "provider": "amazon_ads",
  "params": {
    "campaign_id": "{campaign_id_from_step_1}",
    "name": "Ad Group 1",
    "default_bid": 0.75,
    "state": "paused"
  }
}

Step 3: Add keywords

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.keywords.create",
  "provider": "amazon_ads",
  "params": {
    "ad_group_id": "{ad_group_id_from_step_2}",
    "keyword_text": "wireless headphones",
    "match_type": "broad",
    "bid": 0.80,
    "state": "paused"
  }
}

Match types: Keywords support three match types: "broad" (matches related searches), "phrase" (matches exact phrase), and "exact" (matches exact keyword only). "broad" is the default and casts the widest net for impressions.

Step 4: Create product ad

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.product_ads.create",
  "provider": "amazon_ads",
  "params": {
    "ad_group_id": "{ad_group_id_from_step_2}",
    "sku": "{product_sku}",
    "state": "paused"
  }
}

Example 4: ACOS/ROAS/TACOS Optimizer

Goal: Analyze your ACOS (Advertising Cost of Sale), ROAS (Return on Ad Spend), and TACOS (Total Advertising Cost of Sale) metrics and get actionable optimization recommendations.

Required capabilities:

ads.reports.create - Request performance reports with sales and spend metrics
ads.reports.get - Retrieve report data
ads.performance.fetch - Fetch detailed performance metrics
ads.campaigns.list - Get campaign details for context
ads.campaigns.update - Update campaigns based on recommendations (optional)

Input fields:

date_range (date_range, required) - "Analysis period"
target_acos (number, min: 0, max: 100, optional) - "Target ACOS percentage"
target_roas (number, min: 0, optional) - "Target ROAS ratio"
metric_focus (select, optional) - Options: "ACOS", "ROAS", "TACOS", "All"
include_recommendations (boolean, default: true) - "Include optimization recommendations"

Output: Detailed analysis report (CSV or text) showing ACOS, ROAS, and TACOS calculations for each campaign, ad group, and keyword. Includes performance benchmarks, underperforming areas, and specific recommendations to improve metrics.

Example API calls

Your automation receives job_token from the webhook. Use it to call SellerShorts API:

Step 1: Get all campaigns

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.campaigns.list",
  "provider": "amazon_ads",
  "params": {
    "maxResults": 1000
  }
}

Step 2: Request performance report with sales/spend metrics

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.reports.create",
  "provider": "amazon_ads",
  "params": {
    "report_type": "campaigns",
    "start_date": "20240101",
    "end_date": "20240131",
    "metrics": ["cost", "sales", "impressions", "clicks"]
  }
}

Step 3: Fetch detailed performance metrics

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.performance.fetch",
  "provider": "amazon_ads",
  "params": {
    "entity_type": "campaign",
    "start_date": "20240101",
    "end_date": "20240131",
    "metrics": ["cost", "sales", "impressions", "clicks"]
  }
}

Step 4: Get report and calculate ACOS/ROAS

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.reports.get",
  "provider": "amazon_ads",
  "params": {
    "report_id": "{report_id_from_step_2}"
  }
}

After receiving report data, your automation calculates: ACOS = (Cost / Sales) × 100, ROAS = Sales / Cost, and generates optimization recommendations.

Example 5: Search Term Waste Cleaner (Read-only)

Goal: Identify wasteful search terms (high spend, low/no sales) and produce a negative keyword recommendation list (no auto-changes).

Required capabilities:

ads.reports.create - Request search term performance report
ads.reports.get - Retrieve report data
ads.performance.fetch - (Optional) Pull recent performance metrics
ads.keywords.list - (Optional) Context of existing keywords

Input fields:

date_range (date_range, required) - "Analysis period"
max_acos (number, optional) - "Max ACOS % before marking as waste"
min_clicks (number, optional) - "Minimum clicks to consider a term"
campaign_ids (tags, optional) - "Campaign IDs to include (empty = all)"

Output: CSV/text list of suggested negatives (term, match type suggestion, spend, clicks, sales, ACOS) with rationale. Read-only recommendations; user applies manually.

Example API calls

Use the job_token from the webhook:

Step 1: Request search term report

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.reports.create",
  "provider": "amazon_ads",
  "params": {
    "report_type": "keywords",
    "start_date": "20240101",
    "end_date": "20240131",
    "metrics": ["impressions", "clicks", "cost", "sales"]
  }
}

Step 2: Check report status and get download

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.reports.get",
  "provider": "amazon_ads",
  "params": {
    "report_id": "{report_id_from_step_1}"
  }
}

Process the downloaded data to flag waste terms; output recommended negatives (do not auto-apply).

Example 6: Search Term Optimizer (Read-only recommendations)

Goal: Identify winning and losing search terms, recommend bid up/down or negatives (no auto-changes).

Required capabilities:

ads.reports.create - Request search term performance report
ads.reports.get - Retrieve report data
ads.performance.fetch - (Optional) Pull recent performance metrics

Input fields:

date_range (date_range, required) - "Analysis period"
target_acos (number, optional) - "Target ACOS % for scaling decisions"
min_clicks (number, optional) - "Minimum clicks to consider"
campaign_ids (tags, optional) - "Campaign IDs to include (empty = all)"

Output: Two lists: (1) scale candidates (good ROAS/low ACOS → bid up suggestion), (2) cut/negate candidates (high spend/low sales → bid down or negative suggestion). Read-only recommendations.

Example API calls

Use the job_token from the webhook:

Step 1: Request search term report

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.reports.create",
  "provider": "amazon_ads",
  "params": {
    "report_type": "keywords",
    "start_date": "20240101",
    "end_date": "20240131",
    "metrics": ["impressions", "clicks", "cost", "sales"]
  }
}

Step 2: Check report status and get download

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.reports.get",
  "provider": "amazon_ads",
  "params": {
    "report_id": "{report_id_from_step_1}"
  }
}

Use the report data to classify terms into scale vs. cut/negate suggestions; no automatic changes are made.

Buyer experience

Connecting Amazon Ads account

When a buyer runs your AI Tool that requires Amazon Ads:

They see a "Connect Amazon Ads Account" button on the run page
Clicking the button redirects them to Amazon's authorization page
They sign in with their Amazon Ads account credentials
They select which advertising profile to connect (if they have multiple profiles, they choose one)
They authorize SellerShorts to access their account
They're redirected back to your AI Tool's run page
The connection status shows as "Connected" and they can proceed

Note: If a buyer has multiple Amazon Ads profiles, they select one during connection. All API calls for that order will use the selected profile. To use a different profile, the buyer must disconnect and reconnect with the desired profile.

Connection status

Buyers can see their connection status on the AI Tool run page. If the connection is valid and has the required capabilities, they'll see a green "Connected" status. If there's an issue, they'll see an error message with instructions to reconnect.

Disconnecting

Buyers can disconnect their Amazon Ads account at any time from their account settings page. If they disconnect, new orders will require reconnection. Any in-progress calls will fail with NO_CONNECTION until the buyer reconnects.

Error handling

Error code reference

All possible error codes returned by the capabilities API:

Error Code	Description	HTTP Status
`INVALID_TOKEN`	Job token is missing, malformed, or expired	401
`CAPABILITY_NOT_ALLOWED`	Requested capability is not supported	403
`NO_CONNECTION`	Buyer hasn't connected Amazon Ads account	400
`LIMIT_EXCEEDED`	Value exceeds buyer's input limit	400
`PERMISSION_DENIED`	Campaign enable permission denied	403
`RATE_LIMIT`	Amazon Ads API rate limit exceeded	429
`TOKEN_EXPIRED`	Amazon Ads connection expired or revoked	401
`ORDER_NOT_FOUND`	Order ID doesn't exist or access denied	404
`INVALID_REQUEST`	Invalid request parameters or format	400
`SP_API_ERROR`	Amazon Ads API returned an error	500
`INTERNAL_ERROR`	Internal server error	500

Common API errors

Detailed explanations for each error code:

INVALID_TOKEN

Code: INVALID_TOKEN
Message: "Invalid or expired job token"
Cause: Job token is missing, malformed, or expired
Solution: Ensure you're sending the token from the webhook payload in the Authorization header

CAPABILITY_NOT_ALLOWED

Code: CAPABILITY_NOT_ALLOWED
Message: "Capability 'ads.keywords.delete' is not allowed for this order"
Cause: The requested capability is not supported for safety reasons
Solution: Use a different capability that is supported. Check the FAQ section for a list of capabilities that are not available.

NO_CONNECTION

Code: NO_CONNECTION
Message: "No Amazon Ads connection found. Please connect your Amazon Ads account first."
Cause: Buyer hasn't connected their Amazon Ads account
Solution: Buyer must connect their account before running the AI Tool

LIMIT_EXCEEDED

Code: LIMIT_EXCEEDED
Message: "daily_budget (150) exceeds your limit (100)"
Cause: The requested value exceeds the buyer's input limit
Solution: Reduce the value to within the limit, or inform the buyer to increase their limit

PERMISSION_DENIED

Code: PERMISSION_DENIED
Message: "Enabling campaigns is not allowed for this AI Tool"
Cause: Your AI agent tried to set a campaign's state to "enabled", but the buyer has set allowEnableCampaigns to false in their input form
Solution: Create campaigns with "state": "paused" instead, or inform the buyer that they need to set allowEnableCampaigns to true if they want campaigns to be automatically enabled

RATE_LIMIT

Code: RATE_LIMIT
Message: "Amazon Ads API rate limit exceeded. Please try again later."
Cause: Amazon Ads API enforces rate limits. Too many requests in a short time period.
Solution: SellerShorts automatically handles rate limits by retrying requests up to 4 times with exponential backoff (1s, 2s, 4s delays). If rate limits persist after automatic retries, wait before making additional requests. Your automation doesn't need to implement retry logic. SellerShorts handles it automatically. For bulk operations, consider throttling your requests (e.g., 1 request per second) to avoid hitting limits.

TOKEN_EXPIRED

Code: TOKEN_EXPIRED
Message: "Amazon Ads connection has been revoked. Please reconnect your Amazon Ads account."
Cause: The buyer's Amazon Ads connection was revoked or expired
Solution: The buyer must reconnect their Amazon Ads account. Your automation should handle this gracefully and inform the buyer to reconnect.

ORDER_NOT_FOUND

Code: ORDER_NOT_FOUND
Message: "Order not found or access denied"
Cause: The order ID in the job token doesn't exist or doesn't belong to the buyer
Solution: Ensure you're using the correct job token from the webhook payload. If the issue persists, contact support.

INVALID_REQUEST

Code: INVALID_REQUEST
Message: "Invalid request body" or "Invalid JSON in request body" or "Unsupported provider: {provider}"
Cause: The request body is malformed, missing required fields, or uses an unsupported provider
Solution: Check that your request body is valid JSON and includes all required fields (capability, provider, and optionally params). Ensure provider is set to "amazon_ads".

SP_API_ERROR

Code: SP_API_ERROR
Message: "Failed to load Amazon Ads connection" or error message from Amazon Ads API
Cause: An error occurred when communicating with Amazon Ads API or loading the connection
Solution: Check the error details in the response. This could indicate a temporary Amazon Ads API issue, connection problem, or permission issue. Retry the request after a short delay.

INTERNAL_ERROR

Code: INTERNAL_ERROR
Message: "Internal server error"
Cause: An unexpected error occurred on SellerShorts' servers
Solution: This is a rare occurrence. Wait a few moments and retry the request. If the issue persists, contact support with the error details.

Best practices

Use capabilities appropriately

All 42 capabilities are automatically enabled when you select Amazon Ads. While you have access to all capabilities, design your AI Agent to only use the capabilities it actually needs for its specific purpose. This follows the principle of least privilege and makes your AI Tool's behavior clearer to buyers.

Always set safety limits

For any AI Tool that modifies budgets or bids, always add number input fields with maximum limits. This protects buyers and builds trust in your automation.

Handle errors gracefully

Your automation should handle API errors gracefully. If a capability call fails, log the error, inform the buyer through your callback response, and don't crash your automation.

Test thoroughly

Important: Always use the Test step in the submission wizard to test your AI Tool with a real Amazon Ads account connection before submitting for review. Verify that:

All required capabilities are working
Safety limits are enforced correctly
Error handling works as expected
Results are returned in the correct format

The Test step allows you to run your AI Tool end-to-end with your own Amazon Ads account, ensuring everything works correctly before buyers use it.

Document in admin review notes

When submitting your AI Tool for review, use the "Notes for Admin Review" field to explain:

Which capabilities your AI Agent uses and why
What safety limits you've set and why
What account state is needed for testing (e.g., "Requires at least one active campaign")
Any special considerations for the admin review team

FAQ

Do I need my own Amazon Ads account to publish an AI Tool?

No. You don't need an Amazon Ads account to publish an AI Tool. Buyers connect their own accounts when they run your AI Tool.

Can I test my AI Tool without a buyer account?

Yes. Use the Test step in the submission wizard. You'll need to connect your own Amazon Ads account (or a test account) to test the integration end-to-end.

What happens if a buyer doesn't have an Amazon Ads account?

They cannot run your AI Tool. The connection step is required, and they'll see instructions to create an Amazon Ads account if they don't have one.

Can I change capabilities after my AI Tool is approved?

Currently, edits to an approved AI Tool are not automatically forced through re-review. If you change capabilities, you should submit for admin re-review to keep buyers safe and aligned with platform policy.

Are there any capabilities that are not available?

Yes. The following capabilities are not supported for safety reasons:

ads.keywords.delete
ads.product_ads.delete
ads.targeting.delete
ads.budget_rules.create
ads.budget_rules.update
ads.budget_rules.associate

These capabilities are not supported to protect buyer accounts and prevent unintended changes.

How do I know which capabilities my AI agent needs?

Think about what your AI Agent needs to do:

Read-only operations: Use list and get capabilities
Creating new items: Use create capabilities
Modifying existing items: Use update capabilities
Performance data: Use ads.reports.* and ads.performance.fetch

What's next?

Now that you understand how Amazon Ads integration works, you can:

Publish your first Amazon Ads AI Tool using the Inputs step guide
Learn about webhook payloads and placeholders
Review the Test step guide to test your integration

Amazon Ads Integration

Learn how to publish AI Tools that connect to buyers' Amazon Ads accounts.

Security & Privacy: All API calls are made through SellerShorts' secure infrastructure. Sellers never have direct access to buyer Amazon Ads accounts.

Access is scoped to the specific order and capabilities defined for the AI Tool. All connections are encrypted and follow Amazon Ads API security best practices.

🔒 Token & Credential Handling

AI Tool builders never receive Amazon Ads tokens, credentials, or login information. They only receive a SellerShorts job_token.
SellerShorts stores all tokens encrypted and authenticates every API call before forwarding to Amazon on the buyer's behalf.
Buyers can revoke access anytime from Connected Accounts or from their Amazon login settings.

This architecture complies with Amazon's Advertising API Terms of Use.

Overview

When you publish an AI Tool that requires Amazon Ads access, buyers will connect their own Amazon Ads accounts when they run your AI Tool.

Your AI Agent automation receives a secure token that allows it to request API calls through SellerShorts to Amazon Ads on the buyer's behalf.

All 42 available capabilities (Sponsored Products + Sponsored Brands v3 + Sponsored Display) are automatically enabled when you select Amazon Ads. No additional configuration is needed.

End-to-end flow (at a glance)

Creator setup: define required inputs and select Amazon Ads (all 42 capabilities enabled across SP, SB v3, and SD).Inputs guide
Buyer run: buyer fills the inputs and connects Amazon Ads; SellerShorts issues a job_token.
Agent execution: your automation uses the job_token to call SellerShorts, which forwards to Amazon Ads. All 42 capabilities are allowed by default.
Processing: fetch data, analyze, and generate recommendations or actions.
Return results: POST back to your callback/webhook URL with the output.Callback guide

💡 How it works

You select Amazon Ads as a required connection in the Inputs step
All 42 available capabilities are automatically enabled for your AI Agent: Sponsored Products and shared Reports/Performance/Recommendations/Budget Rules verbs (34 verbs total), Sponsored Brands v3 (3 verbs: campaigns, keywords, negative keywords), and Sponsored Display (5 verbs: campaigns, ad groups, product ads, targets, negative targets). No configuration needed.
When a buyer runs your AI Tool, they connect their Amazon Ads account
Your webhook receives a job_token in the payload
Your automation uses this token to call SellerShorts API endpoints for Amazon Ads operations
Your AI agent can use any of the 42 available capabilities. Note: Some capabilities like delete operations are intentionally disabled for safety reasons (see FAQ section for details)

Important: Amazon Ads Policy Responsibility

📜 Your AI Tool must produce Amazon-Ads-policy-compliant campaigns

Common Amazon Ads rules that AI Tools must respect:

Sponsored Brands creatives (headlines, custom images, video) are reviewed and may be rejected for any policy reason. The broker submits; Amazon decides.
Restricted product categories (e.g., adult, alcohol, regulated health, weapons) have additional advertising restrictions or are entirely prohibited from advertising.
Brand protection: competitor brand keyword bidding is allowed in most categories but is restricted for some (e.g., consumables) and prohibited in trademark-protected name use.
Bid and budget caps: Your AI Tool should respect the buyer-input maxDailyBudget and maxBid safety caps. The broker enforces these per-call but the buyer's stated cap is what matters for trust.
Campaign state: defaults are "paused" across SP, SB, and SD. Enabling a campaign without buyer review is risky; consider keeping campaigns paused until the buyer toggles them on.
Apply button preview must be truthful: the confirm.summary shown to the buyer must accurately describe the campaign or keyword set being created. Misleading previews are grounds for tool de-listing.

📚 Amazon authoritative sources: Amazon Ads policy hub · Creative acceptance policies · General policies

Setting up Amazon Ads in your AI Tool

Step 1: Select Amazon Ads provider

In the Inputs step of the AI Tool submission wizard, expand the "Authentication & Access Requirements" section.

You'll see a card for "Amazon Ads" with the description: "Buyers connect their Amazon Ads account. Your AI agent can request campaign, ad, and performance data."

Click the Amazon Ads card to select it. When selected, the card will show a green checkmark and an "Enabled" status badge.

Step 2: Understand capabilities

Capabilities are permissions that define what your AI Agent can do with a buyer's Amazon Ads account.

When you select Amazon Ads, all 42 available capabilities are automatically enabled. You don't need to configure anything. These capabilities are organized into 13 categories:

How to read the parameters:

Required fields: Must be provided in your API calls
Optional fields: Can be omitted if not needed
Enums: List the only allowed values (e.g., "state": "enabled" or "paused")
Dates: ISO format (YYYY-MM-DD, e.g., "2024-01-15") or YYYYMMDD for reports (e.g., "20240115"). Dates are interpreted as calendar dates (not timezone-specific), ensuring consistent behavior regardless of server location.
IDs: Accept string or number (e.g., "12345" or 12345)
Defaults: If a default is noted, you can omit that field and the default applies
Validation: Extra fields are rejected, and types are enforced server-side

Campaigns (4 capabilities)

Set up and manage top-level ad campaigns, including budgets, status, and scheduling.

ads.campaigns.create - Create new advertising campaigns
View parameters
Required:
- name (string) - Campaign name
- daily_budget (number) - Daily budget amount
Optional:
- campaign_type (enum) - "sponsoredProducts", "sponsoredBrands", or "sponsoredDisplay" (default: "sponsoredProducts")
- targeting_type (enum) - "manual" or "auto" (default: "manual")
- state (enum) - "enabled" or "paused" (default: "paused")
- start_date (string) - ISO date string
- end_date (string) - ISO date string
- portfolio_id (number) - Portfolio ID
- bidding (object) - Bidding strategy with optional strategy and adjustments
ads.campaigns.list - List all campaigns with optional filters
View parameters
All parameters are optional:
- maxResults (number, 1-1000) - Maximum number of results
- count (number, 1-100) - Legacy support, maps to maxResults
- nextToken (string) - Pagination token
- state_filter (enum) - "enabled", "paused", or "archived"
- name (string) - Filter by campaign name
- campaign_type (enum) - "sponsoredProducts", "sponsoredBrands", or "sponsoredDisplay"
- portfolio_id (number) - Filter by portfolio ID
- campaign_id (string|number) - Filter by specific campaign ID
ads.campaigns.update - Update existing campaigns (budget, status, settings)
View parameters
Required:
- campaign_id (string|number) - Campaign ID to update
Optional:
- name (string) - Campaign name
- state (enum) - "enabled" or "paused"
- daily_budget (number) - Daily budget amount
- start_date (string) - ISO date string
- end_date (string) - ISO date string
- portfolio_id (number) - Portfolio ID
- bidding (object) - Bidding strategy with optional strategy and adjustments
ads.campaigns.get - Get details of a specific campaign
View parameters
Required:
- campaign_id (string|number) - Campaign ID

Recommendations (4 capabilities)

Get AI-powered recommendations for keywords, product targeting, and budget optimization to improve campaign performance.

ads.keywords.recommendations - Get keyword recommendations based on ASINs or existing ad groups
View parameters
Required:
- recommendation_type (enum) - "KEYWORDS_FOR_ASINS" or "KEYWORDS_FOR_ADGROUP"
- For KEYWORDS_FOR_ASINS: asins (array of strings) - List of product ASINs
- For KEYWORDS_FOR_ADGROUP: campaign_id and ad_group_id (string|number) - Existing campaign and ad group IDs
Optional:
- targets (array) - User-defined keywords to rank alongside recommendations
- locale (string) - Locale for keyword translations
- maxRecommendations (number, 0-200) - Maximum number of recommendations (default: 200)
- sortDimension (enum) - "CLICKS", "CONVERSIONS", or "DEFAULT" (default: "DEFAULT")
ads.product_targeting.recommendations - Get product targeting recommendations based on input ASINs
View parameters
Required:
- ad_asins (array of strings, min 1) - List of input ASINs (each ASIN must be exactly 10 characters)
Optional:
- count (number, min 1) - Count of objects requested in the response. Defaults apply based on Accept header format
- cursor (string) - Cursor value for pagination (to fetch next or previous set of records)
- locale (string) - Locale for theme names and descriptions (e.g., "en_US", "en_GB", "zh_CN", "es_ES", "jp_JP", "de_DE", "fr_FR", "it_IT")
Note: This endpoint returns suggested ASINs to target based on input ASINs. Recommendations can be returned as a single list or grouped by theme (use Accept header to control format). Themes include: Top converting targets, Similar items, Complements, etc.
ads.budget.recommendations - Get budget recommendations for existing campaigns with missed opportunities analysis
View parameters
Required:
- campaign_ids (array of strings|numbers, 1-100 items) - List of campaign IDs to analyze
Returns recommended daily budget, percent time in budget, and estimated missed impressions/clicks/sales.
ads.budget.initial_recommendation - Get budget recommendation for a new campaign before creation
View parameters
Required:
- ad_groups (array) - Ad group information for the new campaign (exactly 1 item required)
- bidding (object) - Bidding strategy configuration
- targeting_type (enum) - "auto" or "manual"
Optional:
- start_date (string) - Campaign start date (ISO format or YYYYMMDD)
- end_date (string) - Campaign end date (ISO format or YYYYMMDD)

⚠️ Default behavior

Using the job token in your webhook

Webhook payload structure

When a buyer runs your AI Tool that requires Amazon Ads, your webhook receives a standard payload with an additional job_token field:

{
  "short_id": "abc123",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "inputs": {
    "date_range": { "from": "2024-01-01", "to": "2024-01-31" },
    "max_daily_budget": 100
  },
  "callback_url": "https://sellershorts.com/api/orders/callback",
  "ts": 1736032405,
  "job_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

What is the job token?

The job_token is an encrypted token that contains:

The order ID and buyer's user ID
The list of allowed capabilities for this AI Tool
Security information to verify the token

Important: The job token is sensitive. Never expose it in logs, error messages, or client-side code. Treat it like a password.

The job token stays valid for the entire workflow execution (up to 24 hours), so your automation can make multiple SellerShorts API calls with the same token until the job finishes or times out.

API endpoint

All Amazon Ads API calls go through SellerShorts' capabilities API endpoint:

Base URL: https://sellershorts.com/api/capabilities

This is a POST endpoint that accepts JSON requests with the job token in the Authorization header.

Using the job token to call Amazon Ads API

To make Amazon Ads API calls, send requests to the capabilities API endpoint with the job token in the Authorization header:

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.campaigns.list",
  "provider": "amazon_ads",
  "params": {
    "portfolio_id": 1234567890,
    "maxResults": 10
  }
}

The API will verify that:

The job token is valid and not expired
The requested capability is in the allowed list
The buyer has a connected Amazon Ads account

If all checks pass, SellerShorts makes the actual API call to Amazon Ads on your behalf and returns the result.

Pagination with nextToken

How pagination works:

Make your first request with maxResults (e.g., 1000)
Check if the response includes next_token
If next_token exists, make another request with the same parameters plus nextToken: {next_token}
Repeat until next_token is null or missing

Example: Fetching all campaigns

// First request
POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.campaigns.list",
  "provider": "amazon_ads",
  "params": {
    "maxResults": 1000
  }
}

// Response includes next_token if more results exist
{
  "status": "success",
  "data": {
    "campaigns": [...],
    "count": 1000,
    "next_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

// Second request (if next_token exists)
{
  "capability": "ads.campaigns.list",
  "provider": "amazon_ads",
  "params": {
    "maxResults": 1000,
    "nextToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Response format

Successful API calls return a JSON response with this structure:

{
  "status": "success",
  "data": {
    // Response data from Amazon Ads API
    // Structure varies by capability
  },
  "metadata": {
    "capability": "ads.campaigns.list",
    "provider": "amazon_ads",
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}

Failed API calls return an error response:

{
  "status": "error",
  "error": {
    "code": "LIMIT_EXCEEDED",
    "message": "daily_budget (150) exceeds your limit (100)",
    "details": {
      "field": "daily_budget",
      "value": 150
    }
  }
}

Example: ads.campaigns.list response

{
  "status": "success",
  "data": {
    "campaigns": [
      {
        "campaignId": "1234567890",
        "name": "Summer Sale Campaign",
        "campaignType": "sponsoredProducts",
        "targetingType": "manual",
        "state": "enabled",
        "dailyBudget": 50.0,
        "startDate": "20240101",
        "endDate": null,
        "portfolioId": 9876543210
      }
    ],
    "count": 1,
    "next_token": null,
    "total_results": 1
  },
  "metadata": {
    "capability": "ads.campaigns.list",
    "provider": "amazon_ads",
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}

Example: ads.reports.get response (when report is ready)

{
  "status": "success",
  "data": {
    "reportId": "amzn1.sellerapi.report.1234567890",
    "status": "SUCCESS",
    "statusDetails": "Report generation completed successfully",
    "url": "https://advertising-api.amazon.com/v2/reports/amzn1.sellerapi.report.1234567890/download",
    "startDate": "20240101",
    "endDate": "20240131"
  },
  "metadata": {
    "capability": "ads.reports.get",
    "provider": "amazon_ads",
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}

Safety limits and validation

Number input fields with limits

Supported limit fields

The system checks for these input field keys (case-insensitive, flexible naming):

Daily Budget Limits: maxDailyBudget, max_daily_budget, dailyBudgetMax, maxDailyBudgetLimit
Bid Limits: maxBid, max_bid, bidMax, maxBidLimit
Default Bid Limits: maxDefaultBid, max_default_bid

How validation works

When your AI Agent tries to create or update a campaign with a daily budget, or create/update keywords or targeting with a bid, the system:

Checks if the buyer provided a limit in their input form
Compares the requested value against the limit
If the value exceeds the limit, returns an error: {"status": "error", "error": {"code": "LIMIT_EXCEEDED", "message": "daily_budget (150) exceeds your limit (100)"}}
If no limit is set, the operation is allowed (backward compatible)

Note: The error response shown above is the technical JSON format your automation will receive. This is the standard error structure for all API errors.

Campaign enable protection

To prevent your AI Agent from automatically enabling campaigns, you can add a boolean input field with one of these keys:

allowEnableCampaigns
allow_enable_campaigns
allowCampaignEnable

If this field is set to false in the buyer's inputs, any attempt to set a campaign's state to "enabled" will be blocked with an error.

✅ Best practice

Always add number input fields with maximum limits for any AI Tool that modifies budgets or bids. This protects buyers from unexpected spending and builds trust.

Example: Add a "Maximum Daily Budget" number field with min: 1, max: 1000. Buyers can set their comfort level, and your AI Agent cannot exceed it.

Examples

Example 1: Account Performance Analyzer

Goal: Analyze your entire Amazon Ads account and get comprehensive performance data with optimization recommendations.

Required capabilities:

ads.campaigns.list - Get all campaigns across your account
ads.ad_groups.list - Get all ad groups for context
ads.keywords.list - Get all keywords for analysis
ads.product_ads.list - Get all product ads
ads.reports.create - Request comprehensive performance reports
ads.reports.get - Retrieve report data
ads.performance.fetch - Fetch detailed performance metrics

Input fields:

date_range (date_range, required) - "Analysis period (e.g., last 30 days)"
campaign_type (select, optional) - Options: "All", "Sponsored Products", "Sponsored Brands", "Sponsored Display"
include_recommendations (boolean, default: true) - "Include optimization recommendations"

Output: Comprehensive CSV or Excel report with account-wide performance metrics, campaign analysis, ad group performance, keyword performance, and actionable optimization recommendations.

Example API calls

Your automation receives job_token from the webhook. Use it to call SellerShorts API:

Step 1: List all campaigns

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.campaigns.list",
  "provider": "amazon_ads",
  "params": {
    "maxResults": 1000
  }
}

Step 2: Request performance report

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.reports.create",
  "provider": "amazon_ads",
  "params": {
    "report_type": "campaigns",
    "start_date": "20240101",
    "end_date": "20240131",
    "campaign_type": "sponsoredProducts"
  }
}

Step 3: Get report status and download URL

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.reports.get",
  "provider": "amazon_ads",
  "params": {
    "report_id": "{report_id_from_step_2}"
  }
}

Step 4: Fetch additional performance metrics

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.performance.fetch",
  "provider": "amazon_ads",
  "params": {
    "entity_type": "campaign",
    "start_date": "20240101",
    "end_date": "20240131"
  }
}

Example 2: Sponsored Products Detailed Report

Goal: Get a full detailed report of your Sponsored Products ads or entire ad account with granular insights.

Required capabilities:

ads.reports.create - Request detailed reports (filtered by Sponsored Products)
ads.reports.get - Retrieve report data and download URL
ads.campaigns.list - Get campaign details for context
ads.ad_groups.list - Get ad group details for context
ads.performance.fetch - Fetch additional performance metrics

Input fields:

date_range (date_range, required) - "Report period"
report_type (select, required) - Options: "campaigns", "adGroups", "keywords", "productAds"
campaign_ids (tags, optional) - "Specific campaign IDs to include (leave empty for all)"
include_metrics (multiselect, optional) - Options: "Impressions", "Clicks", "Spend", "Sales", "ACOS", "ROAS"

Output: Detailed report file (CSV or JSON) with comprehensive metrics, performance data, and insights for Sponsored Products campaigns. Can be filtered by specific campaigns or ad groups.

Example API calls

Your automation receives job_token from the webhook. Use it to call SellerShorts API:

Step 1: Create report request

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.reports.create",
  "provider": "amazon_ads",
  "params": {
    "report_type": "campaigns",
    "start_date": "20240101",
    "end_date": "20240131",
    "campaign_type": "sponsoredProducts",
    "metrics": ["impressions", "clicks", "cost", "sales"]
  }
}

Note: ACOS and ROAS are calculated fields, not direct API metrics. Calculate them from the report data: ACOS = (cost / sales) × 100, ROAS = sales / cost.

Step 2: Check report status (poll until ready)

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.reports.get",
  "provider": "amazon_ads",
  "params": {
    "report_id": "{report_id_from_step_1}"
  }
}

Response includes status ("SUCCESS", "IN_PROGRESS", "FAILURE") and url (download URL) when ready.

Report polling strategy

Reports are generated asynchronously. After creating a report request, you must poll the ads.reports.get endpoint until the status is "SUCCESS" or "FAILURE". Here's a recommended polling pattern:

Poll every 5-10 seconds (don't poll too frequently to avoid rate limits)
Set a maximum timeout (e.g., 5 minutes) to prevent infinite loops
If status is "IN_PROGRESS", continue polling
If status is "SUCCESS", download the report from the url field
If status is "FAILURE", check statusDetails for error information

// Example polling loop (pseudo-code)
let reportStatus = "IN_PROGRESS";
let attempts = 0;
const maxAttempts = 60; // 5 minutes at 5-second intervals

while (reportStatus === "IN_PROGRESS" && attempts < maxAttempts) {
  await sleep(5000); // Wait 5 seconds
  
  const response = await fetch("https://sellershorts.com/api/capabilities", {
    method: "POST",
    headers: {
      "Authorization": "Bearer {job_token}",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      capability: "ads.reports.get",
      provider: "amazon_ads",
      params: { report_id: "{report_id}" }
    })
  });
  
  const data = await response.json();
  reportStatus = data.data.status;
  attempts++;
  
  if (reportStatus === "SUCCESS") {
    // Download report from data.data.url
    break;
  } else if (reportStatus === "FAILURE") {
    // Handle error
    break;
  }
}

Example 3: Campaign Builder (Best Practices)

Goal: Create best-practice Amazon Ads campaigns and complete ad structure from scratch following industry best practices.

Required capabilities:

ads.campaigns.create - Create new campaigns with optimal settings
ads.ad_groups.create - Create ad groups within campaigns
ads.keywords.create - Add keywords to ad groups
ads.product_ads.create - Create product ads
ads.targeting.create - Create targeting clauses

Input fields:

campaign_name (text, required) - "Campaign name"
product_asin (text, required) - "Product ASIN to advertise"
daily_budget (number, min: 1, max: 1000, required) - "Daily budget"
max_daily_budget (number, min: 1, max: 1000, required) - "Maximum daily budget limit"
targeting_type (select, required) - Options: "Manual", "Auto"
default_bid (number, min: 0.01, max: 10, optional) - "Default bid amount"
max_bid (number, min: 0.01, max: 10, optional) - "Maximum bid limit"
keywords (tags, optional) - "Keywords to add (comma-separated)"

Output: Text report confirming created campaign structure including campaign ID, ad group IDs, keyword IDs, and product ad IDs. Includes best practice recommendations and next steps.

Example API calls

Your automation receives job_token from the webhook. Use it to call SellerShorts API:

Step 1: Create campaign

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.campaigns.create",
  "provider": "amazon_ads",
  "params": {
    "name": "{campaign_name}",
    "daily_budget": 50,
    "campaign_type": "sponsoredProducts",
    "targeting_type": "manual",
    "state": "paused"
  }
}

Note: Campaigns are created as "paused" by default for safety. Enable them manually or use the allowEnableCampaigns input field if you want campaigns to start enabled.

Step 2: Create ad group

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.ad_groups.create",
  "provider": "amazon_ads",
  "params": {
    "campaign_id": "{campaign_id_from_step_1}",
    "name": "Ad Group 1",
    "default_bid": 0.75,
    "state": "paused"
  }
}

Step 3: Add keywords

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.keywords.create",
  "provider": "amazon_ads",
  "params": {
    "ad_group_id": "{ad_group_id_from_step_2}",
    "keyword_text": "wireless headphones",
    "match_type": "broad",
    "bid": 0.80,
    "state": "paused"
  }
}

Step 4: Create product ad

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.product_ads.create",
  "provider": "amazon_ads",
  "params": {
    "ad_group_id": "{ad_group_id_from_step_2}",
    "sku": "{product_sku}",
    "state": "paused"
  }
}

Example 4: ACOS/ROAS/TACOS Optimizer

Goal: Analyze your ACOS (Advertising Cost of Sale), ROAS (Return on Ad Spend), and TACOS (Total Advertising Cost of Sale) metrics and get actionable optimization recommendations.

Required capabilities:

ads.reports.create - Request performance reports with sales and spend metrics
ads.reports.get - Retrieve report data
ads.performance.fetch - Fetch detailed performance metrics
ads.campaigns.list - Get campaign details for context
ads.campaigns.update - Update campaigns based on recommendations (optional)

Input fields:

date_range (date_range, required) - "Analysis period"
target_acos (number, min: 0, max: 100, optional) - "Target ACOS percentage"
target_roas (number, min: 0, optional) - "Target ROAS ratio"
metric_focus (select, optional) - Options: "ACOS", "ROAS", "TACOS", "All"
include_recommendations (boolean, default: true) - "Include optimization recommendations"

Example API calls

Your automation receives job_token from the webhook. Use it to call SellerShorts API:

Step 1: Get all campaigns

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.campaigns.list",
  "provider": "amazon_ads",
  "params": {
    "maxResults": 1000
  }
}

Step 2: Request performance report with sales/spend metrics

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.reports.create",
  "provider": "amazon_ads",
  "params": {
    "report_type": "campaigns",
    "start_date": "20240101",
    "end_date": "20240131",
    "metrics": ["cost", "sales", "impressions", "clicks"]
  }
}

Step 3: Fetch detailed performance metrics

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.performance.fetch",
  "provider": "amazon_ads",
  "params": {
    "entity_type": "campaign",
    "start_date": "20240101",
    "end_date": "20240131",
    "metrics": ["cost", "sales", "impressions", "clicks"]
  }
}

Step 4: Get report and calculate ACOS/ROAS

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.reports.get",
  "provider": "amazon_ads",
  "params": {
    "report_id": "{report_id_from_step_2}"
  }
}

After receiving report data, your automation calculates: ACOS = (Cost / Sales) × 100, ROAS = Sales / Cost, and generates optimization recommendations.

Example 5: Search Term Waste Cleaner (Read-only)

Goal: Identify wasteful search terms (high spend, low/no sales) and produce a negative keyword recommendation list (no auto-changes).

Required capabilities:

ads.reports.create - Request search term performance report
ads.reports.get - Retrieve report data
ads.performance.fetch - (Optional) Pull recent performance metrics
ads.keywords.list - (Optional) Context of existing keywords

Input fields:

date_range (date_range, required) - "Analysis period"
max_acos (number, optional) - "Max ACOS % before marking as waste"
min_clicks (number, optional) - "Minimum clicks to consider a term"
campaign_ids (tags, optional) - "Campaign IDs to include (empty = all)"

Output: CSV/text list of suggested negatives (term, match type suggestion, spend, clicks, sales, ACOS) with rationale. Read-only recommendations; user applies manually.

Example API calls

Use the job_token from the webhook:

Step 1: Request search term report

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.reports.create",
  "provider": "amazon_ads",
  "params": {
    "report_type": "keywords",
    "start_date": "20240101",
    "end_date": "20240131",
    "metrics": ["impressions", "clicks", "cost", "sales"]
  }
}

Step 2: Check report status and get download

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.reports.get",
  "provider": "amazon_ads",
  "params": {
    "report_id": "{report_id_from_step_1}"
  }
}

Process the downloaded data to flag waste terms; output recommended negatives (do not auto-apply).

Example 6: Search Term Optimizer (Read-only recommendations)

Goal: Identify winning and losing search terms, recommend bid up/down or negatives (no auto-changes).

Required capabilities:

ads.reports.create - Request search term performance report
ads.reports.get - Retrieve report data
ads.performance.fetch - (Optional) Pull recent performance metrics

Input fields:

date_range (date_range, required) - "Analysis period"
target_acos (number, optional) - "Target ACOS % for scaling decisions"
min_clicks (number, optional) - "Minimum clicks to consider"
campaign_ids (tags, optional) - "Campaign IDs to include (empty = all)"

Example API calls

Use the job_token from the webhook:

Step 1: Request search term report

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.reports.create",
  "provider": "amazon_ads",
  "params": {
    "report_type": "keywords",
    "start_date": "20240101",
    "end_date": "20240131",
    "metrics": ["impressions", "clicks", "cost", "sales"]
  }
}

Step 2: Check report status and get download

POST https://sellershorts.com/api/capabilities
Authorization: Bearer {job_token}
Content-Type: application/json

{
  "capability": "ads.reports.get",
  "provider": "amazon_ads",
  "params": {
    "report_id": "{report_id_from_step_1}"
  }
}

Use the report data to classify terms into scale vs. cut/negate suggestions; no automatic changes are made.

Buyer experience

Connecting Amazon Ads account

When a buyer runs your AI Tool that requires Amazon Ads:

They see a "Connect Amazon Ads Account" button on the run page
Clicking the button redirects them to Amazon's authorization page
They sign in with their Amazon Ads account credentials
They select which advertising profile to connect (if they have multiple profiles, they choose one)
They authorize SellerShorts to access their account
They're redirected back to your AI Tool's run page
The connection status shows as "Connected" and they can proceed

Connection status

Disconnecting

Error handling

Error code reference

All possible error codes returned by the capabilities API:

Error Code	Description	HTTP Status
`INVALID_TOKEN`	Job token is missing, malformed, or expired	401
`CAPABILITY_NOT_ALLOWED`	Requested capability is not supported	403
`NO_CONNECTION`	Buyer hasn't connected Amazon Ads account	400
`LIMIT_EXCEEDED`	Value exceeds buyer's input limit	400
`PERMISSION_DENIED`	Campaign enable permission denied	403
`RATE_LIMIT`	Amazon Ads API rate limit exceeded	429
`TOKEN_EXPIRED`	Amazon Ads connection expired or revoked	401
`ORDER_NOT_FOUND`	Order ID doesn't exist or access denied	404
`INVALID_REQUEST`	Invalid request parameters or format	400
`SP_API_ERROR`	Amazon Ads API returned an error	500
`INTERNAL_ERROR`	Internal server error	500

Common API errors

Detailed explanations for each error code:

INVALID_TOKEN

Code: INVALID_TOKEN
Message: "Invalid or expired job token"
Cause: Job token is missing, malformed, or expired
Solution: Ensure you're sending the token from the webhook payload in the Authorization header

CAPABILITY_NOT_ALLOWED

Code: CAPABILITY_NOT_ALLOWED
Message: "Capability 'ads.keywords.delete' is not allowed for this order"
Cause: The requested capability is not supported for safety reasons
Solution: Use a different capability that is supported. Check the FAQ section for a list of capabilities that are not available.

NO_CONNECTION

Code: NO_CONNECTION
Message: "No Amazon Ads connection found. Please connect your Amazon Ads account first."
Cause: Buyer hasn't connected their Amazon Ads account
Solution: Buyer must connect their account before running the AI Tool

LIMIT_EXCEEDED

Code: LIMIT_EXCEEDED
Message: "daily_budget (150) exceeds your limit (100)"
Cause: The requested value exceeds the buyer's input limit
Solution: Reduce the value to within the limit, or inform the buyer to increase their limit

PERMISSION_DENIED

Code: PERMISSION_DENIED
Message: "Enabling campaigns is not allowed for this AI Tool"
Cause: Your AI agent tried to set a campaign's state to "enabled", but the buyer has set allowEnableCampaigns to false in their input form
Solution: Create campaigns with "state": "paused" instead, or inform the buyer that they need to set allowEnableCampaigns to true if they want campaigns to be automatically enabled

RATE_LIMIT

Code: RATE_LIMIT
Message: "Amazon Ads API rate limit exceeded. Please try again later."
Cause: Amazon Ads API enforces rate limits. Too many requests in a short time period.
Solution: SellerShorts automatically handles rate limits by retrying requests up to 4 times with exponential backoff (1s, 2s, 4s delays). If rate limits persist after automatic retries, wait before making additional requests. Your automation doesn't need to implement retry logic. SellerShorts handles it automatically. For bulk operations, consider throttling your requests (e.g., 1 request per second) to avoid hitting limits.

TOKEN_EXPIRED

Code: TOKEN_EXPIRED
Message: "Amazon Ads connection has been revoked. Please reconnect your Amazon Ads account."
Cause: The buyer's Amazon Ads connection was revoked or expired
Solution: The buyer must reconnect their Amazon Ads account. Your automation should handle this gracefully and inform the buyer to reconnect.

ORDER_NOT_FOUND

Code: ORDER_NOT_FOUND
Message: "Order not found or access denied"
Cause: The order ID in the job token doesn't exist or doesn't belong to the buyer
Solution: Ensure you're using the correct job token from the webhook payload. If the issue persists, contact support.

INVALID_REQUEST

Code: INVALID_REQUEST
Message: "Invalid request body" or "Invalid JSON in request body" or "Unsupported provider: {provider}"
Cause: The request body is malformed, missing required fields, or uses an unsupported provider
Solution: Check that your request body is valid JSON and includes all required fields (capability, provider, and optionally params). Ensure provider is set to "amazon_ads".

SP_API_ERROR

Code: SP_API_ERROR
Message: "Failed to load Amazon Ads connection" or error message from Amazon Ads API
Cause: An error occurred when communicating with Amazon Ads API or loading the connection
Solution: Check the error details in the response. This could indicate a temporary Amazon Ads API issue, connection problem, or permission issue. Retry the request after a short delay.

INTERNAL_ERROR

Code: INTERNAL_ERROR
Message: "Internal server error"
Cause: An unexpected error occurred on SellerShorts' servers
Solution: This is a rare occurrence. Wait a few moments and retry the request. If the issue persists, contact support with the error details.

Best practices

Use capabilities appropriately

Always set safety limits

For any AI Tool that modifies budgets or bids, always add number input fields with maximum limits. This protects buyers and builds trust in your automation.

Handle errors gracefully

Your automation should handle API errors gracefully. If a capability call fails, log the error, inform the buyer through your callback response, and don't crash your automation.

Test thoroughly

Important: Always use the Test step in the submission wizard to test your AI Tool with a real Amazon Ads account connection before submitting for review. Verify that:

All required capabilities are working
Safety limits are enforced correctly
Error handling works as expected
Results are returned in the correct format

The Test step allows you to run your AI Tool end-to-end with your own Amazon Ads account, ensuring everything works correctly before buyers use it.

Document in admin review notes

When submitting your AI Tool for review, use the "Notes for Admin Review" field to explain:

Which capabilities your AI Agent uses and why
What safety limits you've set and why
What account state is needed for testing (e.g., "Requires at least one active campaign")
Any special considerations for the admin review team

FAQ

Do I need my own Amazon Ads account to publish an AI Tool?

No. You don't need an Amazon Ads account to publish an AI Tool. Buyers connect their own accounts when they run your AI Tool.

Can I test my AI Tool without a buyer account?

Yes. Use the Test step in the submission wizard. You'll need to connect your own Amazon Ads account (or a test account) to test the integration end-to-end.

What happens if a buyer doesn't have an Amazon Ads account?

They cannot run your AI Tool. The connection step is required, and they'll see instructions to create an Amazon Ads account if they don't have one.

Can I change capabilities after my AI Tool is approved?

Are there any capabilities that are not available?

Yes. The following capabilities are not supported for safety reasons:

ads.keywords.delete
ads.product_ads.delete
ads.targeting.delete
ads.budget_rules.create
ads.budget_rules.update
ads.budget_rules.associate

These capabilities are not supported to protect buyer accounts and prevent unintended changes.

How do I know which capabilities my AI agent needs?

Think about what your AI Agent needs to do:

Read-only operations: Use list and get capabilities
Creating new items: Use create capabilities
Modifying existing items: Use update capabilities
Performance data: Use ads.reports.* and ads.performance.fetch

What's next?

Now that you understand how Amazon Ads integration works, you can:

Publish your first Amazon Ads AI Tool using the Inputs step guide
Learn about webhook payloads and placeholders
Review the Test step guide to test your integration

Amazon Ads Integration

Overview

End-to-end flow (at a glance)

💡 How it works

Important: Amazon Ads Policy Responsibility

Setting up Amazon Ads in your AI Tool

Step 1: Select Amazon Ads provider

Step 2: Understand capabilities

Campaigns (4 capabilities)

Ad Groups (4 capabilities)

Keywords (4 capabilities)

Product Ads (4 capabilities)

Targeting (4 capabilities)

Reports (3 capabilities)

Performance (1 capability)

Budget Rules (2 capabilities)

Recommendations (4 capabilities)

Negative Keywords (2 capabilities)

Negative Targeting (2 capabilities)

Sponsored Brands v3 (3 capabilities)

Sponsored Display (5 capabilities)

⚠️ Default behavior

Using the job token in your webhook

Webhook payload structure

What is the job token?

API endpoint

Using the job token to call Amazon Ads API

Pagination with nextToken

Response format

Safety limits and validation

Number input fields with limits

Supported limit fields

How validation works

Campaign enable protection

✅ Best practice

Examples

Example 1: Account Performance Analyzer

Example API calls

Example 2: Sponsored Products Detailed Report

Example API calls

Example 3: Campaign Builder (Best Practices)

Example API calls

Example 4: ACOS/ROAS/TACOS Optimizer

Example API calls

Example 5: Search Term Waste Cleaner (Read-only)

Example API calls

Example 6: Search Term Optimizer (Read-only recommendations)

Example API calls

Buyer experience

Connecting Amazon Ads account

Connection status

Disconnecting

Error handling

Error code reference

Common API errors

INVALID_TOKEN

CAPABILITY_NOT_ALLOWED

NO_CONNECTION

LIMIT_EXCEEDED

PERMISSION_DENIED

RATE_LIMIT

TOKEN_EXPIRED

ORDER_NOT_FOUND

INVALID_REQUEST

SP_API_ERROR

INTERNAL_ERROR

Best practices

Use capabilities appropriately

Always set safety limits

Handle errors gracefully

Test thoroughly

Document in admin review notes

FAQ

Do I need my own Amazon Ads account to publish an AI Tool?

Can I test my AI Tool without a buyer account?

What happens if a buyer doesn't have an Amazon Ads account?

Can I change capabilities after my AI Tool is approved?

Are there any capabilities that are not available?

How do I know which capabilities my AI agent needs?

What's next?