AgentXray

Brand Analytics, analysed (brand-registered sellers): (1) search terms where this seller's product gets a click share like a competitor's but a lower conversion share — a detail-page problem (price, reviews, images), not a keyword one; (2) search terms the seller's own buyers use that the listing's title, bullets and backend keywords do not carry, each with a ready `draft` (draft_listing_update carrying the FULL backend keyword set — the field is replaced, never appended). File a draft only after the seller agrees. Use it for 'which keywords am I missing', 'why do competitors convert better', 'improve my listing for search'.

get_brand_keyword_gaps

Buy Box performance for one marketplace on the connected seller account: win rate over a window, SKUs currently losing the Buy Box with the competing price gap, and recent held-to-lost transitions. Requires a marketplace id from list_my_marketplaces.

get_buybox_status

Close a follow-up by its id (from get_follow_ups): done, or cancelled with cancel=true. The follow-up stays in its history and is not deleted, but a closed follow-up cannot be reopened, so confirm with the seller first. Nothing changes on Amazon.

complete_follow_up

Per-DAY advertising spend, sales, clicks and ACoS — the series that answers 'when did it change', which a 30-day rollup cannot. Use for pacing, for finding the day a change took effect, and before claiming any trend. A day Amazon did not report is ABSENT, not zero.

get_ads_daily_series

The MEASURED outcome of changes this seller approved and applied through AgentXray: what changed, when, and what happened to conversion in the fortnight afterwards. Verdicts are deliberately conservative — at low volume 'inconclusive' is the honest answer and the reasons say exactly why (thin traffic, day-to-day swing, another change to the same listing inside the window). A change whose window has not closed yet reports status 'measuring' with the date it can first be read. Use for 'did that change work', 'was it worth it'.

did_my_changes_work

Draft Amazon's own 'Request a Review' for the seller's recent FBA orders that have not been asked yet (purchased about 3-30 days ago, shipped). This NEVER contacts a buyer by itself: it lists the eligible orders and puts ONE draft in the seller's AgentXray Inbox (Approvals tab). Only after a person approves it does AgentXray ask Amazon, order by order, whether a request is allowed right now and send it — Amazon emails each buyer once, in Amazon's own wording, and a sent request cannot be withdrawn. The approval result counts sent / not eligible yet / already requested. At most 30 orders per draft (sending takes about 1-2 seconds per order); when more are eligible the result says so — draft again after this one is approved. Call get_review_requests first to see what was already sent.

draft_review_requests

Draft a brand-new listing (new SKU) on the connected Amazon account. This NEVER creates anything on its own: the draft waits in AgentXray for the seller's approval, and even after approval the listing is created with QUANTITY 0 so it cannot sell until the seller raises stock in Seller Central. Required: marketplace_id, a NEW sku, product_type (Amazon's UPPER_SNAKE type, e.g. ENVELOPE), item_name (≤75 chars incl. spaces), price (marketplace currency), and images.main (public https URL — fetched and measured before drafting). Optional: brand (default Generic; branded creates usually need Brand Registry), bullet_points (≤5), product_description (≤2000), images '1'..'8'. Product-type schemas vary; when the preview lists missing attributes, re-draft with them in extra_attributes. Tell the seller to run the PREVIEW in the panel: Amazon lists every missing attribute for that type without creating anything. If the sku already exists the draft is blocked; use draft_listing_update instead.

draft_create_listing

Draft a new bid for one keyword or product target on the connected Amazon Ads account. This NEVER changes the live bid: it creates a draft the seller must approve in AgentXray (your Inbox (Approvals tab)) before anything is sent to Amazon. Pass the target's recent clicks and orders (from get_ads_search_terms or get_ads_targets) and the SKU it advertises: the draft is then priced against the fees Amazon actually deducted from this seller's settlements, and comes back carrying their real break-even CPC. A bid above break-even is a WARNING, not a block. Do not resubmit a rejected draft unchanged, and state a warning once rather than pressing it.

draft_bid_change

