SellerMate Public API

Every request must carry your API key, sent either way:

1X-API-Key: sm_live_xxxxxxxxxxxxxxxxxxxx
Copy

or

1Authorization: Bearer sm_live_xxxxxxxxxxxxxxxxxxxx
Copy

• Keys look like sm_live_….
• A workspace admin creates a key in the SellerMate web app (Profile → API Keys). The full key is shown once, at creation — store it securely; it can’t be retrieved later.
• A key is scoped to a single workspace, can be limited to specific Amazon accounts, and can be revoked at any time (revocation takes effect immediately).

Three independent checks apply to every call — all must pass:

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.

Response shapes

• Success: the tool’s result object, returned directly (no wrapper).
• Auth / rate-limit errors: { "status": <code>, "message": "..." }
• Tool errors: { "error": "..." } (policy violations also include rule, scope, message).

Status codes

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.

• Account selection. 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.)
• Dates are YYYY-MM-DD strings (start_date, end_date). Exception: get_sqp_report uses integer month + year.
• Pagination. Report/list tools return a 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.)
• Sorting (performance tools): sort_field (a metric) + sort_direction (asc|desc, default desc).
• Common metrics: cost (spend), attributedSales14d (sales), impressions, clicks, purchases (orders), acos, roas, ctr, cpc, cvr.
• Authoritative schema: GET /public/v1/tools/{name} returns the live JSON Schema for any tool — the source of truth if this page ever lags the API.

GET /public/v1/tools

List 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_..."
Copy

GET /public/v1/tools/{name}

Return the JSON Schema for one tool. 404 if unknown or outside your scope.

POST /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"}'
Copy

R = requires tools:read, W = requires tools:write. workspace_id / amazon_account_id are auto-filled per §4 and omitted below unless noted.

Discovery

get_user_contextR — Your accessible workspaces and Amazon accounts (each with id, name, accountType, country, currency, marketplace). Call this first to get the account IDs the other tools need.

• Arguments: none.

get_sellermate_capabilitiesR — What the SellerMate platform supports beyond these API tools (with deep links).

• Optional: query (string — what you’re trying to do).

Campaigns

list_campaignsR — Campaign inventory (no metrics): name, state, budget, type, targeting type.

• Optional: status (ENABLED|PAUSED|ARCHIVED, default ENABLED), sponsored_type (Product|Brand|Display), name_search.

get_campaign_performanceRPaginated — Ads metrics per campaign over a date range (spend, sales, ACOS, ROAS, CTR, CPC, orders, CVR) + summary.

• Required: start_date, end_date.
• Optional: campaign_ids, campaign_name, status (default ENABLED — pass campaign_ids or status to include paused/archived), tag_values, group_by_tag, page, page_size.

get_marketplace_summaryR — Aggregated ads metrics per account across the workspace.

• Required: start_date, end_date.
• Optional: amazon_account_ids (list; defaults to all accounts the key can reach).

update_campaign_budgetW — Set absolute daily budgets. Passes through budget policy (may be blocked → 422, or queued for approval).

• Required: updates — array (1–50) of { campaign_id, new_budget }.
• Optional: _reasoning (stored in the audit log).

create_campaignW — Create one Sponsored Products campaign. Asynchronous: returns status:"processing" + a session_id; poll get_campaign_creation_status.

• Required: name, sponsored_type (Product), targeting_type (AUTO|MANUAL), daily_budget, ad_group ({ name, default_bid, products:[{asin,…}] }; ASINs from list_product_catalog).
• Optional: state, dynamic_bidding, _reasoning.

get_campaign_creation_statusR — Poll an async create_campaign job.

• Required: session_id. Returns per-step status and the new campaignId once assigned.

Targeting

list_targetsRPaginated — Full inventory of targets (keywords / product / auto): id, current bid, state, match type, keyword text or product expression, parent campaign/ad-group ids, marketplace/country. No metrics.

• Optional: state (ENABLED|PAUSED|ARCHIVED|ALL; omit or ["ALL"] returns every state), sponsored_type, campaign_id, ad_group_id, keyword_text, include_tags, page, page_size.

get_targeting_performanceRPaginated — Metrics per target; default grouping targetingValue + campaignName.

• Required: start_date, end_date.
• Optional: group_by (e.g. targetingValue, campaignName, week, month), targeting_type, targeting_value, campaign_ids, ad_group_ids, sponsored_type, sort_field, sort_direction, page, page_size.

get_search_term_performanceRPaginated — Customer search-query metrics; default grouping searchTerm.

• Required: start_date, end_date.
• Optional: search_term, group_by, campaign_ids, ad_group_ids, targeting_type, sort_field, sort_direction, page, page_size.

update_target_bidW — Set absolute bids on keywords/product targets. Passes through bid policy.

• Required: updates — array (1–50) of { target_id, new_bid }. Optional: _reasoning.

Negatives

