query_promotions
PROMOTIONS RUNNING OR TO COME: the deals, coupons, price discounts and seller promotions of the accounts of the call that have started and not ended, or are scheduled, with the products each applies to. The same service as the promotions badge and modal of the app's Live page (POST /v2/promotions and /v2/promotions/summary), read off a table Nova rebuilds every hour from what Amazon lists. Answers: what is on promotion right now, what starts next and when, which products a deal or a coupon covers and at what price or discount, how a running deal or coupon is doing so far. type is one of DEAL (a Best Deal, a Lightning Deal or a Deal of the Day: subtype says which once Amazon's deal report lists the deal), COUPON (subtype STANDARD, SUBSCRIBE_AND_SAVE or REORDER_REWARDS), PRICE_DISCOUNT (a lower price on an offer for a period) and BASKET_BUILDING (a seller promotion: a discount or a free item for buying a quantity or an amount). state is decided at the time of the call (readAt) on the promotion's own dates: "running" = started and not ended, "upcoming" = not started yet; a promotion that has ended or was cancelled is not listed. Nova reads Amazon's list several times a day for a Seller Central account and once a day for a Vendor Central one: a promotion created since may not be listed yet. THE LIST (default): one record per promotion, the running ones first, then by start date. Each carries startAt / endAt (ISO instants, UTC; endAt null = Amazon gives no end), appliesTo ("products", or "whole_catalogue" for a seller promotion on every product of the account on that marketplace: it names no product, productCount is 0), its terms (percentOff in percentage points, 20 = 20 %; amountOff and promotionPrice in terms.currency; each a min / max over the products, equal when they all agree; the quantity or amount to buy to qualify), its budget when the promotion has one, its performance and its products (per product: the ASIN, the SKUs Amazon names for it, an empty list meaning every offer of the ASIN, its own price or discount, its own figures when Amazon reports them by product). A seller promotion can be TIERED, giving more for buying more (10 % from 2 units, 18 % from 3, 25 % from 5): terms.tiers then lists every step, the entry one first, each with the units (purchaseQuantityThreshold) or the amount (purchaseAmountThreshold, in terms.purchaseAmountCurrency) to buy to reach it and its percentOff; terms.percentOff runs from the entry step (min) to the top one (max), while the thresholds of terms and a product's own percentOff are the entry step's. tiers is empty when the promotion has one step. performance is the promotion's figures so far, CUMULATED SINCE IT STARTED and not a period; source says where they come from. A deal's and a coupon's are what Amazon reports: source names the Amazon report, asOf the day Nova read it. Amazon has no report for a seller promotion (BASKET_BUILDING): its source is "nova_order_lines", Nova's own count, on the day asOf, of the order lines that carry the promotion's trackingId since it started, cancelled orders left out. There unitsSold and salesAmount (the item price of those lines before the discount, shipping not included) are given for the promotion and for each product, 0 when no order has used the promotion yet; discountAmount is given only when none of those lines carries another promotion too (an order line has one discount for all the promotions applied to it), null otherwise. A price discount has no performance: Amazon has no report for it and an order line does not name it. null = no figure for that promotion (a price discount, a seller promotion that has not started, a deal or a coupon Amazon's report does not list yet), never zero; a null figure inside it is one the source does not carry. Amounts stay in the currency Amazon names, the marketplace's, never converted and never to be added across currencies. At most 100 products are listed under a promotion (productsTruncated says when there are more, productCount how many); when the call names products (childAsins, skus, parentAsins, tags) only THOSE products are listed under each promotion. pagination.total counts the promotions the filters keep. SUMMARY (summary=true): the counts behind the page's badge, per row of groupBy: running, upcoming, the same by types, and wholeCatalogue (how many of them are promotions on the whole catalogue, counted on every listed product of the account). A row's count is the number of DISTINCT promotions that apply to at least one of its products, so a parent's count is never the sum of its variants' (a coupon on three variants counts once on their parent). Only the rows with a promotion come back. groupBy sellerAccount or marketplace counts every account or marketplace of the call; a product grouping (childAsin, the default; sku; parentAsin) counts the rows named in keys, at most 200. Not a metrics tool: no period and no cost. What the promotions cost over a period (the discounts given on the orders) is a P&L line of query_metrics; what a product sold today is query_live. Not in this tool: the Subscribe & Save programme's own discount (query_subscribe_and_save; a Subscribe & Save coupon is a COUPON here), Brand Tailored promotions, Vine, and the advertising campaigns (query_advertising).
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "query_promotions"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| keys | No | With summary=true and a product grouping, the rows to count, at most 200: ASINs (childAsin), SKUs (sku), or parent rows spelled "<marketplaceId>:<parentAsin>" (parentAsin), the `key` of a query_live products row under the same groupBy. | |
| skus | No | Keep the promotions that apply to these SKUs (Seller Central). | |
| tags | No | "Your Filters" tag IDS from list_tags (manual custom tags or predefined segmentations, Brand included) — a tag NAME is rejected. | |
| limit | No | List only: promotions to return, 1 to 200 (default 50). `pagination.total` says how many the filters keep. | |
| state | No | List only: "running" keeps the promotions that have started, "upcoming" the ones to come. Omit for both, the running ones first. | |
| types | No | List only: keep these types (DEAL, COUPON, PRICE_DISCOUNT, BASKET_BUILDING). Omit for every type. | |
| offset | No | List only: promotions to skip, for pagination (default 0). | |
| reason | No | One sentence, ALWAYS IN ENGLISH (regardless of the conversation language), on WHY you are making this call — the user question or your analytical goal. Recorded so the seller can see how their data is used. | |
| groupBy | No | With summary=true, the rows counted: childAsin (default), sku or parentAsin, which count the rows named in `keys`; marketplace or sellerAccount, which count every marketplace or account of the call. | |
| summary | No | true = the counts per row of `groupBy` (SUMMARY above: running, upcoming, by type) instead of the promotions themselves. Omit to list the promotions. | |
| accounts | No | Restrict to a subset of your own seller account IDs (from list_accounts). Omit to include all your accounts. A brand/account name is accepted and resolved to its id when it matches one of your accounts unambiguously; a label that carries the id ("Brand (A1B2C3D4E5F6G)") resolves to that id. | |
| channels | No | The Amazon programme to read: 'SELLER' = Seller Central (3P), 'VENDOR' = Vendor Central (1P), both = one read, each promotion naming its own channel. Omit = SELLER whenever the accounts of the call include a Seller Central account, else VENDOR. | |
| childAsins | No | Keep the promotions that apply to these ASINs. | |
| parentAsins | No | Keep the promotions that apply to a variant of these parent ASINs. | |
| marketplaces | No | Marketplaces to read: country codes (US, DE), domains (amazon.de) or marketplace ids. Omit for every marketplace of the accounts. |