Draft a new daily budget for one campaign on the connected Amazon Ads account. This NEVER changes the live budget: it creates a draft the seller must approve in AgentXray first. Pass the campaign's recent daily spend so the draft can say whether the new budget caps it below what it currently uses. A budget of zero is rejected by Amazon; to stop a campaign use draft_campaign_state to pause it instead. Do not resubmit a rejected draft unchanged.

draft_budget_change

Draft a change to a listing's title (item_name), bullet points, product description and/or backend search terms (generic_keyword) on the connected Amazon account. To change a listing's IMAGES use draft_image_swap instead. This NEVER edits the live listing: it creates a draft that the seller must review and approve in AgentXray (your Inbox (Approvals tab)) before anything is sent to Amazon. The draft is screened against Amazon policy and trademark rules; blocking risks come back in the response — revise and submit a new draft if so. Hard limits: item_name max 75 characters INCLUDING spaces; up to 5 bullet points; product_description max 2000 characters; generic_keyword max 250 BYTES (not characters) and it REPLACES the existing search terms, so send the full set you want, never just the additions.

draft_listing_update

Draft a NEW Sponsored Products campaign and its first ad group. This NEVER creates anything on Amazon by itself: it creates a draft the seller approves in AgentXray. On approval the campaign and ad group are created PAUSED and with no product ad, so they CANNOT spend - advertising starts only after draft_create_product_ad and an explicit enable. daily_budget is REQUIRED and must come from the seller: never invent one, and never carry over a number from another campaign.

draft_create_campaign

Draft a placement bid adjustment (Top of Search, product pages or rest of search) for one Sponsored Products campaign. This NEVER changes the live campaign: it creates a draft the seller must approve in AgentXray first. On apply, the campaign's OTHER placement adjustments and its bidding strategy are kept - only the one named here changes. Pass the placement's own clicks, orders, cost and sales from get_ads_placements: a raise is judged on what that placement converted, and comes back with a WARNING when it has under 3 orders, runs above the seller's break-even ACoS, jumps more than 50 points, or the campaign uses dynamic up-and-down bidding (Amazon already raises Top of Search bids itself). Still approvable - the seller decides. Use 0 to remove an adjustment.

draft_placement_modifier

Draft a new REGULAR price for one SKU on the connected Amazon account. This NEVER changes the live price: it creates a draft the seller must review and approve in AgentXray (the Approvals page in the sidebar). The draft reads the current price from Amazon and reports what the new price does to the seller's measured break-even ACoS — read that back verbatim, because every bid and budget decision on the account was derived from the OLD price. It changes the regular price only: if a sale or coupon is running, buyers keep paying the sale price until that window ends, and the draft says so. Not for Business/B2B pricing.

draft_price_change

Draft adding one or more keywords to an EXISTING ad group. Send them as ONE draft with a keywords array - not one draft per keyword - because the seller's approval queue caps at 25 open drafts and a normal keyword build is larger than that. Each keyword takes text, match_type (EXACT/PHRASE/BROAD) and an optional bid; a bid above the seller's measured break-even CPC comes back as a WARNING, not a refusal, because a new keyword has no history to judge.

draft_add_keywords

Draft putting a SKU into an ad group as a product ad. This is the step that makes a campaign actually advertise something: a campaign with keywords or targets but NO product ad never serves and never spends, and looks launched until somebody checks. If the seller has just created a campaign, this is the next call.

draft_create_product_ad

Draft an inbound FBA shipment for the seller to approve. This NEVER creates anything on Amazon by itself: it checks the plan against the constraints that actually get shipments rejected and puts it in front of the seller in AgentXray (your Inbox (Approvals tab)). Storage-capacity checking (Amazon measures it in CUBIC METRES, not units) is only active on marketplaces where the account's confirmed limit is on file — today that is Australia. Elsewhere the draft says the limit is unknown rather than implying the plan fits. On approval it creates a DRAFT inbound plan in their Amazon account; they then finish packing, placement and carrier steps in Seller Central, where Amazon shows the real costs. Nothing is defaulted: a ship-from address and carton dimensions must come from the seller or from a saved supplier quote. Do not invent them — a guessed address does not fail loudly.

draft_shipment_plan