list_negative_targetsRPaginated — Negative-targeting inventory: negative keywords and negative product targets, at ad-group and campaign scope. Returns type, scope, campaignId, adGroupId, matchType, keywordText or expression, state, sponsoredType, createdAt/updatedAt.

• Optional: data_type (keyword|product|all), scope (campaign|adGroup|all), campaign_id, ad_group_id, state, sponsored_type, match_type, page, page_size.

Products & reports

get_advertised_product_performanceRPaginated — Ads-only metrics per advertised ASIN.

• Required: start_date, end_date. Optional: ad_asin, ad_product_name, campaign_ids, report_type, group_by, sort_field, sort_direction, page, page_size.

get_retail_product_performanceR — Combined retail + ads metrics per ASIN: total revenue, sessions, page views, buy-box %, TACoS, organic-vs-ads. Requires Seller Central (returns a connect prompt if not connected).

• Required: start_date, end_date. Optional: asin, item_name, listing_type (child_asin|parent_asin), sort_field, sort_direction, page, page_size.

get_placement_performanceRPaginated — Metrics per placement (Top of Search / Product Page / Rest of Search; SB also Home) per campaign, plus bid-adjustment % and bidding strategy.

• Required: start_date, end_date. Optional: sponsored_type (set this for SP-only or SB-only numbers), placement_classification, campaign_ids, campaign_names, state, group_by, sort_field, sort_direction, page, page_size.

get_sqp_reportR — Amazon Search Query Performance, one row per (ASIN, query). Uses month + year, not a date range.

• Required: month (1–12), year. Optional: asin, search_query, sort_field, sort_direction, page, page_size (default 50, max 200).

get_orders_reportR — Orders for a date range: aggregate totals + breakdown by state; raw rows only on request.

• Required: start_date, end_date. Optional: include_orders (default false), max_orders_per_state, top_states, state, marketplace_ids.

get_tagsR — Legacy tag inventory for one entity type (labels, colors, assigned entities, optional per-tag metrics).

• Required: data_type (campaign|product|targeting|search_term). Optional: include_entities, include_metrics (+ start_date/end_date), tag_labels.

list_product_catalogR — Seller ASINs + SKUs. Requires Seller Central.

• Mode 1 (catalog): omit dates. Mode 2 (catalog + performance): pass start_date + end_date.
• Optional: asins, skus, name_search, fulfillment_channel (FBA|FBM|ALL), include_suppressed, limit (default 50, max 200), offset; Mode 2 only: include_ads_metrics, include_retail_metrics, unadvertised_only, max_acos, min_total_revenue, sort_by.

get_inventoryR — Per-ASIN stock (FBM qty, FBA fulfillable/warehouse balance, snapshot date). Requires Seller Central.

• Optional: asins, view (merged|fbm|fba), limit (default 50, max 200), offset.

Vendor Central

These serve Vendor Central accounts (distinct from Seller Central). On an account without a Vendor Central connection they return { "connected": false, "connectUrl": … } rather than data. Use get_user_context and pick an account whose accountType is vendor.

get_vendor_inventoryR — Vendor on-hand inventory per ASIN: sellable (available) + unsellable units, with name/image.

• Optional: inventory_type (sourcing default | manufacturing), asins, page, page_size.

get_vendor_sales_performanceRPaginated — Vendor 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. summary covers the full set.

• Required: start_date, end_date. Optional: asins, page, page_size.

list_vendor_productsRPaginated — Vendor catalog (ASIN, item name, image) for ASIN discovery.

• Optional: asins, page, page_size.

Discover your accounts

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 '{}'
Copy

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}
Copy

Campaign performance (paginated)

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}'
Copy

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}
Copy

Vendor sales by ASIN

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"}'
Copy

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}
Copy

Update a budget (requires tools:write)

1curl -s -X POST https://api.sellermate.ai/public/v1/tools/update_campaign_budget \
2  -H "X-API-Key: sm_live_..." -H "Content-Type: application/json" \
3  -d '{"updates":[{"campaign_id":"<id from list_campaigns>","new_budget":25.0}],"_reasoning":"Scaling a winner"}'
Copy

Outcomes: applied → { "status":"success", "applied":true, ... }; blocked by policy → 422 { "error":"Policy violation …", "rule":"maxBudget" }; needs approval → { "status":"pending_approval", "applied":false, "rollback_token":"…" }.

Python quickstart

1import requests
2
3BASE, KEY = "https://api.sellermate.ai", "sm_live_..."
4H = {"X-API-Key": KEY, "Content-Type": "application/json"}
5
6def 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()
10
11ctx = 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"])
Copy

• Per-call batch cap: write tools accept at most 50 items in updates per call.
• One-time secret: an API key’s value is shown only at creation; lost keys must be revoked and recreated.
• Revocation is immediate: a revoked key returns 401 on the next call.
• SP-API / Vendor tools return { "connected": false, "connectUrl": … } when the required Seller/Vendor Central connection is missing — that’s a normal response, not an error.
• Discovery is authoritative: GET /public/v1/tools (and /tools/{name}) always reflects the live set of tools and parameters available to your key.