Developer API
Programmatic, key-authenticated access to your Amazon Advertising, Amazon DSP, Amazon Marketing Cloud (AMC), Seller Central, and Vendor Central data and actions. SellerMate already collects, normalises and keeps this data for every connected account (history retained by plan, unlimited on Unlimited and Enterprise), so there is no Amazon API approval, report pipeline or warehouse to build. The Public API is a thin, stable surface over the same engine that powers SellerMate’s app and AI agent, so every call is permission-checked, policy-guarded, and audit-logged.
Base URL
https://api.sellermate.ai
Version prefix
/public/v1
Content type
application/json
OpenAPI spec
/public/v1/openapi.jsonNew tools ship regularly. GET /public/v1/tools always returns the live set your key can call, so treat it as the source of truth.
Building with Claude, ChatGPT or Cursor? Give it this page’s URL — every tool and parameter is listed in §6 — or point it at the raw OpenAPI spec.
Every request must carry your API key, sent either way:
1X-API-Key: sm_live_xxxxxxxxxxxxxxxxxxxx
or
1Authorization: Bearer sm_live_xxxxxxxxxxxxxxxxxxxx
sm_live_….Per-key rate limit: default 120 requests/minute. Exceeding it returns 429 with a Retry-After header (seconds) — honor it before retrying.
Failed-auth lockout: repeated invalid-key attempts from one IP are locked out (429 + Retry-After). Don’t retry on a 401 — a bad key won’t start working.
{ "status": <code>, "message": "..." }{ "error": "..." } (policy violations also include rule, scope, message).| Code | Meaning |
|---|---|
200 | Success — body is the tool result. |
400 | Invalid or missing arguments. |
401 | Auth failed — always a generic { "message": "Invalid API key" }. |
403 | Your key's scope doesn't permit this tool, or the account isn't allowed for the key. |
404 | Unknown tool. |
422 | A workspace policy rejected a write (includes rule/scope/message). |
429 | Rate limit exceeded, or too many failed auth attempts. See Retry-After. |
500 | Internal error. |
Every tool is invoked the same way: POST /public/v1/tools/{tool_name} with a JSON object of arguments. A few rules apply across all tools, so each tool below only lists what’s unique to it.
workspace_id is taken from your key automatically. If your key is limited to one Amazon account, amazon_account_id is filled in for you too; if your key spans multiple accounts, pass amazon_account_id to choose one. Call get_user_context to list the accounts (and their accountType: seller / vendor / agency) your key can use. (get_marketplace_summary takes a list, amazon_account_ids, to span accounts.)YYYY-MM-DD strings (start_date, end_date). Exception: get_sqp_report uses integer month + year.pagination block — { page, pageSize, total, totalPages, hasMore, nextCursor } — alongside the rows. Pass page (0-indexed, default 0) and page_size (default 100, max 500) to walk pages. summary/totals always cover the full result set, not the page. (Catalog tools use limit/offset instead — noted inline.)sort_field (a metric) + sort_direction (asc|desc, default desc).cost (spend), attributedSales14d (sales), impressions, clicks, purchases (orders), acos, roas, ctr, cpc, cvr.GET /public/v1/tools/{name} returns the live JSON Schema for any tool — the source of truth if this page ever lags the API./public/v1/toolsList the tools your key can use (filtered to its scope). Each entry includes the tool’s JSON Schema — handy for discovery and codegen.
1curl -s https://api.sellermate.ai/public/v1/tools -H "X-API-Key: sm_live_..."
/public/v1/tools/{name}Return the JSON Schema for one tool. 404 if unknown or outside your scope.
/public/v1/tools/{name}Invoke a tool. Body = the tool’s arguments. Returns the raw tool result.
1curl -s -X POST https://api.sellermate.ai/public/v1/tools/get_campaign_performance \2 -H "X-API-Key: sm_live_..." -H "Content-Type: application/json" \3 -d '{"start_date":"2026-05-01","end_date":"2026-05-31"}'
/public/v1/openapi.jsonMachine-readable OpenAPI 3.1 spec for the whole API — one documented operation per tool, generated live from the same registry the API serves. No auth required. Import it into Postman or Insomnia, or feed it to a codegen. Rendered as a browsable reference at api.sellermate.ai/public/v1/docs.
The full tool catalog — every tool’s parameters, scope (R tools:read / W tools:write) and description — is listed below, generated from the live API so it always matches what your key can actually call. The interactive reference shows the same catalog with full JSON schemas, sample requests in curl, Python and Node, and a console to try calls against your own key.
Interactive API reference
All tools, grouped by category — Discovery, Campaigns, Targeting, Negatives, Products & Reports, Tags, Amazon DSP, Amazon Marketing Cloud (AMC), Vendor Central, Knowledge Files, Automation & Dayparting, Insights & Alerts — with a built-in console to try calls against your own key.
Open the tools referenceworkspace_id is never sent (bound to your key); amazon_account_id is auto-filled for single-account keys — see §4.GET /public/v1/tools returns exactly the tools your key’s scopes allow — the reference shows the full catalog.R tools:read · W tools:write · generated from the live spec
Expand a tool for its description and parameters. Every tool is called the same way — POST /public/v1/tools/{name} with a JSON body — and the account rules in §4 apply to all of them.
Find your workspaces, Amazon accounts, what SellerMate supports, and which report data has arrived.
check_data_coverageCheck Data CoverageCheck Data Coverage
POST /public/v1/tools/check_data_coverage · requires tools:read
Which days of Amazon report data have actually arrived, so a day that has not synced yet is not read as zero spend. Pass the accounts as amazon_account_ids. One account (mode: "reports", the default for one id): per feed (campaign, targeting, search-term and advertised-product ads feeds, plus Seller Central and Vendor Central product feeds) a status, the latest date with rows, and datesWithNoRows; use latestDateAllFeedsHaveRows as the end date for any answer that mixes ads and retail (TACoS); notMonitored lists feeds with no coverage evidence here (placements, SQP, SCP, DSP, orders); mode: "reports_daily" adds a row count per date. Several accounts (mode: "summary", the default for several ids, up to 300): each account's last day of campaign, Seller Central and Vendor Central data on its own calendar, plus the day most active accounts have data through. days sets the window (default 17, max 60). Read-only — never triggers a sync.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idsrequired | array of string | The Amazon account or accounts to check: 1-300 ids of this workspace's accounts. One id: report-by-report status (mode 'reports'). Several ids: one row per account (mode 'summary'). |
mode | enum | 'reports' (default for one account): every report with its status, latest date and the dates with no rows. 'reports_daily': the same plus 'counts', the row count for every date -- use it to see a gradual decline, which no status or anomaly flag will report. 'summary' (default for several accounts): the last day of each account's top-level reports. 'reports' and 'reports_daily' take one account.One of: summary, reports, reports_daily |
days | integer | Size of the window to inspect, counting back from today and including it. Defaults to 17, the same window the in-app sync dialog shows. Min 2, max 60. |
get_sellermate_capabilitiesGet Sellermate CapabilitiesGet Sellermate Capabilities
POST /public/v1/tools/get_sellermate_capabilities · requires tools:read
What the SellerMate platform supports beyond these API tools, with deep links. Pass an optional query describing what you're trying to do.
| Parameter | Type | Description |
|---|---|---|
query | string | What the user is trying to do, e.g. 'dayparting', 'create campaigns', 'organic vs ads data', 'track competitor rankings'. Used to highlight the most relevant capabilities in the response. |
amazon_account_id | string | Optional Amazon account ID to build direct deep links. Auto-filled when your API key is restricted to a single Amazon account. |
get_user_contextGet User ContextGet User Context
POST /public/v1/tools/get_user_context · requires tools:read
Your accessible workspaces and Amazon accounts — each account with id, name, accountType (seller / vendor / agency), country, currency, and marketplace, plus hasDsp (an active Amazon DSP advertiser is linked). Call this first to get the account IDs the other tools need. Pass has_dsp: true to return only DSP-enabled accounts.
| Parameter | Type | Description |
|---|---|---|
account_name_search | string | Optional. Case-insensitive substring to filter accounts by name. Use this to resolve a named account (e.g. 'rolex') to its ids. |
has_dsp | boolean | Optional. true returns ONLY accounts with an active Amazon DSP advertiser linked; false returns only those without. Omit for all accounts. Use has_dsp=true to answer 'which of my accounts have DSP?' in one call, then pass those ids to get_dsp_performance. |
page | integer | Page number (0-indexed). Defaults to 0. |
page_size | integer | Accounts per page. Defaults to 50. Max 200. |
resolve_accountResolve AccountResolve Account
POST /public/v1/tools/resolve_account · requires tools:read
Resolve an Amazon account by name to its workspace_id and amazon_account_id, so account-scoped tools can be called without listing everything via get_user_context.
| Parameter | Type | Description |
|---|---|---|
queryrequired | string | Account name (or part of it) to resolve, e.g. 'Rolex'. |
Campaign and ad-group inventory, performance, budgets, and creation.
add_products_to_ad_groupAdd Products to Ad GroupAdd Products to Ad Group
POST /public/v1/tools/add_products_to_ad_group · requires tools:write
Add up to 50 products (ASIN product ads) to existing ad groups. Each item needs campaign_id, ad_group_id and asin; seller accounts also need sku, vendor accounts advertise by ASIN alone. state defaults to ENABLED. Resolve ASIN / SKU pairs with list_product_catalog.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
productsrequired | array of object | Products to add to existing ad groups.Fields: campaign_id*, ad_group_id*, asin*, sku, state (* required) |
_reasoning | string | Briefly explain why. Stored for audit. |
create_ad_groupCreate Ad GroupCreate Ad Group
POST /public/v1/tools/create_ad_group · requires tools:write
Create one or more ad groups inside an existing Sponsored Products campaign, each with a name, default_bid and at least one product; keywords / product_targets are accepted on MANUAL campaigns only. Names must be unique within the campaign. All-or-nothing: an invalid ad group, or a bid blocked by the workspace bid policy (maxBid / minBid), returns 422 and nothing is submitted to Amazon.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
campaign_idrequired | string | Amazon campaign ID of the EXISTING campaign to add to (from list_campaigns). Must be Sponsored Products and not archived. |
ad_groupsrequired | array of object | Ad groups to create. Each needs a name, a default_bid and at least one product; keywords / product_targets are MANUAL-only.Fields: name*, default_bid*, state, products*, keywords, product_targets, negative_keywords, negative_product_targets (* required) |
_reasoning | string | Briefly explain why the user wants these ad groups. Stored for audit and shown to admins in the activity log. |
create_campaignCreate CampaignCreate Campaign
POST /public/v1/tools/create_campaign · requires tools:write
Create one Sponsored Products campaign (one ad group, one or more products). Asynchronous: returns a session_id — poll get_campaign_creation_status. Subject to workspace campaign-creation policies (budget caps, targeting-type restrictions); a policy-blocked create returns 422 and is not submitted.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
namerequired | string | Campaign name. Must be unique within the account. |
sponsored_typerequired | enum | Amazon ad type. Only 'Product' (Sponsored Products) is supported today.One of: Product |
targeting_typerequired | enum | AUTO lets Amazon pick targets automatically (no keywords or product_targets allowed). MANUAL requires at least one keyword or product target.One of: AUTO, MANUAL |
state | enum | Campaign state. Defaults to ENABLED.One of: ENABLED, PAUSED |
daily_budgetrequired | number | Daily budget (absolute number, in the account's currency). Subject to workspace maxStartingBudget. |
start_date | string | Optional campaign start date in YYYY-MM-DD format. Omit to start immediately. Must not be in the past. |
end_date | string | Optional campaign end date in YYYY-MM-DD format. Omit to run with no end date. Must not be before start_date. |
ad_group | object | Legacy single ad group (one ad group only). Prefer ad_groups (array) for one or more ad groups. Sponsored Products campaigns must have at least one ad group with at least one product.Fields: name*, default_bid*, state, products*, keywords, product_targets, negative_keywords, negative_product_targets (* required) |
dynamic_bidding | object | Optional Sponsored Products bidding strategy + placement bid adjustments. Shape: {strategy, placementBidding: [{placement, percentage}]}. Provide strategy and/or placementBidding. Omit the whole object to use Amazon's defaults (LEGACY_FOR_SALES, no placement adjustments).Fields: strategy, placementBidding |
_reasoning | string | Briefly explain why the user wants this campaign created. Stored for audit and shown to admins in the activity log. |
confirm | boolean | Must be true to queue campaign creation. Omit or set false on the first call to receive a preview (or an incomplete response if required fields are missing). Re-call with confirm=true only after the user explicitly approves the preview, and send the confirmation_token from that preview with it. |
confirmation_token | string | The confirmation_token returned by the preview call. Required with confirm=true. It is tied to the exact arguments that were previewed, so changing any argument after the preview invalidates it and a new preview is required. |
ad_groups | array of object | One or more ad groups. Preferred over the legacy single ad_group. Each ad group has its own name, default_bid, products, and (for MANUAL campaigns) keywords/product_targets. Each ad group requires at least one product. Every product needs an ASIN; SKU is required only for seller accounts (vendor accounts advertise by ASIN alone).Fields: name*, default_bid*, state, products*, keywords, product_targets, negative_keywords, negative_product_targets (* required) |
get_campaign_creation_statusGet Campaign Creation StatusGet Campaign Creation Status
POST /public/v1/tools/get_campaign_creation_status · requires tools:read
Poll an asynchronous create_campaign job by session_id. Returns per-step status and the new campaignId once Amazon assigns it.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
session_idrequired | string | Session id returned by create_campaign. The session must belong to the same workspace + amazon_account. |
get_campaign_performanceGet Campaign PerformanceGet Campaign Performance
POST /public/v1/tools/get_campaign_performance · requires tools:read
Ads metrics per campaign over a date range — spend, sales, ACOS, ROAS, CTR, CPC, orders, CVR — plus a full-set summary. Defaults to ENABLED campaigns; pass campaign_ids or status to include paused/archived. Paginated.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | The Amazon account ID Auto-filled when your API key is restricted to a single Amazon account. |
start_daterequired | string | Start date in YYYY-MM-DD format |
end_daterequired | string | End date in YYYY-MM-DD format |
campaign_ids | array of string | Optional campaign IDs. When set, metrics are returned for these IDs regardless of campaign state. |
campaign_name | string | Filter by campaign name (partial match). Metrics are returned for matching campaigns regardless of state. |
status | array of enum | Campaign states to include. Defaults to ENABLED only. Set explicitly when the user asks for paused or archived campaigns. |
sponsored_type | array of enum | Optional ad-type filter. Pass ["Product"] for Sponsored Products (SP), ["Brand"] for Sponsored Brands (SB), ["Display"] for Sponsored Display (SD). Required whenever the user asks about SP-only, SB-only or SD-only numbers — without it the rows AND the summary totals mix all ad types together. |
group_by | array of enum | Dimensions to group rows by. Defaults to ['campaignName', 'campaignId'] — one row per campaign for the whole date range. Add exactly ONE time dimension for a trend: 'timeWindowStart' (daily), 'week', 'month' or 'year'. The bucket is returned on each row under that same key, and the date range still bounds the query — group_by only decides how rows are split inside it. Drop campaignName/campaignId for an account-level total per bucket (e.g. group_by=['month'] for monthly account spend). Add 'sponsoredType' for an SP/SB/SD split. Ignored when group_by_tag is true. The summary always covers the FULL result set across every bucket, so do not present it as one period's number. |
tag_values | array of string | Optional legacy tag labels. Only ENABLED campaigns with an active tag assignment are included unless status or campaign_name is specified. |
group_by_tag | boolean | When true, results are one row per tag (rollup metrics by tag). Each row includes tagValue instead of per-campaign breakdown. |
sort_field | enum | Field to sort results by. Defaults to 'cost'.One of: cost, attributedSales14d, impressions, clicks, purchases, acos, roas, ctr, cpc, cvr |
sort_direction | enum | Sort direction. Defaults to 'desc'.One of: asc, desc |
page_size | integer | Number of results per page. Defaults to 100. Max 500. |
page | integer | Page number (0-indexed). Defaults to 0. |
get_marketplace_summaryGet Marketplace SummaryGet Marketplace Summary
POST /public/v1/tools/get_marketplace_summary · requires tools:read
Aggregated ads metrics per account across the workspace. Takes amazon_account_ids (list) — defaults to all accounts the key can reach.
| Parameter | Type | Description |
|---|---|---|
start_daterequired | string | Start date in YYYY-MM-DD format |
end_daterequired | string | End date in YYYY-MM-DD format |
amazon_account_ids | array of string | Optional list of account IDs. Defaults to all accounts in workspace. |
get_placement_performanceGet Placement PerformanceGet Placement Performance
POST /public/v1/tools/get_placement_performance · requires tools:read
Metrics per placement (Top of Search / Product Page / Rest of Search; SB also Home) per campaign, plus bid-adjustment % and bidding strategy. Set sponsored_type for SP-only or SB-only numbers. Paginated; supports a metrics selector.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
start_daterequired | string | Start date in YYYY-MM-DD format. |
end_daterequired | string | End date in YYYY-MM-DD format. |
group_by | array of enum | Dimensions to group results by. Defaults to ['campaignId', 'placementClassification', 'sponsoredType'] — one row per campaign x placement x ad type, with metadata (campaign name, bidding strategy, bid adjustments) joined in. Drop campaignId for an account-level summary. Use time fields (week/month) for trend analysis. NEVER include campaignName — campaign names come from metadata enrichment, not grouping. |
metrics | array of enum | Metrics to fetch. Defaults to the full set. Raw additive metrics are always included internally so that derived metrics stay correct after the SB Home/Homepage alias merge. |
campaign_ids | array of string | Filter to specific campaigns by ID. |
campaign_names | array of string | Filter to specific campaigns by name (case-insensitive PARTIAL match, same as get_campaign_performance's campaign_name). Names are resolved to campaign IDs via a CampaignData lookup before the fetch — faster than name-based matching and avoids ambiguity when two campaigns share a name. |
sponsored_type | array of enum | Optional ad-type filter. Pass ["Product"] for Sponsored Products (SP), ["Brand"] for Sponsored Brands (SB), ["Display"] for Sponsored Display (SD). Required whenever the user is asking about SP-only or SB-only metrics — without it the response (and summary totals) mixes all ad types. |
placement_classification | array of enum | Filter to specific placements. Uses this tool's canonical names (Top of Search / Product Page / Home / Rest of Search); they are translated to the smbot internal vocabulary before fetching. Consumer placements only — Amazon Business (B2B) has no value here. Omit this filter to see every placement the account has, including any whose name is not in the list above. |
state | array of enum | Filter by campaign state. |
campaign_targeting_type | array of enum | Filter by campaign targeting type (auto vs manual targeting). |
sort_field | enum | Field to sort results by. Defaults to 'cost'.One of: cost, attributedSales14d, impressions, clicks, purchases, acos, roas, ctr, cpc, cvr |
sort_direction | enum | Sort direction. Defaults to 'desc'.One of: asc, desc |
page_size | integer | Number of results per page. Defaults to 100. Max 500. |
page | integer | Page number (0-indexed). Defaults to 0. |
list_ad_groupsList Ad GroupsList Ad Groups
POST /public/v1/tools/list_ad_groups · requires tools:read
Ad-group inventory (no metrics): adGroupId, name, parent campaignId / campaignName, campaignState, state, defaultBid, sponsoredType. This is where every ad-group-scoped write gets its ad_group_id. Defaults to ENABLED — pass state (or ["ALL"]) to widen; filter by campaign_id (recommended: an account-wide call can return thousands), campaign_ids, name_search or sponsored_type. Check campaignState before writing — Amazon rejects writes to ad groups of an archived campaign. Paginated.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
campaign_id | string | Filter to one campaign by its Amazon campaignId (from list_campaigns). Strongly recommended — an account-wide call can return thousands of ad groups. |
campaign_ids | array of string | Filter to several campaigns by Amazon campaignId. |
name_search | string | Search ad groups by name (case-insensitive partial match). |
state | array of enum | Filter by ad group state. Defaults to ENABLED only. Pass ['ALL'] to return every state. |
sponsored_type | array of enum | Filter by ad type (Sponsored Products, Brands, Display). |
page_size | integer | Number of results per page. Defaults to 100. Max 500. |
page | integer | Page number (0-indexed). Defaults to 0. |
list_campaignsList CampaignsList Campaigns
POST /public/v1/tools/list_campaigns · requires tools:read
Campaign inventory (no performance metrics): name, state, budget, type, targeting type, and budgetUsage — the newest budget-utilisation reading (percent of that day's budget, can exceed 100; asOf; account-local date; isToday). The newest reading is often from an earlier day, so check isToday before treating it as today's usage; null means no reading in the last 14 days. Defaults to ENABLED campaigns — pass status or name_search to widen.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | The Amazon account ID (from get_user_context) Auto-filled when your API key is restricted to a single Amazon account. |
status | array of enum | Filter by campaign status. Defaults to ENABLED only. Omit when using name_search to find a campaign regardless of state. |
sponsored_type | array of enum | Filter by ad type (Sponsored Products, Brands, Display). |
name_search | string | Search campaigns by name (case-insensitive partial match). |
page_size | integer | Number of results per page. Defaults to 100. Max 500. |
page | integer | Page number (0-indexed). Defaults to 0. |
update_ad_groupUpdate Ad GroupUpdate Ad Group
POST /public/v1/tools/update_ad_group · requires tools:write
Update up to 50 ad groups per call: state (ENABLED / PAUSED), default_bid and/or name per ad_group_id from list_ad_groups. Sponsored Products only — Sponsored Brands / Display items are rejected individually while the rest apply. Ad groups are never archived; PAUSED is the stop state. Atomic against workspace policy (neverPause, maxBid / minBid): one blocked field returns 422 and the whole batch is left untouched.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
updatesrequired | array of object | Per-ad-group updates. Each needs ad_group_id plus at least one of state/default_bid/name.Fields: ad_group_id*, state, default_bid, name (* required) |
_reasoning | string | Briefly explain why the user wants this change. Stored for audit. |
update_campaignUpdate CampaignUpdate Campaign
POST /public/v1/tools/update_campaign · requires tools:write
Update up to 50 campaigns per call; each item needs campaign_id plus at least one of state (ENABLED / PAUSED / ARCHIVED), budget (new absolute daily budget, not a delta) or dynamic_bidding (Sponsored Products only: bidding strategy — LEGACY_FOR_SALES, AUTO_FOR_SALES, MANUAL, RULE_BASED — and/or placementBidding: [{placement, percentage}], 0–900, merged into the campaign's existing settings). ARCHIVED is permanent, Sponsored Products only, and must be the only field on its item; it also pauses every ad group in the campaign. Atomic against workspace policy (budget min / max / multiplier, neverPause, neverArchive): one blocked field returns 422 and nothing is sent to Amazon.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
updatesrequired | array of object | Per-campaign updates. Each needs campaign_id plus at least one of state/budget/dynamic_bidding.Fields: campaign_id*, state, budget, dynamic_bidding (* required) |
_reasoning | string | Briefly explain why the user wants this change. Stored for audit. |
Targets (keywords / product / auto): inventory, performance, and bids.
add_targetsAdd TargetsAdd Targets
POST /public/v1/tools/add_targets · requires tools:write
Add up to 50 keyword or product targets to existing ad groups of MANUAL Sponsored Products campaigns (AUTO campaigns reject explicit targets). Each item needs campaign_id, ad_group_id, an absolute bid, and exactly one of keyword_text + match_type (BROAD / EXACT / PHRASE) or an expression list of {type, value} predicates (e.g. ASIN_SAME_AS, ASIN_CATEGORY_SAME_AS). A duplicate already in the ad group is rejected per item while the rest apply. Atomic against the workspace bid policy (maxBid / minBid): one blocked bid returns 422 and nothing is sent to Amazon.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
targetsrequired | array of object | Targets to add to existing ad groups. Each item is either a keyword (keyword_text + match_type) or a product target (expression) — never both.Fields: campaign_id*, ad_group_id*, keyword_text, match_type, expression, bid*, state (* required) |
_reasoning | string | Briefly explain why. Stored for audit. |
get_search_term_performanceGet Search Term PerformanceGet Search Term Performance
POST /public/v1/tools/get_search_term_performance · requires tools:read
Customer search queries that triggered your ads, with their metrics; default grouping is search term. Paginated.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | The Amazon account ID Auto-filled when your API key is restricted to a single Amazon account. |
start_daterequired | string | Start date in YYYY-MM-DD format |
end_daterequired | string | End date in YYYY-MM-DD format |
group_by | array of enum | Dimensions to group results by. Defaults to ['searchTerm']. Include 'targetingValue' to see which target each search term matched. Include 'campaignName' to break down by campaign. |
search_term | string | Filter by search term — case-insensitive PARTIAL match (e.g. 'yoga' returns 'yoga mat' and 'best yoga block'). |
campaign_ids | array of string | Filter to specific campaigns by ID. |
ad_group_ids | array of string | Filter to specific ad groups by ID. |
targeting_type | array of enum | Filter by the targeting type that triggered the search term. |
sort_field | enum | Field to sort results by. Defaults to 'cost'.One of: cost, attributedSales14d, impressions, clicks, purchases, acos, roas, ctr, cpc, cvr |
sort_direction | enum | Sort direction. Defaults to 'desc'.One of: asc, desc |
page_size | integer | Number of results per page. Defaults to 100. Max 500. |
page | integer | Page number (0-indexed). Defaults to 0. |
tag_values | array of string | Optional legacy tag labels. For campaigns, only ENABLED campaigns with an active tag assignment are included unless status or a named campaign is specified. |
group_by_tag | boolean | When true, results are one row per tag (rollup metrics by tag). Each row includes tagValue. include_tags is ignored when true. |
include_tags | boolean | When true (and group_by_tag is false), each row includes tags loaded from MarketingData after metrics (legacy tag assignments: value, color, bgColor, tagEntityId). |
get_targeting_performanceGet Targeting PerformanceGet Targeting Performance
POST /public/v1/tools/get_targeting_performance · requires tools:read
Metrics per target over a date range; default grouping is targeting value + campaign. Filter by campaign/ad-group/type; sortable. Paginated.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | The Amazon account ID Auto-filled when your API key is restricted to a single Amazon account. |
start_daterequired | string | Start date in YYYY-MM-DD format |
end_daterequired | string | End date in YYYY-MM-DD format |
group_by | array of enum | Dimensions to group results by. Defaults to ['targetingValue', 'campaignName']. Use time fields (week, month) for trend analysis. reportType maps to ad type: spTargetingDaily=Sponsored Products, sbTargetingDaily=Sponsored Brands, sdTargetingDaily=Sponsored Display. |
campaign_ids | array of string | Filter to specific campaigns by ID. |
ad_group_ids | array of string | Filter to specific ad groups by ID. |
targeting_type | array of enum | Filter by targeting type. Keyword: EXACT/PHRASE/BROAD. Product: ASIN_SAME_AS/ASIN_BRAND_SAME_AS/ASIN_CATEGORY_SAME_AS. Auto: LOOSE_MATCH/CLOSE_MATCH/SUBSTITUTES/COMPLEMENTS. |
targeting_value | string | Filter by targeting value (keyword text or ASIN) — case-insensitive PARTIAL match. |
sponsored_type | array of enum | Filter by ad type. |
sort_field | enum | Field to sort results by. Defaults to 'cost'.One of: cost, attributedSales14d, impressions, clicks, purchases, acos, roas, ctr, cpc, cvr |
sort_direction | enum | Sort direction. Defaults to 'desc'.One of: asc, desc |
page_size | integer | Number of results per page. Defaults to 100. Max 500. |
page | integer | Page number (0-indexed). Defaults to 0. |
tag_values | array of string | Optional legacy tag labels. For campaigns, only ENABLED campaigns with an active tag assignment are included unless status or a named campaign is specified. |
group_by_tag | boolean | When true, results are one row per tag (rollup metrics by tag). Each row includes tagValue. include_tags is ignored when true. |
include_tags | boolean | When true (and group_by_tag is false), each row includes tags loaded from MarketingData after metrics (legacy tag assignments: value, color, bgColor, tagEntityId). |
list_targetsList TargetsList Targets
POST /public/v1/tools/list_targets · requires tools:read
Full target inventory (keywords / product / auto): id, current bid, state, match type, keyword text or product expression, parent campaign/ad-group ids, marketplace/country. Returns ALL states by default. No metrics. Paginated.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | The Amazon account ID (from get_user_context) Auto-filled when your API key is restricted to a single Amazon account. |
state | array of enum | Filter by target state. Omit (or pass ['ALL']) to return targets in ALL states — list_targets is a full inventory call, not performance-bound. |
sponsored_type | array of enum | Filter by ad type (Sponsored Products/Brands/Display). |
campaign_id | string | Filter targets to a specific campaign by campaign ID. |
ad_group_id | string | Filter targets to a specific ad group by ad group ID (from list_ad_groups). |
keyword_text | string | Search for targets by keyword text — case-insensitive PARTIAL match against the target's keyword text / targeting value. |
start_date | string | Start date in YYYY-MM-DD format. Defaults to 30 days ago. |
end_date | string | End date in YYYY-MM-DD format. Defaults to today. |
page_size | integer | Number of results per page. Defaults to 100. Max 500. |
page | integer | Page number (0-indexed). Defaults to 0. |
include_tags | boolean | When true, each target includes active legacy tags for its targetingValue (loaded from MarketingData). |
update_targetUpdate TargetUpdate Target
POST /public/v1/tools/update_target · requires tools:write
Update up to 50 keyword or product targets per call; each item needs target_id from list_targets plus at least one of bid (absolute, sent to Amazon), state (ENABLED / PAUSED / ARCHIVED — ARCHIVED is permanent) or baseBid. baseBid is SellerMate-only and never sent to Amazon: it is the reference bid that bid dayparting and automation multipliers apply to, and this is the only tool that sets it; an item with only baseBid makes no Amazon change. Atomic against workspace policy (bid multiplier, neverPause, neverArchive): one blocked field returns 422.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
updatesrequired | array of object | Per-target updates. Each needs target_id plus at least one of bid/state/baseBid.Fields: target_id*, bid, state, baseBid (* required) |
_reasoning | string | Briefly explain why. Stored for audit. |
Negative keywords and negative product targets.
add_negative_keywordsAdd Negative KeywordsAdd Negative Keywords
POST /public/v1/tools/add_negative_keywords · requires tools:write
Add up to 50 negative keywords to existing campaigns or ad groups. Each item needs campaign_id, keyword_text and match_type (NEGATIVE_EXACT / NEGATIVE_PHRASE / NEGATIVE_BROAD); include ad_group_id for an ad-group-level negative, omit it for campaign level. state defaults to ENABLED. Atomic: a negation blocked by workspace policy returns 422 and nothing is sent to Amazon.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
negativesrequired | array of object | Negative keywords to add. Omit ad_group_id for a campaign-level negative.Fields: campaign_id*, ad_group_id, keyword_text*, match_type*, state (* required) |
_reasoning | string | Briefly explain why. Stored for audit. |
add_negative_product_targetsAdd Negative Product TargetsAdd Negative Product Targets
POST /public/v1/tools/add_negative_product_targets · requires tools:write
Add up to 50 negative product targets to existing campaigns or ad groups. Each item needs campaign_id and an expression of {type, value} predicates — ASIN_SAME_AS with the ASIN to negate; brand-level negation is not supported. Include ad_group_id for an ad-group-level negative, omit it for campaign level. Atomic: a negation blocked by workspace policy returns 422 and nothing is sent to Amazon.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
negativesrequired | array of object | Negative product targets to add. Omit ad_group_id for campaign-level.Fields: campaign_id*, ad_group_id, expression*, state (* required) |
_reasoning | string | Briefly explain why. Stored for audit. |
list_negative_targetsList Negative TargetsList Negative Targets
POST /public/v1/tools/list_negative_targets · requires tools:read
Negative-targeting inventory: negative keywords and negative product targets at campaign and ad-group scope — match type, state, keyword text or product expression, parent ids, created/updated dates. No metrics. Paginated.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
data_type | enum | Negative keywords, negative product targets, or all (default).One of: keyword, product, all |
scope | enum | Restrict to campaign-level or ad-group-level negatives. Defaults to all.One of: campaign, adGroup, all |
campaign_id | string | Filter to a single campaign by ID. |
ad_group_id | string | Filter to a single ad group by ID. |
state | array of enum | Filter by state. Omit (or pass ['ALL']) to return all states. |
sponsored_type | array of enum | Filter by ad type. |
match_type | array of string | Filter by negative match type, e.g. NEGATIVE_EXACT, NEGATIVE_PHRASE (keywords) or ASIN_SAME_AS (product targets). |
page_size | integer | Number of results per page. Defaults to 100. Max 500. |
page | integer | Page number (0-indexed). Defaults to 0. |
update_negative_keywordUpdate Negative KeywordUpdate Negative Keyword
POST /public/v1/tools/update_negative_keyword · requires tools:write
Set the state of up to 50 negative keywords per call: each item is {negative_id, state} with the negative's id from list_negative_targets and state ENABLED / PAUSED / ARCHIVED. Scope, campaign and ad group are derived from the id. ARCHIVED removes the negative permanently.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
updatesrequired | array of object | Per-negative keyword state changes.Fields: negative_id*, state* (* required) |
_reasoning | string | Briefly explain why. Stored for audit. |
update_negative_product_targetUpdate Negative Product TargetUpdate Negative Product Target
POST /public/v1/tools/update_negative_product_target · requires tools:write
Set the state of up to 50 negative product targets per call: each item is {negative_id, state} with the negative's id from list_negative_targets and state ENABLED / PAUSED / ARCHIVED. Scope, campaign and ad group are derived from the id. ARCHIVED removes the negative permanently.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
updatesrequired | array of object | Per-negative product target state changes.Fields: negative_id*, state* (* required) |
_reasoning | string | Briefly explain why. Stored for audit. |
Catalog, inventory, retail + ads performance, and Amazon reports.
get_advertised_product_performanceGet Advertised Product PerformanceGet Advertised Product Performance
POST /public/v1/tools/get_advertised_product_performance · requires tools:read
Ads-only metrics per advertised ASIN over a date range (only products that received ad impressions). Returns cost (ad spend), attributedSales14d (ad sales), impressions, clicks, and derived ACOS/ROAS/CTR/CPC/CVR. Paginated.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | The Amazon account ID Auto-filled when your API key is restricted to a single Amazon account. |
start_daterequired | string | Start date in YYYY-MM-DD format |
end_daterequired | string | End date in YYYY-MM-DD format |
group_by | array of enum | Dimensions to group results by. Defaults to ['adAsin', 'adProductName']. Use time fields (week, month) for trend analysis. reportType maps to ad type: spAdvertisedDaily=Sponsored Products, sbAdvertisedDaily=Sponsored Brands, sdAdvertisedDaily=Sponsored Display. |
ad_asin | string | Filter to a specific ASIN. |
ad_product_name | string | Filter by product name — case-insensitive PARTIAL match. |
campaign_ids | array of string | Filter to specific campaigns by ID. |
ad_group_ids | array of string | Filter to specific ad groups by ID. |
report_type | array of enum | Filter by ad type. spAdvertisedDaily=Sponsored Products, sbAdvertisedDaily=Sponsored Brands, sdAdvertisedDaily=Sponsored Display. |
sort_field | enum | Field to sort results by. Defaults to 'cost'.One of: cost, attributedSales14d, impressions, clicks, purchases, acos, roas, ctr, cpc, cvr |
sort_direction | enum | Sort direction. Defaults to 'desc'.One of: asc, desc |
page_size | integer | Number of results per page. Defaults to 100. Max 500. |
page | integer | Page number (0-indexed). Defaults to 0. |
tag_values | array of string | Optional legacy tag labels. For campaigns, only ENABLED campaigns with an active tag assignment are included unless status or a named campaign is specified. |
group_by_tag | boolean | When true, results are one row per tag (rollup metrics by tag). Each row includes tagValue. include_tags is ignored when true. |
include_tags | boolean | When true (and group_by_tag is false), each row includes tags loaded from MarketingData after metrics (legacy tag assignments: value, color, bgColor, tagEntityId). |
get_fba_customer_returnsGet FBA Customer ReturnsGet FBA Customer Returns
POST /public/v1/tools/get_fba_customer_returns · requires tools:read
FBA customer returns for a Seller Central account over a date range, per ASIN/SKU, with return reasons and dispositions.
| Parameter | Type | Description |
|---|---|---|
start_daterequired | string | Start date (inclusive) in YYYY-MM-DD format, filtered by returnDate. |
end_daterequired | string | End date (inclusive) in YYYY-MM-DD format, filtered by returnDate. |
page | integer | 0-indexed page of returns to return. Default 0. |
page_size | integer | Returns per page. Default 100, max 500. Check the response's pagination.hasMore/totalPages and increment page to fetch every return. |
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
get_inventoryGet InventoryGet Inventory
POST /public/v1/tools/get_inventory · requires tools:read
Per-ASIN stock: FBM quantity (fbm.quantity) and FBA warehouse balance (fba.endingWarehouseBalance, from the daily FBA Inventory Ledger). A null fbm or fba block means not applicable or no data, not zero (FBA SKUs have fbm: null). Amazon's fulfillable / inbound / reserved / unfulfillable figures are not available. Requires Seller Central. Uses limit/offset.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
asins | array of string | Filter to specific ASINs. |
view | enum | merged (default; use for stock and days-of-cover): one row per ASIN with both FBM and FBA blocks. fbm: merchant-fulfilled rows only, excludes FBA stock (FBA SKUs get fbm: null). fba: FBA-only rows. fba_by_location: FBA-only rows broken out per Amazon fulfillment center (FC) — each ASIN carries a fba.byLocation array with the warehouse balance at each location, plus the rolled-up network total.One of: merged, fbm, fba, fba_by_location |
offset | integer | Pagination offset. Defaults to 0. |
limit | integer | Pagination limit. Defaults to 50. Hard cap at 200. |
get_orders_reportGet Orders ReportGet Orders Report
POST /public/v1/tools/get_orders_report · requires tools:read
Orders for a date range: aggregate totals plus a breakdown by state; raw order rows only when include_orders is set.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
start_daterequired | string | Start date in YYYY-MM-DD format. |
end_daterequired | string | End date in YYYY-MM-DD format. |
marketplace_ids | array of string | Optional marketplace IDs list. |
include_orders | boolean | If true, include the full raw per-order rows, paginated via page/page_size. Defaults to false — only aggregates are returned. Combine with state to drill into one state. |
page | integer | 0-indexed page of orders to return when include_orders=true. Default 0. |
page_size | integer | Orders per page when include_orders=true. Default 100, max 500. Check the response's pagination.hasMore/pagination.totalPages and increment page to fetch every order. |
top_states | integer | Return only the top N state groups (by total value) in the aggregate SUMMARY breakdown; the remainder is summarized as a single 'otherStates' bucket. Does NOT limit the raw orders list (that covers every state, subject to state and pagination). Default 25, max 100. |
state | string | Optional case-insensitive state filter, applied to both the summary breakdown and the raw orders list. Matches state labels containing this value (e.g. 'maharashtra'). |
get_retail_product_performanceGet Retail Product PerformanceGet Retail Product Performance
POST /public/v1/tools/get_retail_product_performance · requires tools:read
Combined retail + ads metrics per ASIN — total revenue, sessions, page views, buy-box %, TACoS, organic vs ads split. Requires a Seller Central (SP-API) connection; supports child/parent ASIN rollup.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | The Amazon account ID (from get_user_context) Auto-filled when your API key is restricted to a single Amazon account. |
start_daterequired | string | Start date in YYYY-MM-DD format |
end_daterequired | string | End date in YYYY-MM-DD format |
listing_type | enum | Product listing level. 'child_asin' (default) shows individual product variations. 'parent_asin' shows parent-level rollup across all variations.One of: child_asin, parent_asin |
asin | string | Filter to a specific ASIN. |
item_name | string | Filter by product name. |
sort_field | enum | Field to sort results by. Defaults to 'totalSales'.One of: totalSales, pageViews, sessions, unitsOrdered, buyBoxPercentage, cost, attributedSales14d, impressions, clicks, purchases, acos, roas, tacos |
sort_direction | enum | Sort direction. Defaults to 'desc'.One of: asc, desc |
page_size | integer | Number of results per page. Defaults to 100. Max 500. |
page | integer | Page number (0-indexed). Defaults to 0. |
get_scp_reportGet SCP ReportGet SCP Report
POST /public/v1/tools/get_scp_report · requires tools:read
Amazon Brand Analytics Search Catalog Performance — one row per ASIN per month (no search-query dimension), with nested impression / click / cart-add / purchase metrics (counts, rates, median prices, shipping-speed breakdowns, search-traffic sales) plus product title and image. Takes integer month + year; asin narrows to one product. Sorted by impressionCount by default (sort_field / sort_direction). Paginated (page_size 50, max 200).
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | Amazon account ID (from get_user_context) Auto-filled when your API key is restricted to a single Amazon account. |
monthrequired | integer | Calendar month (1-12) |
yearrequired | integer | Four-digit year |
asin | string | Optional ASIN filter (exact match). |
page | integer | Page number (0-indexed). Defaults to 0. |
page_size | integer | Rows per page. Defaults to 50, max 200. Keep small — responses over ~1 MB can be rejected by the MCP client. |
sort_field | string | Field to sort by. Defaults to 'impressionCount'. Common alternatives: 'clickCount', 'cartAddCount', 'purchaseCount', 'clickRate', 'conversionRate', 'asin'. |
sort_direction | enum | Sort direction. Defaults to 'desc'.One of: asc, desc |
get_sqp_reportGet SQP ReportGet SQP Report
POST /public/v1/tools/get_sqp_report · requires tools:read
Amazon Search Query Performance — one row per (ASIN, query). Uses integer month + year, not a date range. Paginated.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | Amazon account ID (from get_user_context) Auto-filled when your API key is restricted to a single Amazon account. |
monthrequired | integer | Calendar month (1-12) |
yearrequired | integer | Four-digit year |
asin | string | Optional ASIN filter (exact match). |
search_query | string | Optional search query filter (exact match). |
page | integer | Page number (0-indexed). Defaults to 0. |
page_size | integer | Rows per page. Defaults to 50, max 200. Keep small — responses over ~1 MB can be rejected by the MCP client. |
sort_field | string | Field to sort by. Defaults to 'searchQueryData.searchQueryScore'. Common alternatives: 'searchQueryData.searchQueryVolume', 'asin'. |
sort_direction | enum | Sort direction. Defaults to 'desc'.One of: asc, desc |
list_product_catalogList Product CatalogList Product Catalog
POST /public/v1/tools/list_product_catalog · requires tools:read
Seller product catalog (ASIN + SKU, name, image, price, fulfillment channel, status, FBM quantity). Optionally pass a date range to add retail and ad metrics per product. Requires Seller Central. Uses limit/offset.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
asins | array of string | Filter to specific ASINs. |
skus | array of string | Filter to specific SKUs. |
name_search | string | Case-insensitive substring match against the item name. |
fulfillment_channel | enum | Filter by fulfillment. FBA = Amazon-fulfilled (channel starts with AMAZON_), FBM = merchant-fulfilled (channel = DEFAULT). Defaults to ALL.One of: FBA, FBM, ALL |
include_suppressed | boolean | When false (default), products whose status list includes 'SUPPRESSED' or 'INACTIVE' are filtered out. |
start_date | string | Start date in YYYY-MM-DD format. Presence of this field switches the tool to Mode 2 (catalog + performance). end_date is required when start_date is set. |
end_date | string | End date in YYYY-MM-DD format. Required iff start_date is set; must be on or after start_date. |
include_retail_metrics | boolean | Mode 2 only. Default true. When true, each row carries a retail block with sessions, pageViews, unitsOrdered, totalRevenue, conversionRate, buyBoxPercentage. |
include_ads_metrics | boolean | Mode 2 only. Default false. When true, each row carries an ads block with spend, attributedSales14d, ACOS, ROAS, orders, impressions, clicks. |
unadvertised_only | boolean | Mode 2 only. When true, only products with zero ad spend in the date range are returned — i.e. candidates for create_campaign. Forces include_ads_metrics=true. |
min_total_revenue | number | Mode 2 only. Filter to products whose retail revenue in the date range is >= this value. |
max_acos | number | Mode 2 only. Filter to products whose advertising ACOS in the date range is <= this value (percent, e.g. 30 for 30%). Skips products with no ad spend. |
sort_by | object | Sort key. Mode 1 defaults to itemName asc. Mode 2 defaults to totalRevenue desc.Fields: field*, direction (* required) |
offset | integer | Pagination offset. Defaults to 0. |
limit | integer | Pagination limit. Defaults to 50. Hard cap at 200. |
update_product_adUpdate Product AdUpdate Product Ad
POST /public/v1/tools/update_product_ad · requires tools:write
Set the state of up to 50 product ads per call: each item needs campaign_id, ad_group_id, the asin (or ad_id) and state ENABLED / PAUSED / ARCHIVED. ARCHIVED removes the product ad and is permanent — PAUSED stops advertising a product reversibly.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
updatesrequired | array of object | Per-product-ad state changes.Fields: campaign_id*, ad_group_id*, asin, ad_id, state* (* required) |
_reasoning | string | Briefly explain why. Stored for audit. |
Amazon DSP (programmatic display/video) campaigns and reports.
get_dsp_performanceGet DSP PerformanceGet DSP Performance
POST /public/v1/tools/get_dsp_performance · requires tools:read
Amazon DSP performance over a date range — five reports behind one report enum (campaign / product / inventory / geo / audience), with group_by and metrics chosen per report. Separate from Sponsored Products data; do not combine the two. Paginated.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | Amazon account ID (from get_user_context) Auto-filled when your API key is restricted to a single Amazon account. |
reportrequired | enum | Which DSP report to run. 'campaign' for spend/sales/ROAS by campaign, 'product' for per-ASIN conversions, 'inventory' for placement/creative, 'geo' for geography, 'audience' for segments.One of: audience, campaign, geo, inventory, product |
start_daterequired | string | Start date, YYYY-MM-DD (inclusive). |
end_daterequired | string | End date, YYYY-MM-DD (inclusive). |
group_by | array of enum | Dimensions to break results out by. Valid values depend on report — this enum is the union across all five. Every report also accepts the time buckets 'timeWindowStart' (daily), 'week', 'month' and 'year'. Omit for the per-report default. Each extra dimension multiplies the row count, so add them one at a time. |
metrics | array of enum | Metric columns to return. Valid values depend on report — this enum is the union across all five. Omit for a sensible default set. |
order_ids | array of string | Optional DSP order (campaign) IDs to restrict to. Resolve names to IDs with list_dsp_campaigns. |
asins | array of string | Optional ASIN filter. Only applies to report='product' — the other collections carry no ASIN field. |
page | integer | Page number (0-indexed). Defaults to 0. |
page_size | integer | Rows per page. Defaults to 50, max 200. Keep it small — responses over ~1 MB can be rejected by the MCP client. |
sort_field | string | Metric or dimension to sort by (must be valid for this report). Defaults to totalCost, or sales for report='product' (that collection has no cost field). |
sort_direction | enum | Sort direction. Defaults to 'desc'.One of: asc, desc |
list_dsp_campaignsList DSP CampaignsList DSP Campaigns
POST /public/v1/tools/list_dsp_campaigns · requires tools:read
DSP campaigns (orders) for an account: order_id, name, state, delivery status and flight dates. Metadata only — resolve a campaign name to the order_id that get_dsp_performance filters on.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | Amazon account ID (from get_user_context) Auto-filled when your API key is restricted to a single Amazon account. |
name_search | string | Filter by campaign name (case-insensitive partial match). |
state | array of string | Filter by campaign state as stored by Amazon (e.g. ACTIVE, PAUSED, ARCHIVED). Omit to return every state. |
delivery_status | array of string | Filter by Amazon delivery status (e.g. DELIVERING, NOT_DELIVERING). Omit to return every status. |
order_ids | array of string | Optional exact DSP order (campaign) IDs to look up. |
page | integer | Page number (0-indexed). Defaults to 0. |
page_size | integer | Campaigns per page. Defaults to 50, max 200. |
AMC instances, audiences (templates, size estimates, creation), and AMC reports.
create_amc_audienceCreate AMC AudienceCreate AMC Audience
POST /public/v1/tools/create_amc_audience · requires tools:write
Create a rule-based (default) or lookalike AMC audience on the account's instance. Source: a template_id with its inputs, a query_payload, or raw query SQL. activation is SPONSORED_ADS (default) or DSP (fails if the instance has no DSP advertiser). days sets the lookback (default: the template's, or 90); refresh_rate_days 0–21 (7–21 for a lookalike; default 21); a lookalike also needs lookalike_expected_reach. Run estimate_amc_audience_size first when in doubt, or pass dry_run: true to get the resolved plan and SQL without creating anything. Amazon builds the audience asynchronously — follow up with list_amc_audiences.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
namerequired | string | Audience name (1–100 characters). |
description | string | Optional description (defaults to the template's). |
instance_id | string | AMC instanceId (from get_amc_report_options). Defaults to the account's default instance. |
template_id | string | A recipe from get_amc_audience_templates. Give its inputs below when it needs them. |
search_terms | string | array of string | For a search-term recipe: the customer search terms (list or comma-separated). |
asins | string | array of string | For an ASIN-scoped recipe: the ASINs of the first row (list or comma-separated). |
asins_b | string | array of string | Cross-sell only: the ASINs of the second (excluded) row. |
value | number | For a recipe with an open threshold (high-value buyers): the order value. |
query_payload | object | Instead of a template: a rule-builder payload {conditions:[...], connectors:[...]} as the AMC audience agent produces. |
query | string | Instead of a template or payload: raw AMC audience SQL on the *_for_audiences tables. |
days | integer | Lookback window in days ending today (default: the template's, or 90). |
audience_type | enum | Which minimum to grade against (default RULE_BASED: 2,000 users; LOOKALIKE seed: 500 to 500,000).One of: RULE_BASED, LOOKALIKE |
time_window_start | string | Optional explicit window start (ISO 8601 UTC) instead of days. |
time_window_end | string | Optional explicit window end (ISO 8601 UTC) instead of days. |
time_window_relative | boolean | Slide the window forward on each refresh (default true). |
refresh_rate_days | integer | How often Amazon rebuilds it: 0–21 days (7–21 for a lookalike). Default 21. |
lookalike_expected_reach | enum | Lookalike only: how far from the seed to reach.One of: MOST_SIMILAR, SIMILAR, BALANCED, BROAD, MOST_BROAD |
activation | enum | Where the audience is activated (default SPONSORED_ADS).One of: SPONSORED_ADS, DSP |
dry_run | boolean | true = return the resolved plan and SQL without creating anything. |
estimate_amc_audience_sizeEstimate AMC Audience SizeEstimate AMC Audience Size
POST /public/v1/tools/estimate_amc_audience_size · requires tools:read
Count how many shoppers an audience definition would contain before creating it. Amazon rejects a rule-based audience under 2,000 users (2,500 recommended) and a lookalike seed outside 500–500,000, and only says so after building it. Give a template_id (plus its inputs), a query_payload, or raw query SQL, with optional days and audience_type. Returns an estimateId immediately; AMC takes one to five minutes, so poll get_amc_audience_size_estimate. Nothing is created.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
instance_id | string | AMC instanceId (from get_amc_report_options). Defaults to the account's default instance. |
template_id | string | A recipe from get_amc_audience_templates. Give its inputs below when it needs them. |
search_terms | string | array of string | For a search-term recipe: the customer search terms (list or comma-separated). |
asins | string | array of string | For an ASIN-scoped recipe: the ASINs of the first row (list or comma-separated). |
asins_b | string | array of string | Cross-sell only: the ASINs of the second (excluded) row. |
value | number | For a recipe with an open threshold (high-value buyers): the order value. |
query_payload | object | Instead of a template: a rule-builder payload {conditions:[...], connectors:[...]} as the AMC audience agent produces. |
query | string | Instead of a template or payload: raw AMC audience SQL on the *_for_audiences tables. |
days | integer | Lookback window in days ending today (default: the template's, or 90). |
audience_type | enum | Which minimum to grade against (default RULE_BASED: 2,000 users; LOOKALIKE seed: 500 to 500,000).One of: RULE_BASED, LOOKALIKE |
get_amc_audience_size_estimateGet AMC Audience Size EstimateGet AMC Audience Size Estimate
POST /public/v1/tools/get_amc_audience_size_estimate · requires tools:read
Poll an estimate by estimate_id. Returns status (PENDING / RUNNING / SUCCEEDED / FAILED), audienceSize, suppressed (true when AMC withheld the number because the audience is under roughly 100 shoppers — not zero), a verdict (ok / borderline / too_small / too_large) with the thresholds it was graded against, and sizeText. Poll about once a minute until the status is terminal.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
estimate_idrequired | string | The estimateId returned by estimate_amc_audience_size. |
instance_id | string | The instanceId the estimate was started on (defaults to the account's default instance). |
get_amc_audience_templatesGet AMC Audience TemplatesGet AMC Audience Templates
POST /public/v1/tools/get_amc_audience_templates · requires tools:read
SellerMate's library of ready-made AMC audience recipes (cart abandoners, repeat viewers, high-value / new-to-brand / lapsed buyers, cross-sell, ad-fatigued non-clickers, …). Each entry gives a templateId, what it selects, its default lookback window, the inputs it still needs (search_terms, asins, value), whether it suits a lookalike seed, and where it can be activated. Filter with group or fetch one by template_id; include_payload adds each recipe's rule payload. Needs no account id.
| Parameter | Type | Description |
|---|---|---|
template_id | string | One recipe by id (returns its rule payload too). |
group | enum | Only this group.One of: Retarget, Loyalty & growth, Exclusion |
include_payload | boolean | Include each recipe's rule payload (default false). |
get_amc_custom_attributionGet AMC Custom AttributionGet AMC Custom Attribution
POST /public/v1/tools/get_amc_custom_attribution · requires tools:read
AMC Custom Attribution report: per-campaign conversions under a chosen attribution model, selected with granularity (LAST_TOUCH default, FIRST_TOUCH, LINEAR, POSITION). Metrics include impressions, clicks, user_reach, users_that_converted, conversions, conversion_rate, total_units_sold and total_product_sales, plus a pinned Total row. month is YYYY-MM from get_amc_report_options (default: latest available). Sortable, filterable via filter_model; page is 1-based (page_size 100, max 500).
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
instance_id | string | AMC instanceId (from get_amc_report_options). Defaults to the account's default instance. |
month | string | Report month as YYYY-MM (from get_amc_report_options). Defaults to the latest available month. |
granularity | enum | Attribution MODEL (this report's granularity slot). LAST_TOUCH is the default.One of: LAST_TOUCH, FIRST_TOUCH, LINEAR, POSITION |
sort_by | string | Field to sort by. Defaults to the report's default sort. |
sort_order | enum | Sort direction. Defaults to 'desc'.One of: asc, desc |
page | integer | 1-based page number. Defaults to 1 — increment to page through all rows (see the response's pagination block). |
page_size | integer | Rows per page. Defaults to 100, max 500. Keep small for MCP transport limits. |
filter_model | object | Optional MUI-DataGrid filter model {items:[{field,operator,value}], logicOperator:'and'|'or'}. Only the report's whitelisted columns are applied. |
get_amc_path_to_conversionGet AMC Path to ConversionGet AMC Path to Conversion
POST /public/v1/tools/get_amc_path_to_conversion · requires tools:read
AMC Path to Conversion report: the ad-exposure paths shoppers took before purchasing, one row per path, grouped by granularity (AD_TYPE default or CAMPAIGN). Metrics include path_occurrences, impressions, imp_total_cost, users_that_purchased, sales_amount, purchases, user_purchase_rate and new-to-brand (ntb_*) columns, plus a pinned Total row. month is YYYY-MM (default: latest available). page is 1-based (page_size 100, max 500).
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
instance_id | string | AMC instanceId (from get_amc_report_options). Defaults to the account's default instance. |
month | string | Report month as YYYY-MM (from get_amc_report_options). Defaults to the latest available month. |
granularity | enum | Path grouping. AD_TYPE (default) groups paths by ad type; CAMPAIGN groups by campaign.One of: AD_TYPE, CAMPAIGN |
sort_by | string | Field to sort by. Defaults to the report's default sort. |
sort_order | enum | Sort direction. Defaults to 'desc'.One of: asc, desc |
page | integer | 1-based page number. Defaults to 1 — increment to page through all rows (see the response's pagination block). |
page_size | integer | Rows per page. Defaults to 100, max 500. Keep small for MCP transport limits. |
filter_model | object | Optional MUI-DataGrid filter model {items:[{field,operator,value}], logicOperator:'and'|'or'}. Only the report's whitelisted columns are applied. |
get_amc_report_optionsGet AMC Report OptionsGet AMC Report Options
POST /public/v1/tools/get_amc_report_options · requires tools:read
The account's AMC setup — call this before any other AMC tool. Returns the linked AMC instances (instanceId, instanceName, which one is the default), the available months (YYYY-MM, newest first) for each monthly report (path to conversion, time to conversion, custom attribution), and the tentpole events (eventId, name, status) the overlap report needs. An empty instances list means no AMC instance is linked.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
instance_id | string | Optional AMC instanceId to scope the available months/events to. Defaults to the account's default instance. |
get_amc_tentpole_overlapGet AMC Tentpole OverlapGet AMC Tentpole Overlap
POST /public/v1/tools/get_amc_tentpole_overlap · requires tools:read
AMC Tentpole Phase Overlap results for one tentpole event: strategy-path performance across the event's phases, one row per path. Requires event_id from get_amc_report_options. Metrics include impressions, unique_viewers, unique_purchasers, dpv, sales, ntb_sales, ad_spend, roas and rate columns; default sort is sales. page is 1-based (page_size 100, max 500).
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
event_idrequired | string | Tentpole event id (from get_amc_report_options → tentpole_events). |
instance_id | string | AMC instanceId (from get_amc_report_options). Defaults to the account's default instance. |
sort_by | string | Field to sort by. Defaults to 'sales'. Common: sales, roas, ad_spend, impressions, unique_purchasers. |
sort_order | enum | Sort direction. Defaults to 'desc'.One of: asc, desc |
page | integer | 1-based page number. Defaults to 1 — increment to page through all rows. |
page_size | integer | Rows per page. Defaults to 100, max 500. Keep small for MCP transport limits. |
get_amc_time_to_conversionGet AMC Time to ConversionGet AMC Time to Conversion
POST /public/v1/tools/get_amc_time_to_conversion · requires tools:read
AMC Time to Conversion report: how long after ad exposure shoppers converted, as a latency distribution with one row per group × time bucket, grouped by granularity (AD_TYPE default or CAMPAIGN). Metrics include purchases, total_brand_purchases, avg_time_to_conversion_hours and avg_time_to_conversion_per_group, plus a pinned Total row. month is YYYY-MM (default: latest available). page is 1-based (page_size 100, max 500).
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
instance_id | string | AMC instanceId (from get_amc_report_options). Defaults to the account's default instance. |
month | string | Report month as YYYY-MM (from get_amc_report_options). Defaults to the latest available month. |
granularity | enum | Grouping of the latency distribution. AD_TYPE (default) groups by ad type; CAMPAIGN groups by campaign.One of: AD_TYPE, CAMPAIGN |
sort_by | string | Field to sort by. Defaults to the report's default sort. |
sort_order | enum | Sort direction. Defaults to 'desc'.One of: asc, desc |
page | integer | 1-based page number. Defaults to 1 — increment to page through all rows (see the response's pagination block). |
page_size | integer | Rows per page. Defaults to 100, max 500. Keep small for MCP transport limits. |
filter_model | object | Optional MUI-DataGrid filter model {items:[{field,operator,value}], logicOperator:'and'|'or'}. Only the report's whitelisted columns are applied. |
list_amc_audiencesList AMC AudiencesList AMC Audiences
POST /public/v1/tools/list_amc_audiences · requires tools:read
The audiences built on one AMC instance (rule-based and lookalike): name, description, type, status (SUCCEEDED = usable; FAILED with Amazon's statusReason, usually the 2,000-user minimum; PENDING / RUNNING = still building), audienceCount, activation (Sponsored Ads or DSP), the Amazon audience id used for targeting, time window, refresh rate and SQL. Filters (AND-ed): status, audience_type, name_query, audience_ids. instance_id defaults to the account's default instance. Paginated — page is 1-based here (page_size 50, max 200).
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
instance_id | string | AMC instanceId (from get_amc_report_options). Defaults to the account's default instance. |
status | string | array of string | Only these statuses: SUCCEEDED, FAILED, PENDING, RUNNING. A list or a comma-separated string. |
audience_type | string | array of string | Only this type: RULE_BASED or LOOKALIKE. A list or a comma-separated string. |
name_query | string | Case-insensitive substring to match against the audience name or description. |
audience_ids | string | array of string | Exact audienceId or audienceExecutionId values, from a mention or an earlier result. |
page | integer | 1-based page (default 1). |
page_size | integer | Rows per page (default 50, max 200). |
Vendor Central sales, inventory, and catalog (vendor accounts).
get_vendor_inventoryGet Vendor InventoryGet Vendor Inventory
POST /public/v1/tools/get_vendor_inventory · requires tools:read
Vendor Central on-hand inventory per ASIN: sellable (available) and unsellable units, with product name/image. Choose the sourcing (default) or manufacturing view. Returns {connected: false} with a connect URL if the account has no Vendor Central connection. Paginated.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
inventory_type | enum | Vendor inventory view. Defaults to 'sourcing'.One of: sourcing, manufacturing |
asins | array of string | Optional: filter to specific ASINs. |
page_size | integer | Number of results per page. Defaults to 100. Max 500. |
page | integer | Page number (0-indexed). Defaults to 0. |
get_vendor_sales_performanceGet Vendor Sales PerformanceGet Vendor Sales Performance
POST /public/v1/tools/get_vendor_sales_performance · requires tools:read
Vendor Central sales per ASIN over a date range: ordered units + ordered revenue (manufacturing view), shipped units + shipped revenue + shipped COGS + customer returns (sourcing view), and glance views. Note: vendor traffic is glance views only — sessions, page views, and conversion are not available for vendor accounts. Paginated; summary covers the full set.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
start_daterequired | string | Start date in YYYY-MM-DD format. |
end_daterequired | string | End date in YYYY-MM-DD format. |
asins | array of string | Optional: filter to specific ASINs. |
page_size | integer | Number of results per page. Defaults to 100. Max 500. |
page | integer | Page number (0-indexed). Defaults to 0. |
list_vendor_productsList Vendor ProductsList Vendor Products
POST /public/v1/tools/list_vendor_products · requires tools:read
Vendor Central product catalog (ASIN, item name, image) — use it to discover ASINs for the other vendor tools. Paginated.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
asins | array of string | Optional: filter to specific ASINs. |
page_size | integer | Number of results per page. Defaults to 100. Max 500. |
page | integer | Page number (0-indexed). Defaults to 0. |
Real profit from Seller Central finance data: the P&L statement, profit per product, and unit costs (paid plans; switched on per account).
get_pnl_by_productGet P&L by ProductGet P&L by Product
POST /public/v1/tools/get_pnl_by_product · requires tools:read
Profit per SKU, or per product family with group_by: "family" (parent ASIN, every child summed): units, revenue, fees and feePct, cost of goods and cogsBasis (actual / estimated / missing / partial), ad spend, ad sales, gross and net profit, margin. One currency per call (currency; default the one with most revenue). sort_by / sort, filters sku / asin / parent_asin / cogs_basis (comma-separated), include_no_sales; paginated (page, page_size ≤ 500). summary covers the whole filtered set.
| Parameter | Type | Description |
|---|---|---|
start_date | string | Start date (inclusive), YYYY-MM-DD. Default: 30 full days ago. |
end_date | string | End date (inclusive), YYYY-MM-DD. Default: yesterday. |
currency | string | Which currency's rows to return (e.g. USD). Default: the currency with most revenue. |
group_by | enum | 'sku' (default) one row per SKU; 'family' one row per parent ASIN with every child summed.One of: sku, family |
sort_by | enum | Default 'revenue'. Cost fields sort by magnitude.One of: revenue, net_profit, gross_profit, margin_pct, fee_pct, fees, ad_spend, ad_sales, ad_share_of_revenue, cogs, units, units_returned |
sort | enum | Default 'desc'. Rows with no value for sort_by come last.One of: asc, desc |
sku | string | Only these SKUs (comma-separated for several). |
asin | string | Only these child ASINs (comma-separated for several). |
parent_asin | string | Only products in these families (comma-separated for several). |
cogs_basis | string | Only rows whose cost basis is among: actual, estimated, missing, partial, none (comma-separated). |
include_no_sales | boolean | Include ASINs that spent on ads but sold nothing. Default true. |
page | integer | 0-indexed page. Default 0. |
page_size | integer | Rows per page. Default 100, max 500. |
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
get_pnl_statusGet P&L StatusGet P&L Status
POST /public/v1/tools/get_pnl_status · requires tools:read
Whether Profit & Loss is available for the account (state: ready / syncing / not_enabled / not_connected / awaiting_access / reconnect_required / not_paid) and how far its data reaches: data.salesFrom, data.salesThrough, data.settlementThrough. The P&L feeds are not covered by check_data_coverage; a day after salesThrough is unknown, not zero. Settlement fees lag by up to two weeks.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
get_pnl_summaryGet P&L StatementGet P&L Statement
POST /public/v1/tools/get_pnl_summary · requires tools:read
The P&L statement for a date range, per currency: product sales, refunds, promotions, Amazon selling fees by type and as a % of sales (fee_breakdown, fee_pct), inbound / removal / subscription / Easy Ship / storage fees, reimbursements, ad spend, cost of goods (real and estimated), gross and net profit, margin, units, orders. granularity: "daily" adds a per-day series. Default window: the last 30 full days; max 400. Never add two currencies together. Paid plans only.
| Parameter | Type | Description |
|---|---|---|
start_date | string | Start date (inclusive), YYYY-MM-DD. Default: 30 full days ago. |
end_date | string | End date (inclusive), YYYY-MM-DD. Default: yesterday. |
currency | string | Return only this currency (e.g. USD). Default: every currency the account settles in. |
granularity | enum | 'daily' adds a day-by-day series. Default 'total'.One of: total, daily |
fields | enum | With granularity='daily': 'charted' (default) carries the main lines only; 'all' every line per day.One of: charted, all |
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
get_product_costsGet Product Costs (COGS)Get Product Costs (COGS)
POST /public/v1/tools/get_product_costs · requires tools:read
The cost-of-goods catalogue: per (SKU, currency) the saved unitCost, units, revenue and average sale price since sales history starts, plus the smart-COGS settings and counts of products with and without a cost. only_missing: true lists products that still need a cost; include_unsold: true adds listed products that have not sold. Paginated.
| Parameter | Type | Description |
|---|---|---|
only_missing | boolean | Only products with no unit cost on file. Default false. |
include_unsold | boolean | Also list products that have not sold since sales history starts. Default false. |
currency | string | Only rows in this currency. |
sku | string | Only these SKUs (comma-separated for several). |
asin | string | Only these ASINs (comma-separated for several). |
page | integer | 0-indexed page. Default 0. |
page_size | integer | Rows per page. Default 100, max 500. |
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
set_product_costsSave Product Costs (COGS)Save Product Costs (COGS)
POST /public/v1/tools/set_product_costs · requires tools:write
Save unit costs per (SKU, currency) — costs: [{sku, unit_cost, currency?}], unit_cost: null clears — and optionally default_cogs_percent (0–95) or disable_cogs_estimate: true (workspace Owner/Admin). confirm: false (default) previews every change, the unchanged and rejected ones, and flags costs above the sale price without saving; confirm: true saves the same list. Up to 2,000 per call. Needs a key with write scope; uses no credits.
| Parameter | Type | Description |
|---|---|---|
costs | array of object | Costs to save. Each: sku (required), unit_cost (number, or null to clear), currency (optional, e.g. USD).Fields: sku*, unit_cost, currency (* required) |
confirm | boolean | false (default): preview only, nothing saved. true: save. Call with true only after the user confirmed the previewed changes. |
default_cogs_percent | number | Smart-COGS estimate for products with no cost: % of revenue, 0–95. Owner/Admin only. |
disable_cogs_estimate | boolean | true switches the smart-COGS estimate off. Owner/Admin only. |
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
Knowledge-base / memory files uploaded to SellerMate.
archive_memory_fileArchive Memory FileArchive Memory File
POST /public/v1/tools/archive_memory_file · requires tools:write
Archive (delete) a memory file by fileId: hidden from every list and tool; nothing is removed from storage. Needs a key with write scope.
| Parameter | Type | Description |
|---|---|---|
fileIdrequired | string | The fileId from list_knowledge_and_memory_files. |
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
create_memory_fileCreate Memory FileCreate Memory File
POST /public/v1/tools/create_memory_file · requires tools:write
Save a new memory file (md, txt or docx from Markdown) with a title, content and optional description. Up to 100,000 characters; 50 files per account; a title already in use is refused. Needs a key with write scope.
| Parameter | Type | Description |
|---|---|---|
titlerequired | string | Clear, specific human-readable title, e.g. 'Belt campaign bidding rules'. Max 200 characters. |
file_typerequired | enum | 'md' (Markdown), 'txt' (plain text) or 'docx' (Word, from Markdown content).One of: docx, md, txt |
contentrequired | string | The full text of the file. Markdown for 'md' and 'docx'. |
description | string | One line on what the file contains and when it is useful (max 500 characters). |
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
find_in_knowledge_and_memory_filesFind in Knowledge & Memory FilesFind in Knowledge & Memory Files
POST /public/v1/tools/find_in_knowledge_and_memory_files · requires tools:read
Search up to 5 documents (fileIds) for 1–10 words or phrases (find): per file a match count, per-term counts and the top 10 matching lines with the text around them, numbered by line.
| Parameter | Type | Description |
|---|---|---|
fileIdsrequired | array of string | 1–5 fileIds from list_knowledge_and_memory_files. |
findrequired | array of string | 1–10 words, phrases or short sentences to look for (2–200 characters each). |
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
get_knowledge_and_memory_file_contentGet Knowledge & Memory File ContentGet Knowledge & Memory File Content
POST /public/v1/tools/get_knowledge_and_memory_file_content · requires tools:read
Read one uploaded file's content by fileId (from list_knowledge_and_memory_files). Documents: the whole text, or pass start_line / end_line (at most 800 lines) for part of it. Tabular files return CSV text with a totalRows count and a truncated flag past the size cap.
| Parameter | Type | Description |
|---|---|---|
fileIdrequired | string | The fileId from list_knowledge_and_memory_files. |
version | integer | Optional: an older version to read. Omit for the current version. |
line_numbers | boolean | Optional: prefix each line with 'N| ' (documents only). |
start_line | integer | Optional: first line to read (1-based); negative = the last N lines. Documents only. |
end_line | integer | Optional: last line to read (inclusive); at most 800 lines per call. |
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
get_knowledge_and_memory_file_detailsGet Knowledge & Memory File DetailsGet Knowledge & Memory File Details
POST /public/v1/tools/get_knowledge_and_memory_file_details · requires tools:read
One file's details by fileId: the list fields plus currentVersion and lastEditedAt; include_history=true adds its kept versions.
| Parameter | Type | Description |
|---|---|---|
fileIdrequired | string | The fileId from list_knowledge_and_memory_files. |
include_history | boolean | Optional: also return the file's kept versions, newest first. |
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
list_knowledge_and_memory_filesList Knowledge & Memory FilesList Knowledge & Memory Files
POST /public/v1/tools/list_knowledge_and_memory_files · requires tools:read
List the knowledge-base / memory files uploaded to SellerMate for this account: fileId, title, file kind (document / tabular), size, description, context snippet, token count.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
query | string | Optional: what to find in the user's files, in plain words. Leave empty for the full list. |
fileId | string | Optional, with query: search inside this one file only. |
update_memory_fileUpdate Memory FileUpdate Memory File
POST /public/v1/tools/update_memory_file · requires tools:write
Change a memory file by fileId: content (mode edit / append / replace — Markdown and text files), title, description, or mode: "revert" with a version. Each change is a new version (last 15 kept). Needs a key with write scope.
| Parameter | Type | Description |
|---|---|---|
fileIdrequired | string | The fileId from list_knowledge_and_memory_files. |
mode | enum | How to change the content, or 'revert' to restore version. Omit when only the title / description change.One of: edit, append, replace, revert |
edits | array of object | mode 'edit': all find/replace pairs OR all line ranges (not mixed).Fields: find, replace_all, start_line, end_line, replace* (* required) |
content | string | mode 'append': text to add at the end. mode 'replace': the whole new file. |
title | string | New title — only when the user asks to rename. Leave empty otherwise. |
description | string | New description — only when the user asks to change it. Leave empty otherwise. |
change_summaryrequired | string | One line on what changed (max 200 characters). |
version | integer | mode 'revert' only: the kept version to restore. |
base_version | integer | The version you read. Required for mode 'replace'; optional otherwise. |
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
Automations, dayparting schedules, and hourly performance.
create_automationCreate AutomationCreate Automation
POST /public/v1/tools/create_automation · requires tools:write
Create an automation rule. Required: automate_for (the category, which fixes the valid condition fields, actions and scope), a name unique among the account's live automations, conditions (the if / else-if / else rule tree), rule_schedule ({type: "weekly" | "monthly", days: [...]}; Campaign rules also need timeSlots) and a scope — selected_campaigns (or selected_campaign_tags), or selected_mapping for Mapped Harvesting. Everything is validated against the rule editor's whitelists. For safety status defaults to INACTIVE, so a new rule does nothing until it is activated (here or via update_automation); each action's isAutoExecute defaults to true for Inventory and Campaign and false elsewhere, where the rule only reports what it would do. Campaign rules take selected_campaigns as {campaignId, baseBudget} objects. Omitted lookback, processing-time and notification fields get the editor's defaults, and the response lists which were defaulted.
| Parameter | Type | Description |
|---|---|---|
automate_forrequired | string | The automation category, one of: Keyword Targets, All Targets, Search Terms, Mapped Harvesting, Placements, Ad Products, Campaign, Inventory. Selects which condition fields, actions and scope fields are valid — see update_automation's per-category reference. |
namerequired | string | Automation name. Must not match an existing live automation in the account. |
description | string | |
status | enum | Defaults to 'INACTIVE' — the rule is created but does not run. Pass 'ACTIVE' to start it immediately; that requires a scope to be set.One of: ACTIVE, INACTIVE |
conditionsrequired | array of object | The if/else_if/else rule blocks: {id, type, condition, action}. Required. Each action takes isAutoExecute; omitted, it defaults to true for Inventory and Campaign and false elsewhere, matching the app. Nested condition groups require advancedMode true. See update_automation's description for the full structure and the valid fields/actions per category. |
rule_schedulerequired | object | When the rule runs. Required.Fields: type, days, timeSlots |
rule_processing_time | string | The single time of day the rule runs (7:00 AM-9:00 PM). Not used by Campaign, which uses rule_schedule.timeSlots. |
selected_campaigns | array of string | object | Campaign id strings; objects {campaignId, adGroupsIds} when campaign_adgroup_selection is true; objects {campaignId, baseBudget} for Campaign automations, which require objects. |
selected_campaign_tags | array of object | Campaign tags scoping the rule; use with campaign_tag_selection. |
campaign_adgroup_selection | boolean | |
campaign_tag_selection | boolean | |
selected_asins | array of string | Inventory only — the ASINs the stock rule watches. |
selected_mapping | object | Mapped Harvesting only, and required for it — ONE existing harvesting mapping (a single object, never a list; from list_harvesting_mappings). For several mappings, create one automation per mapping.Fields: mapping_id, mapping_name |
todays_live_data | boolean | Campaign only — evaluate against today's live performance instead of the closed lookback window. |
lookback_period | object | Defaults to {value: 7, unit: 'days'}. Not used by Inventory.Fields: value, unit |
lookback_skip_days | number | string | Days to skip from today; must be >= 0. Defaults to 3. |
exclude_list | object | array | Entities the rule must leave alone. Shape depends on the category: {phrase, exact} for Keyword Targets/Search Terms/Mapped Harvesting; {phrase, exact, asins} for All Targets; {asins: [...]} for Ad Products; a flat array of warehouse code strings for Inventory. Placements and Campaign have none. Defaults to the category's empty shape. |
email_notification | boolean | |
email_addresses | array of string | |
advancedMode | boolean | |
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
create_daypartingCreate DaypartingCreate Dayparting
POST /public/v1/tools/create_dayparting · requires tools:write
Create a dayparting schedule of one type, passing the whole definition in dayparting. bid and placement: name, state, slotInterval (1, 4 or 6), bidAllocation (allocationType + timeSlots) and selectedCampaigns — per campaign with optional targets for bid, or one {campaignId, placementType, basePlacementPercentage} entry per campaign-placement pair for placement (Sponsored Products only). budget and portfolio: name, a non-empty rules list ({days, hour, minute, action, budget}) and selectedCampaigns ({campaignId, baseBudget}) or selectedPortfolios ({portfolioId, baseBudget}); these are rule-driven and take no time slots. baseBidStrategy says how covered targets without a base bid of their own get one. Base bids themselves are set with update_target.
| Parameter | Type | Description |
|---|---|---|
typerequired | enum | Which kind of dayparting to create (required): bid, budget, portfolio, or placement.One of: bid, budget, portfolio, placement |
daypartingrequired | object | The full definition of the schedule to create. The valid/required fields depend on 'type' — see the tool description. Do not include the account id here; it is injected from the account in scope. |
baseBidStrategy | enum | How to give covered targets a base bid when some have none of their own (auto-targeting expressions that bid at their ad group default). 'use_current_bid' adopts the bid each target already runs at, so spend is unchanged until the multipliers apply. 'custom' means you have already set your own values with update_target (its baseBid field) and this call should proceed. Only send this when the tool asked for it.One of: use_current_bid, custom |
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
get_automationGet AutomationGet Automation
POST /public/v1/tools/get_automation · requires tools:read
Full definition of one automation by automation_id: its if / else-if / else rule blocks (conditions and actions), the campaigns, tags, ASINs or harvesting mapping it runs on, exclusions, schedule, lookback and notification settings.
| Parameter | Type | Description |
|---|---|---|
automation_idrequired | string | The automation id (from list_automations). |
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
get_daypartingGet DaypartingGet Dayparting
POST /public/v1/tools/get_dayparting · requires tools:read
Full definition of one dayparting schedule by type + dayparting_id: for bid / placement the time-slot allocation and the covered campaigns with their targets or placement entries; for budget / portfolio the rules and the covered campaigns or portfolios with their base budgets.
| Parameter | Type | Description |
|---|---|---|
typerequired | enum | Which kind of dayparting the id refers to (required): bid, budget, portfolio, or placement.One of: bid, budget, portfolio, placement |
dayparting_idrequired | string | The dayparting id (from list_daypartings). |
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
get_hourly_performanceGet Hourly PerformanceGet Hourly Performance
POST /public/v1/tools/get_hourly_performance · requires tools:read
Hourly advertising performance at level campaign or keyword (target level): rows bucketed by group_by (default ["hour"]; also timestamp for each hour of each day, weekday, date, and the entity dimensions campaign, keyword, ad_group), each with cost, clicks, impressions, sales, conversions, units, ACOS, ROAS, CTR, CVR and CPC, plus a totals row. Narrow with campaign_ids or keyword_ids. Always pass start_date / end_date: hourly data is rebuilt one whole local day at a time by a batch job, so today is normally empty and the range should end at yesterday or earlier. Hours are in the account timezone.
| Parameter | Type | Description |
|---|---|---|
levelrequired | enum | Granularity (required): 'campaign' or 'keyword' (target-level).One of: campaign, keyword |
start_date | string | Start date YYYY-MM-DD. Should always be passed — omitting it (with end_date) defaults to today, which usually has no rows yet. |
end_date | string | End date YYYY-MM-DD. Defaults to start_date; omitting both defaults to today. End at yesterday or earlier for the most recent complete data. |
group_by | array of enum | How to bucket rows (default ['hour']). Time dims (both levels): 'hour' (0-23), 'weekday', 'date', 'timestamp' (each hour of each day). Entity dims: 'campaign' (both levels); 'keyword' and 'ad_group' (keyword level only). Combine e.g. ['weekday','hour'] for a day-of-week x hour pattern. |
campaign_ids | array of string | Optional. Restrict to these campaign IDs (valid for both levels). |
keyword_ids | array of string | Optional. Restrict to these target IDs. Only valid when level='keyword'. |
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
list_automationsList AutomationsList Automations
POST /public/v1/tools/list_automations · requires tools:read
Automation (rule) inventory for an account: id, name, category (automate_for), status, created / updated time and how many campaigns each covers. Pass type to filter to one category (Keyword Targets, All Targets, Search Terms, Mapped Harvesting, Placements, Ad Products, Campaign, Inventory). Deleted automations are never included; dayparting schedules are listed by list_daypartings. Paginated (page_size 100, max 500).
| Parameter | Type | Description |
|---|---|---|
type | enum | Optional. Filter to a single automation category (automate_for). Omit to list automations of all types.One of: Keyword Targets, Inventory, Search Terms, Placements, All Targets, Ad Products, Campaign, Mapped Harvesting |
page | integer | Page number (0-indexed). Defaults to 0. |
page_size | integer | Results per page. Defaults to 100. Max 500. |
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
list_daypartingsList DaypartingsList Daypartings
POST /public/v1/tools/list_daypartings · requires tools:read
Dayparting schedule inventory for one type — bid (time-based target bid adjustments), placement (placement bid adjustments), budget (campaign budget adjustments) or portfolio (portfolio budget adjustments): each schedule's id, name, state / status, creation time and how many campaigns, targets or portfolios it covers.
| Parameter | Type | Description |
|---|---|---|
typerequired | enum | Which kind of dayparting to list (required): bid, budget, portfolio, or placement.One of: bid, budget, portfolio, placement |
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
preview_automationPreview AutomationPreview Automation
POST /public/v1/tools/preview_automation · requires tools:read
Dry run of a saved automation by automation_id: the entities (campaigns, keywords, targets, ads, …) it would act on right now and the action each would get, computed over the rule's current lookback window without applying anything. would_act_on is the total match count. Use it before setting a rule ACTIVE. Paginated (page_size 50, max 200).
| Parameter | Type | Description |
|---|---|---|
automation_idrequired | string | The automation id (from list_automations). |
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
page | integer | Zero-based page number. Default 0. |
page_size | integer | Rows per page. Default 50, max 200. |
update_automationUpdate AutomationUpdate Automation
POST /public/v1/tools/update_automation · requires tools:write
Change an existing automation by automation_id; updates holds only the fields to change (omitted fields keep their value). Editable everywhere: name, description, status (ACTIVE / INACTIVE; cannot archive), conditions, rule_schedule and notification settings; most categories also take selected_campaigns, selected_campaign_tags, rule_processing_time, lookback_period, lookback_skip_days and exclude_list; Inventory takes selected_asins, Mapped Harvesting selected_mapping, Campaign todays_live_data and rule_schedule.timeSlots. The category itself cannot change, and a field the category does not have is reported back, never stored. Activating requires a scope in the same call. AI Agent automations cannot be edited here.
| Parameter | Type | Description |
|---|---|---|
automation_idrequired | string | The automation id to update (from list_automations). |
updatesrequired | object | ONLY the fields to change. Do not include _id, automate_for, amazon_account_id, or workspace_id — these are not editable here. Which of the properties below apply depends on the automation's category; sending one the category does not have is ignored and reported back.Fields: name, description, status, selected_campaigns, selected_campaign_tags, campaign_adgroup_selection, campaign_tag_selection, selected_asins, selected_mapping, todays_live_data, rule_schedule, rule_processing_time, lookback_period, lookback_skip_days, exclude_list, conditions, email_notification, email_addresses, advancedMode |
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
update_daypartingUpdate DaypartingUpdate Dayparting
POST /public/v1/tools/update_dayparting · requires tools:write
Change an existing dayparting schedule by type + dayparting_id; updates holds only the fields to change. Sent lists replace: a campaign's targets (bid) is its complete desired set, and selectedCampaigns (placement) and rules (budget / portfolio) replace the whole list, so read the current definition with get_dayparting and edit it. Pause or archive via state (bid / placement) or status (budget / portfolio). A baseBid sent here is ignored — set base bids with update_target.
| Parameter | Type | Description |
|---|---|---|
typerequired | enum | Which kind of dayparting the id refers to (required): bid, budget, portfolio, or placement.One of: bid, budget, portfolio, placement |
dayparting_idrequired | string | The dayparting id to update (from list_daypartings). |
updatesrequired | object | The fields to change on this dayparting. Only include the fields you want to modify; the rest are left as-is. The valid fields depend on 'type' — see the tool description. Do not include the id or the account id here. |
baseBidStrategy | enum | How to give covered targets a base bid when some have none of their own (auto-targeting expressions that bid at their ad group default). 'use_current_bid' adopts the bid each target already runs at, so spend is unchanged until the multipliers apply. 'custom' means you have already set your own values with update_target (its baseBid field) and this call should proceed. Only send this when the tool asked for it.One of: use_current_bid, custom |
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
AI performance summary, recommendations, fired alerts, and the activity log.
dismiss_recommendationsDismiss RecommendationsDismiss Recommendations
POST /public/v1/tools/dismiss_recommendations · requires tools:write
Move open recommendations out of the queue — the app's Ignore / Mark as read / Action not required buttons. Pass up to 50 recommendation_ids from list_recommendations and a status (ignored default, action_not_required, mark_as_read). Only recommendations still new are changed; others are reported as skipped. Nothing is applied to Amazon — to act on a recommendation, make the equivalent change with the normal write tools.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
recommendation_idsrequired | array of string | Recommendation ids from list_recommendations (max 50). |
status | enum | Target state. Default 'ignored'.One of: ignored, action_not_required, mark_as_read |
get_activity_logGet Activity LogGet Activity Log
POST /public/v1/tools/get_activity_log · requires tools:read
The account's activity log — the audit trail of changes actually made to campaigns, keywords, targets and ads, newest first, with old value, new value and the source that made it (Bulk Action, Dayparting, AI Recommendation, AI Agent, MCP, Automation, …). Filter by sources, change_types (e.g. Bid Change, Budget Change, State Change), campaign_ids (max 200), targeting_values, changed_by_ids (or system), status (error = changes that failed to apply) and search. mode: "summary" returns no rows — just the total and counts by source, change type, status, entity and the 10 busiest days — so call it first to size a query. Without start_date / end_date the last 7 full days ending yesterday (account timezone) are used; only about the last 30 days are retained, and the newest few hours may not be processed yet. On this API rows come back as JSON objects (format: "toon" gives the compact columnar text instead). Paginated (page_size 100, max 500).
| Parameter | Type | Description |
|---|---|---|
start_date | string | Start of the window, ISO date (e.g. '2026-08-01'). Pair with end_date. |
end_date | string | End of the window, ISO date, inclusive. Pair with start_date. |
sources | array of enum | Only changes from these sources. Use ['Automation'] for automation activity. |
change_types | array of string | Only these change types, e.g. 'Bid Change', 'Budget Change', 'State Change', 'Add Keyword', 'Add Negative Keyword', 'Campaign Creation'. |
campaign_ids | array of string | Restrict to these campaigns (max 200). From list_campaigns. |
targeting_values | array of string | Restrict to these ASINs or keyword texts. |
changed_by_ids | array of string | User ids, or the literal 'system' for automated changes. |
status | enum | Only successful, or only failed, changes.One of: success, error |
search | string | Free-text search over campaigns/targets. Ignored when campaign_ids or targeting_values is already set. |
mode | enum | 'rows' (default) returns the page of change rows. 'summary' returns no rows at all — the total plus counts by source, change type, status, entity and the 10 busiest days in the window (not every day), for exactly the same filters. Use it to size a query before fetching it. 'page' and 'page_size' have no effect on a summary, though an invalid value for either is still a validation error. Summary counts are not all reusable as filters: every source label it reports can be passed back in 'sources', but a few change-type labels are display-only and are rejected as 'change_types'.One of: summary, rows |
page | integer | Page number (0-indexed). Defaults to 0. |
page_size | integer | Rows per page (rows mode only). Defaults to 100, max 500. An over-max value is clamped, not rejected, and the reduction is stated in 'summary'. |
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
get_ai_performance_summaryGet AI Performance SummaryGet AI Performance Summary
POST /public/v1/tools/get_ai_performance_summary · requires tools:read
The latest AI-written summary of the account's advertising performance — the summary card on the SellerMate Home dashboard: a short narrative plus structured insights and positive / negative / neutral pointers when available. Generated periodically: check generated_at; available: false means none has been generated yet.
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
get_fired_alertsGet Fired AlertsGet Fired Alerts
POST /public/v1/tools/get_fired_alerts · requires tools:read
The alerts that have fired on an account, newest first — the Alerts page's event log. Each row has when it fired, the automation (alert) name and category, the entity it fired on, a description of the matched condition and the metric snapshot it fired on. start_date / end_date are inclusive account-local days (default: the last 7 days including today; max window 90 days); automation_name is a case-insensitive partial match. To see how an alert rule is configured use list_automations / get_automation. Paginated (page_size 50, max 200).
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
start_date | string | First day, YYYY-MM-DD (inclusive). |
end_date | string | Last day, YYYY-MM-DD (inclusive). |
automation_name | string | Only alerts whose automation name contains this text (case-insensitive). |
page | integer | Zero-based page number. Default 0. |
page_size | integer | Rows per page. Default 50, max 200. |
list_recommendationsList RecommendationsList Recommendations
POST /public/v1/tools/list_recommendations · requires tools:read
The recommendations SellerMate has generated for an account, newest first: suggested bid changes, keywords / targets to add or negate, and similar actions, each with the entity it concerns. statuses defaults to ["new"] (also executed, executed_from_outside, ignored, action_not_required, mark_as_read, error); source is ai (default) or automation. executed history defaults to the last 30 days unless start_date + end_date are given. The result carries byState and byCategory counts over the whole match, then one page of rows. Read-only. Paginated (page_size 50, max 200).
| Parameter | Type | Description |
|---|---|---|
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
statuses | array of enum | Recommendation states to include. Default ['new']. |
source | enum | 'ai' (default) or 'automation' (proposed by automation rules).One of: ai, automation |
start_date | string | First day, YYYY-MM-DD. Give with end_date. |
end_date | string | Last day, YYYY-MM-DD. Give with start_date. |
ad_products | array of string | Only recommendations on these keyword texts or ASINs. |
page | integer | Zero-based page number. Default 0. |
page_size | integer | Rows per page. Default 50, max 200. |
Everything else.
create_live_ads_trackingCreate Live Ads TrackingCreate Live Ads Tracking
POST /public/v1/tools/create_live_ads_tracking · requires tools:write
Set up the account's Live Ads TRACKING schedule for a tracking_type — what the Live Ads page does under 'Ke…
| Parameter | Type | Description |
|---|---|---|
tracking_typerequired | enum | 'keyword' = keyword rank tracking; 'asin' = ASIN (product page) tracking.One of: keyword, asin |
schedule_namerequired | string | Schedule name. |
frequencyrequired | enum | How often it runs.One of: Daily, Weekly, Monthly |
timerequired | string | Run time 'HH:MM' (24h) in the account's timezone, or in 'timezone' if given. Converted to UTC; the review shows both. |
timezone | string | Optional IANA timezone for 'time', e.g. 'Asia/Kolkata'. Defaults to the account's. |
week_day | enum | Weekly only: the local day it runs. Defaults to SUN.One of: MON, TUE, WED, THU, FRI, SAT, SUN |
month_day | integer | Monthly only: the local day of month it runs. Defaults to 28. |
receiversrequired | array of string | 1-3 emails that receive the CSV report. |
preview | boolean | Return the review (run time in local timezone AND UTC, items, receivers) without saving. Defaults to false. |
itemsrequired | array of string | The COMPLETE list of keywords (or ASINs) to track. |
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
delete_live_ads_trackingDelete Live Ads TrackingDelete Live Ads Tracking
POST /public/v1/tools/delete_live_ads_tracking · requires tools:write
Delete the account's Live Ads TRACKING schedule for a tracking_type ('keyword' or 'asin')
| Parameter | Type | Description |
|---|---|---|
tracking_typerequired | enum | 'keyword' = keyword rank tracking; 'asin' = ASIN (product page) tracking.One of: keyword, asin |
preview | boolean | Show what would be deleted without deleting. Defaults to false. |
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
get_live_ads_trackingGet Live Ads TrackingGet Live Ads Tracking
POST /public/v1/tools/get_live_ads_tracking · requires tools:read
Show the account's Live Ads TRACKING schedules — the scheduled Amazon checks the Live Ads page calls 'Keywo…
| Parameter | Type | Description |
|---|---|---|
tracking_type | enum | Optional. Only this schedule; both when omitted.One of: keyword, asin |
include_items | boolean | List the tracked keywords/ASINs. Defaults to false. |
items_page | integer | Item page (0-indexed). Defaults to 0. |
items_page_size | integer | Items per page. Defaults to 100. |
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
get_live_ads_tracking_historyGet Live Ads Tracking HistoryGet Live Ads Tracking History
POST /public/v1/tools/get_live_ads_tracking_history · requires tools:read
Read what SellerMate's scheduled Live Ads tracking captured on Amazon for an account — the same history the…
| Parameter | Type | Description |
|---|---|---|
tracking_typerequired | enum | 'keyword' for keyword rank tracking, 'asin' for ASIN tracking.One of: keyword, asin |
view | enum | 'snapshot' (default) = one day; 'trend' = one ASIN over a date range.One of: snapshot, trend |
date | string | Snapshot day, YYYY-MM-DD (UTC). Omit for the most recent day with data. |
keywords | array of string | Snapshot, keyword tracking: only these keywords (exact, as tracked). |
asins | array of string | Snapshot: for ASIN tracking, only these ASINs; for keyword tracking, only results showing these ASINs. |
ad_type | enum | Snapshot, keyword tracking: which results to return. Defaults to 'all'.One of: all, sponsored, organic |
max_position | integer | Snapshot, keyword tracking: drop results ranked below this. Defaults to 10. |
latest_run_only | boolean | Snapshot: keep only each keyword/ASIN's last run of the day (default true). False returns every run that day. |
keyword | string | Trend, keyword tracking: the tracked keyword (exact, as tracked). |
asin | string | Trend: the ASIN to follow. |
start_date | string | Trend: first day, YYYY-MM-DD. Defaults to 7 days before end_date. |
end_date | string | Trend: last day (inclusive), YYYY-MM-DD. Defaults to today (UTC). |
page | integer | Snapshot page number (0-indexed). Defaults to 0. |
page_size | integer | Snapshot rows per page. Defaults to 200. Max 1000. |
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
list_harvesting_mappingsList Harvesting MappingsList Harvesting Mappings
POST /public/v1/tools/list_harvesting_mappings · requires tools:read
List the saved harvesting mappings for a specific Amazon account — the source ad group -> destination ad gr…
| Parameter | Type | Description |
|---|---|---|
mapping_id | string | Optional. Return this one mapping in full instead of the list. |
name | string | Optional. Partial, case-insensitive filter on the mapping name. |
page | integer | Page number (0-indexed). Defaults to 0. |
page_size | integer | Results per page. Defaults to 100. Max 500. |
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
search_live_adsSearch Live AdsSearch Live Ads
POST /public/v1/tools/search_live_ads · requires tools:read
Search Amazon RIGHT NOW in the account's marketplace, exactly as the Live Ads page does
| Parameter | Type | Description |
|---|---|---|
search_typerequired | enum | 'keyword' = Amazon search results; 'asin' = product page details.One of: keyword, asin |
keywords | array of string | search_type 'keyword': the search terms (up to 10). |
asins | array of string | search_type 'asin': the ASINs to look up (up to 10). |
my_asins | array of string | Optional. Your ASINs, flagged with is_my_asin in the rows. |
ad_type | enum | Keyword search: which results to return. Defaults to 'all'.One of: all, sponsored, organic |
max_position | integer | Keyword search: drop results ranked below this. Defaults to all. |
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
update_live_ads_trackingUpdate Live Ads TrackingUpdate Live Ads Tracking
POST /public/v1/tools/update_live_ads_tracking · requires tools:write
Change, pause or resume the account's Live Ads TRACKING schedule for a tracking_type ('keyword' or 'asin')
| Parameter | Type | Description |
|---|---|---|
tracking_typerequired | enum | 'keyword' = keyword rank tracking; 'asin' = ASIN (product page) tracking.One of: keyword, asin |
schedule_name | string | Schedule name. |
frequency | enum | How often it runs.One of: Daily, Weekly, Monthly |
time | string | Run time 'HH:MM' (24h) in the account's timezone, or in 'timezone' if given. Converted to UTC; the review shows both. |
timezone | string | Optional IANA timezone for 'time', e.g. 'Asia/Kolkata'. Defaults to the account's. |
week_day | enum | Weekly only: the local day it runs. Defaults to SUN.One of: MON, TUE, WED, THU, FRI, SAT, SUN |
month_day | integer | Monthly only: the local day of month it runs. Defaults to 28. |
receivers | array of string | 1-3 emails that receive the CSV report. |
preview | boolean | Return the review (run time in local timezone AND UTC, items, receivers) without saving. Defaults to false. |
items | array of string | The COMPLETE list of keywords (or ASINs) to track; replaces the current list. |
add_items | array of string | Keywords/ASINs to add to the current list. |
remove_items | array of string | Keywords/ASINs to remove from the current list. |
state | enum | PAUSED to stop the schedule, ENABLED to resume it. Optional.One of: ENABLED, PAUSED |
amazon_account_idrequired | string | The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account. |
1curl -s -X POST https://api.sellermate.ai/public/v1/tools/get_user_context \2 -H "X-API-Key: sm_live_..." -H "Content-Type: application/json" -d '{}'
Response
1{2 "user": { "id": "...", "name": "API Key: Reporting" },3 "workspaces": [{4 "id": "<workspace_id>", "name": "Acme",5 "accounts": [6 { "id": "<amazon_account_id>", "name": "Acme US", "accountType": "seller",7 "country": "US", "currency": "USD", "marketplace": "ATVPDKIKX0DER" }8 ]9 }]10}
1curl -s -X POST https://api.sellermate.ai/public/v1/tools/get_campaign_performance \2 -H "X-API-Key: sm_live_..." -H "Content-Type: application/json" \3 -d '{"amazon_account_id":"<id>","start_date":"2026-05-01","end_date":"2026-05-31","page_size":50}'
Response
1{2 "data": [ { "campaignName": "...", "cost": 1234.5, "attributedSales14d": 5678.9, "acos": 21.7, "roas": 4.6 } ],3 "summary": { "...": "full-set totals" },4 "pagination": { "page": 0, "pageSize": 50, "total": 190, "totalPages": 4, "hasMore": true, "nextCursor": "..." },5 "dateRange": { "start": "2026-05-01", "end": "2026-05-31" }6}
1curl -s -X POST https://api.sellermate.ai/public/v1/tools/get_vendor_sales_performance \2 -H "X-API-Key: sm_live_..." -H "Content-Type: application/json" \3 -d '{"amazon_account_id":"<vendor_account_id>","start_date":"2026-05-01","end_date":"2026-05-31"}'
Response
1{2 "connected": true,3 "data": [4 { "asin": "B0XXXXXXX1", "itemName": "...",5 "orderedUnits": 1240, "orderedRevenueAmount": 38760.00,6 "shippedUnits": 1180, "shippedRevenueAmount": 36890.00, "shippedCogsAmount": 21500.00,7 "customerReturns": 14, "glanceViews": 90250 }8 ],9 "summary": { "orderedRevenueAmount": 38760.00, "shippedRevenueAmount": 36890.00, "glanceViews": 90250, "asins": 1 },10 "pagination": { "page": 0, "pageSize": 100, "total": 1, "hasMore": false }11}
tools:write)1curl -s -X POST https://api.sellermate.ai/public/v1/tools/update_campaign \2 -H "X-API-Key: sm_live_..." -H "Content-Type: application/json" \3 -d '{"updates":[{"campaign_id":"<id from list_campaigns>","budget":25.0}],"_reasoning":"Scaling a winner"}'
Outcomes: applied → { "status":"success", "applied":true, ... }; blocked by policy → 422 { "error":"Policy violation …", "rule":"maxBudget" }. A write either applies or returns 422.
1import requests23BASE, KEY = "https://api.sellermate.ai", "sm_live_..."4H = {"X-API-Key": KEY, "Content-Type": "application/json"}56def call(tool, **args):7 r = requests.post(f"{BASE}/public/v1/tools/{tool}", headers=H, json=args, timeout=120)8 r.raise_for_status()9 return r.json()1011ctx = call("get_user_context")12account_id = ctx["workspaces"][0]["accounts"][0]["id"]13perf = call("get_campaign_performance", amazon_account_id=account_id,14 start_date="2026-05-01", end_date="2026-05-31")15print(perf["summary"])
updates per call.401 on the next call.{ "connected": false, "connectUrl": … } when the required Seller/Vendor Central connection is missing — that’s a normal response, not an error.GET /public/v1/tools (and /tools/{name}) always reflects the live set of tools and parameters available to your key.get_user_context.