Draft a replacement for one or more of a listing's images on the connected Amazon account. This NEVER edits the live listing: it creates a draft the seller must review and approve in AgentXray (your Inbox (Approvals tab)) before anything is sent to Amazon. Give a public https URL per slot — 'main' for the hero image, '1' to '8' for the secondary ones. Each URL is FETCHED AND MEASURED before the draft is approvable (format, dimensions, and for the main slot the background), and whatever fails comes back in the risk list with the measured value. Amazon needs at least 500px on the longest side and 1600px for detail-page zoom. Note that a main image Amazon's classifier rejects can SUPPRESS the listing, which is worse than a failed validation — say so when you propose one.

draft_image_swap

Draft one or more negative keywords for a campaign or ad group on the connected Amazon Ads account. This NEVER blocks a term live: it creates a draft the seller must approve in AgentXray first. Pass the term's clicks, orders and spend from get_ads_search_terms. A negative proposed on a handful of clicks comes back with a WARNING stating what those clicks actually support: zero orders on single-digit clicks is what a normal conversion rate looks like most of the time, so blocking there can cut traffic that would have converted. Still approvable - the seller decides. State it once; do not press.

draft_negative_keyword

Draft pausing or re-enabling the Sponsored Products ads of ONE SKU, without touching its campaigns, ad groups or the other products advertised beside it - for a product that is out of stock or losing money while a sibling in the same campaigns sells. Name the SKU; AgentXray finds every ad group on the connected Ads account that advertised it and lists them in the draft, so ONE draft covers the product everywhere (narrow it with campaign_id or ad_group_ids). This NEVER changes the live ads: it creates a draft the seller must approve in AgentXray first. The product's clicks, spend, orders and sales are measured by AgentXray, not taken from you: pausing a product that produced orders comes back with a WARNING naming the contribution it generates. Still approvable - the seller decides.

draft_product_ad_state

Draft pausing or re-enabling ONE keyword or product target - the finer-grained sibling of draft_campaign_state, for when a single competitor ASIN or search term should stop while the rest of the campaign keeps running. This NEVER changes the live target: it creates a draft the seller must approve in AgentXray first. target_type must be 'product_target' for an ASIN target and 'keyword' for a keyword - it decides which Amazon endpoint the approved change goes to. Pass recent_orders: pausing a target that is producing comes back with a WARNING naming the contribution it generates at this seller's own unit economics. Still approvable - the seller decides. Get target ids from get_ads_targets.

draft_target_state

Draft pausing or re-enabling one campaign on the connected Amazon Ads account. This NEVER changes the live campaign: it creates a draft the seller must approve in AgentXray first. Pass the campaign's recent orders and sales: pausing an arm that is producing orders comes back with a WARNING stating the contribution it currently generates at this seller's own unit economics, because pausing stops that too, not only the spend. Still approvable - the seller decides.

draft_campaign_state

Draft adding product (ASIN) targets to an EXISTING ad group - this is how a seller advertises on a competitor's product page. Send the ASINs as one array in one draft. All targets in a draft share one bid. A product target only serves where Amazon judges the seller's product relevant to the targeted page, so zero impressions can mean irrelevance rather than a low bid; say that rather than recommending a bid raise straight away.

draft_add_product_targets

FBA inventory age for one marketplace on the connected seller account: how stock is distributed across age buckets and which SKUs are approaching long-term storage fees. Use this for 'is my stock getting old', 'will I be charged storage fees'. Requires a marketplace id from list_my_marketplaces.

get_inventory_age

FBA inbound shipments: which are on their way, units sent vs units Amazon has received, status and destination warehouse, and closed shipments where Amazon received fewer units than were sent. Use it for 'where is my shipment', 'has Amazon received my stock', 'is anything missing from a shipment'. Its `narrative` is the answer.

get_inbound_shipments

Delete one saved memory by its id (from recall), when the seller says a goal or rule no longer applies. Only this workspace's memories can be deleted. Nothing changes on Amazon.

forget

The seller's follow-ups: what is due now first, then what is still waiting. Call it at the start of a conversation. status: active (default: open + due), due, open, done, cancelled or all. Its `narrative` is the answer.

get_follow_ups

List the Amazon marketplaces on the seller account connected to this AgentXray workspace. Call this FIRST whenever a question needs a marketplace id (Buy Box, inventory age) so you never guess one.

list_my_marketplaces

List the Amazon seller accounts connected to this workspace, with the marketplaces each one covers. An agency has one per client; a single seller has one. Every marketplace-scoped tool takes an 'account' argument naming which of them to answer about, and refuses rather than guessing when several could apply.

list_my_accounts

Listings with problems Amazon reported (errors that block a listing from selling, and warnings), with Amazon's own message per SKU, and listing deadlines that are still open. A listing that is simply not buyable (often no stock) is counted separately, not reported as a problem. Use it for 'are any of my listings suppressed', 'listing errors', 'why can't my product be bought'. Its `narrative` is the answer.

get_listing_issues

Every negative keyword on the account, with its campaign and ad group and a self_block flag. self_block means the seller also bids on that exact term in the same ad group — the campaign blocks a keyword it pays for. A negative is invisible by construction, so this list is the only way to see one.

get_ads_negatives

Net contribution per ad group, priced with the seller's own economics measured from their settlement (price, Amazon fees, storage, saved unit costs): spend, ad sales, ACoS, CPC, the highest CPC each ad group can afford, and kill candidates. Read its `narrative` as the answer.

get_ad_group_profit

One SKU over time on one marketplace: units per day, the price buyers actually paid after promotions against the listed price, sessions, conversion and Buy Box %, and settled net profit per week. Use it for 'how is this product doing over time', 'did my price change hurt conversion', 'what do buyers really pay'.

get_sku_trend

The seller's Amazon payout balance and why it moved, from Amazon's own settlement lines: what the current settlement started from (negative = still owed to Amazon), what is released and held now, and the last settlements broken into buckets with the posting date of every advertising invoice, debt adjustment and carried balance. Use it for 'why is my balance negative', 'what triggered −X', 'what did Amazon deduct', 'when do I get paid'. Money only — units live in get_inventory_reconciliation.

get_payout_balance

Product (ASIN) and category targets: clicks, orders, spend and sales per target, its measured break-even CPC against its bid, and — when that ASIN is a watched competitor — its latest Buy Box price, offer count and weakness signal. Use it for 'which competitor ASINs should I target', 'are my product targets profitable', 'is the competitor I target out of stock'.

get_product_target_performance

Per-SKU profit ranking for the connected seller account over a window: units, revenue, fees, COGS, net profit and margin per SKU. Use this for 'which product makes money', 'which SKU is losing money', 'what should I stop selling'.

get_profit_by_sku

Real profit and loss for the connected Amazon seller account over a window: revenue, Amazon fees, COGS, net profit and margin, grouped per currency. Numbers come from posted Amazon fee events joined to the seller's own orders and saved product costs, so fees include the consumption tax Amazon actually charged (such as AU GST). Use this for 'what did I actually make', 'was last month profitable', 'what are my fees'.

get_profit_summary

The seller's saved goals, rules, decisions and notes for this workspace — call it at the start of a conversation and before advising, and follow the goals and rules in every answer. Optional kind filters to one kind; optional sku returns that SKU's memories plus the general ones. Its `narrative` is the answer.

recall

Brands registered to this seller in Amazon Brand Registry, with the brand entity id, as Amazon's Advertising API reports them. Call this before proposing anything brand-gated — Sponsored Brands, A+ Content, Brand Analytics and Vine all require an enrolled brand. An empty list distinguishes 'no brand enrolled' from 'not synced yet'.

get_my_brands

Save something the seller wants remembered across conversations: a goal ('keep ACoS under 25% on SKU X'), a rule ('never pause the Brazil campaign'), a note, a decision, or something learned. kind is one of goal, rule, note, decision, learned; text is at most 500 characters; sku, campaign_id and marketplace_id optionally scope it. Saved only inside AgentXray — nothing changes on Amazon. Save the seller's own words; do not save numbers you computed.

remember

Customer returns for one marketplace over a window: units returned against units sold in the same window (a same-window rate), the most returned products, the reasons Amazon recorded and customers' own comments. Use it for 'how many returns', 'why are customers returning', 'which product has the most returns'. Its `narrative` is the answer.

get_returns