Skip to main content
Glama

Nova Amazon MCP Server

query_promotions

Read-only

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

NameRequiredDescriptionDefault
keysNoWith 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.
skusNoKeep the promotions that apply to these SKUs (Seller Central).
tagsNo"Your Filters" tag IDS from list_tags (manual custom tags or predefined segmentations, Brand included) — a tag NAME is rejected.
limitNoList only: promotions to return, 1 to 200 (default 50). `pagination.total` says how many the filters keep.
stateNoList only: "running" keeps the promotions that have started, "upcoming" the ones to come. Omit for both, the running ones first.
typesNoList only: keep these types (DEAL, COUPON, PRICE_DISCOUNT, BASKET_BUILDING). Omit for every type.
offsetNoList only: promotions to skip, for pagination (default 0).
reasonNoOne 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.
groupByNoWith 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.
summaryNotrue = the counts per row of `groupBy` (SUMMARY above: running, upcoming, by type) instead of the promotions themselves. Omit to list the promotions.
accountsNoRestrict 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.
channelsNoThe 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.
childAsinsNoKeep the promotions that apply to these ASINs.
parentAsinsNoKeep the promotions that apply to a variant of these parent ASINs.
marketplacesNoMarketplaces to read: country codes (US, DE), domains (amazon.de) or marketplace ids. Omit for every marketplace of the accounts.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare a safe read, and the description supplies the operational context they cannot: Nova rebuilds the table hourly and reads Amazon's list a few times a day for Seller Central but once a day for Vendor Central, so a newly created promotion may be missing; it defines null as "no figure" rather than zero, caps product listing at 100 with productsTruncated, and forbids adding amounts across currencies.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The lead sentence and the LIST/SUMMARY/NOT-IN-THIS-TOOL structure are well front-loaded, but the body is a dense ~600-word block mixing tier mechanics, performance sourcing and currency rules, with heavy capitalization and backticked identifiers that slow scanning. Much is justified by the 15 parameters and absent output schema, yet the tier explanation and the performance-source discussion could be compressed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 15 optional parameters, no output schema, and a summary mode that returns a wholly different shape, the description carries the full burden and does so: it documents record fields (startAt/endAt, appliesTo, terms, budget, performance, products), the tiered-terms edge case, source/asOf provenance, truncation, and the summary counting rules.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already carries each parameter's meaning; the description nonetheless adds behavior the schema only gestures at, notably that state is decided at read time against the promotion's own dates, that naming products via childAsins/skus/parentAsins/tags narrows what is listed under each promotion, and that groupBy product rows count distinct promotions so a parent is never the sum of its variants.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening line states a specific resource and scope ("deals, coupons, price discounts and seller promotions ... that have started and not ended, or are scheduled") and the description immediately names its siblings it is not (query_metrics, query_live, query_subscribe_and_save, query_advertising), so an agent can place it without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It enumerates the answerable questions (what is on promotion now, what starts next, which products a deal covers, how a running deal is doing) and explicitly excludes adjacent cases: cost over a period belongs to query_metrics, today's sales to query_live, the Subscribe & Save programme discount to query_subscribe_and_save. It also states which states are omitted from results (ended/cancelled).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.