- USD
For a better experience, use desktop or tablet.
More AI Tools are being added regularly. List your AI Tool and monetize your expertise.
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.
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 34 available capabilities are automatically enabled when you select Amazon Ads—no additional configuration is needed.
job_token.job_token to call SellerShorts → Amazon Ads. All 34 capabilities are allowed by default.job_token in the payloadIn 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.
Capabilities are permissions that define what your AI Agent can do with a buyer's Amazon Ads account.
When you select Amazon Ads, all 34 available capabilities are automatically enabled—you don't need to configure anything. These capabilities are organized into 11 categories:
How to read the parameters:
"state": "enabled" or "paused")"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."12345" or 12345)Set up and manage top-level ad campaigns, including budgets, status, and scheduling.
Required:
name (string) - Campaign namedaily_budget (number) - Daily budget amountOptional:
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 stringend_date (string) - ISO date stringportfolio_id (number) - Portfolio IDbidding (object) - Bidding strategy with optional strategy and adjustmentsAll parameters are optional:
maxResults (number, 1-1000) - Maximum number of resultscount (number, 1-100) - Legacy support, maps to maxResultsnextToken (string) - Pagination tokenstate_filter (enum) - "enabled", "paused", or "archived"name (string) - Filter by campaign namecampaign_type (enum) - "sponsoredProducts", "sponsoredBrands", or "sponsoredDisplay"portfolio_id (number) - Filter by portfolio IDcampaign_id (string|number) - Filter by specific campaign IDRequired:
campaign_id (string|number) - Campaign ID to updateOptional:
name (string) - Campaign namestate (enum) - "enabled" or "paused"daily_budget (number) - Daily budget amountstart_date (string) - ISO date stringend_date (string) - ISO date stringportfolio_id (number) - Portfolio IDbidding (object) - Bidding strategy with optional strategy and adjustmentsRequired:
campaign_id (string|number) - Campaign IDOrganize ads within a campaign and control default bids and status for each group.
Required:
campaign_id (string|number) - Parent campaign IDname (string) - Ad group nameOptional:
default_bid (number) - Default bid for the ad groupstate (enum) - "enabled" or "paused" (default: "enabled")All parameters are optional:
campaign_id (string|number) - Filter by campaignad_group_id (string|number) - Filter by ad groupmaxResults (number, 1-1000) - Maximum number of resultscount (number, 1-100) - Legacy support, maps to maxResultsnextToken (string) - Pagination tokenstate_filter (enum) - "enabled", "paused", or "archived"name (string) - Filter by ad group nameRequired:
ad_group_id (string|number) - Ad group ID to updateOptional:
name (string) - Ad group namedefault_bid (number) - Default bid amountstate (enum) - "enabled" or "paused"Required:
ad_group_id (string|number) - Ad group IDAdd and adjust the search terms you bid on, including match types and bids.
Required:
ad_group_id (string|number) - Ad group IDkeyword_text (string) - The keyword textOptional:
match_type (enum) - "broad", "exact", or "phrase" (default: "broad")bid (number) - Bid amountstate (enum) - "enabled" or "paused" (default: "enabled")All parameters are optional:
ad_group_id (string|number) - Filter by ad groupcampaign_id (string|number) - Filter by campaignkeyword_id (string|number) - Filter by keyword IDmaxResults (number, 1-1000) - Maximum number of resultscount (number, 1-100) - Legacy supportnextToken (string) - Pagination tokenstate_filter (enum) - "enabled", "paused", or "archived"match_type_filter (enum) - "broad", "exact", or "phrase"Required:
keyword_id (string|number) - Keyword ID to updateOptional:
bid (number) - Bid amountstate (enum) - "enabled" or "paused"Required:
keyword_id (string|number) - Keyword IDLink SKUs/ASINs to ad groups and control the status of individual product ads.
Required:
ad_group_id (string|number) - Parent ad group IDOptional:
sku (string) - SKU of the productasin (string) - ASIN of the productstate (enum) - "enabled" or "paused" (default: "enabled")All parameters are optional:
ad_group_id (string|number) - Filter by ad groupcampaign_id (string|number) - Filter by campaignad_id (string|number) - Filter by ad IDmaxResults (number, 1-1000) - Maximum number of resultscount (number, 1-100) - Legacy supportnextToken (string) - Pagination tokenstate_filter (enum) - "enabled", "paused", or "archived"Required:
ad_id (string|number) - Product ad ID to updateOptional:
state (enum) - "enabled" or "paused"sku (string) - SKU of the productRequired:
ad_id (string|number) - Product ad IDDefine targeting for the buyer's ads with targeting expressions, bids, and status controls.
Required:
ad_group_id (string|number) - Ad group IDOptional:
expression (array) - Targeting expressionexpression_type (enum) - "auto" or "manual" (default: "manual")bid (number) - Bid amountstate (enum) - "enabled" or "paused" (default: "enabled")All parameters are optional:
ad_group_id (string|number) - Filter by ad groupcampaign_id (string|number) - Filter by campaigntarget_id (string|number) - Filter by target IDmaxResults (number, 1-1000) - Maximum number of resultscount (number, 1-100) - Legacy supportnextToken (string) - Pagination tokenstate_filter (enum) - "enabled", "paused", or "archived"Required:
target_id (string|number) - Targeting clause ID to updateOptional:
bid (number) - Bid amountstate (enum) - "enabled" or "paused"expression (array) - Targeting expressionRequired:
target_id (string|number) - Targeting clause IDRequest, fetch, and list performance reports to analyze results over time.
Required:
report_type (string) - Report type (e.g., "campaigns", "adGroups", "keywords", "productAds")start_date (string) - Start date in YYYYMMDD formatend_date (string) - End date in YYYYMMDD formatOptional:
metrics (array of strings) - Specific metrics to includesegment (string) - Segment dimensioncampaign_type (enum) - "sponsoredProducts", "sponsoredBrands", or "sponsoredDisplay"campaign_ids (array) - Array of specific campaign IDs to includead_group_ids (array) - Array of specific ad group IDs to includeRequired:
report_id (string) - Report IDAll parameters are optional:
report_type (string) - Filter by report typestart_date (string) - Filter by start dateend_date (string) - Filter by end datemaxResults (number, 1-100) - Maximum number of resultsnextToken (string) - Pagination tokenQuickly fetch performance metrics for campaigns, ad groups, keywords, or product ads.
Required:
entity_type (enum) - "campaign", "adGroup", "keyword", "productAd", or "target"start_date (string) - Start date in YYYYMMDD or ISO formatend_date (string) - End date in YYYYMMDD or ISO formatOptional:
entity_ids (array) - Array of specific entity IDs to fetchmetrics (array of strings) - Specific metrics to fetchcampaign_id (string|number) - Filter by campaign IDad_group_id (string|number) - Filter by ad group IDView existing budget rules and their details to understand automated budget changes.
All parameters are optional:
pageSize (number, 1-30) - Number of results per page (default: 30)nextToken (string) - Pagination tokenRequired:
budget_rule_id (string) - Budget rule IDGet AI-powered recommendations for keywords, product targeting, and budget optimization to improve campaign performance.
Required:
recommendation_type (enum) - "KEYWORDS_FOR_ASINS" or "KEYWORDS_FOR_ADGROUP"asins (array of strings) - List of product ASINscampaign_id and ad_group_id (string|number) - Existing campaign and ad group IDsOptional:
targets (array) - User-defined keywords to rank alongside recommendationslocale (string) - Locale for keyword translationsmaxRecommendations (number, 0-200) - Maximum number of recommendations (default: 200)sortDimension (enum) - "CLICKS", "CONVERSIONS", or "DEFAULT" (default: "DEFAULT")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 formatcursor (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.
Required:
campaign_ids (array of strings|numbers, 1-100 items) - List of campaign IDs to analyzeReturns recommended daily budget, percent time in budget, and estimated missed impressions/clicks/sales.
Required:
ad_groups (array) - Ad group information for the new campaign (exactly 1 item required)bidding (object) - Bidding strategy configurationtargeting_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)Create negative keywords to prevent your ads from showing on unwanted search terms, improving campaign efficiency.
Required:
ad_group_id (string|number) - Parent ad group IDkeyword_text (string) - The negative keyword textOptional:
match_type (enum) - "NEGATIVE_BROAD", "NEGATIVE_EXACT", "NEGATIVE_PHRASE", or "OTHER" (default: "NEGATIVE_BROAD")Required:
campaign_id (string|number) - Parent campaign IDkeyword_text (string) - The negative keyword textOptional:
match_type (enum) - "NEGATIVE_BROAD", "NEGATIVE_EXACT", "NEGATIVE_PHRASE", or "OTHER" (default: "NEGATIVE_BROAD")Create negative targeting clauses to exclude specific products or categories from your ad targeting.
Required:
ad_group_id (string|number) - Parent ad group IDOptional:
expression (array) - Targeting expression to excludeexpression_type (enum) - "auto" or "manual" (default: "manual")Required:
campaign_id (string|number) - Parent campaign IDOptional:
expression (array) - Targeting expression to excludeexpression_type (enum) - "auto" or "manual" (default: "manual")All 34 capabilities 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.
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..."
}The job_token is an encrypted token that contains:
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).
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.
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:
If all checks pass, SellerShorts makes the actual API call to Amazon Ads on your behalf and returns the result.
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:
maxResults (e.g., 1000)next_tokennext_token exists, make another request with the same parameters plus nextToken: {next_token}next_token is null or missingExample: 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.
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"
}
}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.
The system checks for these input field keys (case-insensitive, flexible naming):
maxDailyBudget, max_daily_budget, dailyBudgetMax, maxDailyBudgetLimitmaxBid, max_bid, bidMax, maxBidLimitmaxDefaultBid, max_default_bidWhen 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:
{"status": "error", "error": {"code": "LIMIT_EXCEEDED", "message": "daily_budget (150) exceeds your limit (100)"}}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.
To prevent your AI Agent from automatically enabling campaigns, you can add a boolean input field with one of these keys:
allowEnableCampaignsallow_enable_campaignsallowCampaignEnableIf 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.
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.
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 accountads.ad_groups.list - Get all ad groups for contextads.keywords.list - Get all keywords for analysisads.product_ads.list - Get all product adsads.reports.create - Request comprehensive performance reportsads.reports.get - Retrieve report dataads.performance.fetch - Fetch detailed performance metricsInput 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.
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"
}
}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 URLads.campaigns.list - Get campaign details for contextads.ad_groups.list - Get ad group details for contextads.performance.fetch - Fetch additional performance metricsInput 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.
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:
url fieldstatusDetails 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;
}
}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 settingsads.ad_groups.create - Create ad groups within campaignsads.keywords.create - Add keywords to ad groupsads.product_ads.create - Create product adsads.targeting.create - Create targeting clausesInput 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.
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"
}
}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 metricsads.reports.get - Retrieve report dataads.performance.fetch - Fetch detailed performance metricsads.campaigns.list - Get campaign details for contextads.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.
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.
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 reportads.reports.get - Retrieve report dataads.performance.fetch - (Optional) Pull recent performance metricsads.keywords.list - (Optional) Context of existing keywordsInput 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.
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).
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 reportads.reports.get - Retrieve report dataads.performance.fetch - (Optional) Pull recent performance metricsInput 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.
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.
When a buyer runs your AI Tool that requires Amazon Ads:
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.
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.
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.
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 |
Detailed explanations for each error code:
INVALID_TOKENCAPABILITY_NOT_ALLOWEDNO_CONNECTIONLIMIT_EXCEEDEDPERMISSION_DENIEDstate to "enabled", but the buyer has set allowEnableCampaigns to false in their input form"state": "paused" instead, or inform the buyer that they need to set allowEnableCampaigns to true if they want campaigns to be automatically enabledRATE_LIMITTOKEN_EXPIREDORDER_NOT_FOUNDINVALID_REQUESTcapability, provider, and optionally params). Ensure provider is set to "amazon_ads".SP_API_ERRORINTERNAL_ERRORAll 34 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.
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.
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.
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:
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.
When submitting your AI Tool for review, use the "Notes for Admin Review" field to explain:
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.
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.
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.
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.
Yes. The following capabilities are not supported for safety reasons:
ads.keywords.deleteads.product_ads.deleteads.targeting.deleteads.budget_rules.createads.budget_rules.updateads.budget_rules.associateThese capabilities are not supported to protect buyer accounts and prevent unintended changes.
Think about what your AI Agent needs to do:
list and get capabilitiescreate capabilitiesupdate capabilitiesads.reports.* and ads.performance.fetchNow that you understand how Amazon Ads integration works, you can: