Amazon Ads MCP Tool Reference

When to use

Inspect overall ad spend efficiency, campaign comparisons, and campaign-level performance outliers.

Tips

• Sort by ACOS descending to list campaigns with the highest ad cost of sales first.
• Use campaign_name with % wildcards to filter by your naming convention (e.g. "SP-Exact%").
• Compare 30-day windows rather than 7-day windows, because the 14-day attribution window makes short periods unreliable.
• Use profile_id to isolate a specific advertising profile. Profiles are tied to the workspace's active marketplace; non-US access is support-approved during rollout and is not broad global fan-out.

Watch out

• Ads data has a 3-day attribution lag. Recent days will show incomplete sales and ACOS.

Related tools

When to use

Use this when you need campaign state, budget, bidding, portfolio, or placement bid modifier history, or the setting deltas between daily snapshots. view=changes is the reliable 'what changed to my SP campaigns' surface (Amazon's own change history excludes API changes); pair it with get_action_history for changes agentcentral made.

Tips

• Use view="history" to audit the settings in force on a given day.
• Use view="changes" with change_types when reviewing state, budget, bidding, portfolio, or placement modifier changes.
• To reconstruct what changed around a performance shift, combine view=changes (any-source SP campaign settings) with get_action_history (changes agentcentral made). Amazon's get_ads_change_history only shows console edits and is usually empty for agent-managed accounts.
• Pair with get_campaign_performance to separate configuration changes from metric movement.

Watch out

• Campaign snapshots are daily, so same-day writes appear after the next daily snapshot refresh.
• The changes view needs at least two days of snapshots to compute a delta, so it is empty in a tenant’s first day or two.

Related tools

When to use

Inspect Amazon-recorded manual console edits by entity, event time, campaign, ad group, keyword, or change type.

Tips

• Use entity_type and change_type to narrow a broad event window.
• Use get_campaign_snapshots view="changes" for Sponsored Products campaign-setting changes from any source.
• Use get_action_history for writes submitted through agentcentral.

Watch out

• Amazon excludes API changes, including agentcentral writes, from this source. Agent-managed accounts can therefore return no events.
• Amazon does not identify who made a change, and Sponsored Display events are not returned.

Related tools

When to use

Compare ad groups within a campaign by spend, sales, ACOS, and conversion rate.

Tips

• Filter by campaign_name first, then sort by ACOS to find the worst-performing ad groups within a campaign.
• Compare ad group performance across campaigns to find where the same product performs best.
• Use ad_group_name filter with wildcards to target groups by naming pattern.

Watch out

• Ads data has a 3-day attribution lag. Recent days will show incomplete sales and ACOS.

Related tools

When to use

Inspect individual keyword bids, ACOS, ROAS, spend, sales, and impression share.

Tips

• Sort by spend descending to list highest-spend keywords first, then compare ACOS and ROAS.
• Filter by keyword_type=EXACT to focus on your most intentional targeting.
• Look at top_of_search_impression_share to gauge bid competitiveness.
• Use the keyword filter with wildcards to find all variations of a root keyword.
• Rows with keyword_type TARGETING_EXPRESSION or TARGETING_EXPRESSION_PREDEFINED are Sponsored Products target rows; their target IDs currently appear in keyword_id and can be used with update_target_bids.

Watch out

• Ads data has a 3-day attribution lag. Recent days will show incomplete sales and ACOS.

Related tools

When to use

Compare spend, sales, ACOS, ROAS, CTR, and CVR across ad placements.

Tips

• Compare ACOS between Top of Search and Rest of Search placement rows.
• Product Page placements often have lower CTR but can have good CVR for complementary products.
• Use update_campaign_bidding separately when the caller has selected placement adjustment values.

Watch out

• Ads data has a 3-day attribution lag. Recent days will show incomplete sales and ACOS.

Related tools

When to use

Check SP spend, clicks, sales, ACOS, and ROAS for products that are directly advertised in Sponsored Products campaigns.

Tips

• Sort by spend descending to find your highest-cost advertised products, then check ACOS and same_sku_sales.
• Compare same_sku_sales vs total sales to see how much cross-sell attribution is happening.
• Filter by a specific ASIN to see SP campaigns and ad groups advertising that product.

Watch out

• Sponsored Brands, DSP, and campaign spend not tied to the ASIN as the advertised product are not included.
• Ads data has a 3-day attribution lag. Recent days will show incomplete sales and ACOS.

Related tools

When to use

Discover which products customers are buying after clicking ads for a different product, and identify cross-sell or halo effects.

Tips

• Filter by advertised_asin to see all products that customers bought after clicking ads for that ASIN.
• Look for cases where purchased_asin differs from advertised_asin to identify cross-sell attribution patterns.
• This data only contains sales attribution. There is no click, impression, or cost data here.

Watch out

• This table has no click, impression, or cost data. It only contains sales attribution.
• Ads data has a 3-day attribution lag. Recent days will show incomplete sales.

Related tools

When to use

Inspect converting search terms, non-converting spend, matched keyword text, match type, ad product, and ad-attributed metrics across SP and SB.

Tips

• Leave ad_product unset when the caller names a campaign but does not know whether it is SP or SB.
• Sort by spend descending with a high limit to find search terms burning budget without converting.
• Filter for search terms with high clicks and zero sales when reviewing non-converting traffic.
• For Sponsored Brands search terms specifically, set ad_product=SB; SB search-term harvesting also works through get_sponsored_ads_report with ad_product=SB and report_view=search_terms.
• Use ad_product, match_type, and keyword columns to distinguish source targeting from the customer search term.

Watch out

• Ads data has a 3-day attribution lag. Recent days will show incomplete sales and ACOS.
• Sponsored Display search-term reporting is not currently exposed as a retained search-term table; use SD targeting/campaign reports for SD analysis.

Related tools

When to use

Get the full picture of product performance including organic and paid traffic combined, check conversion rates and Buy Box percentages, or analyze traffic composition (browser vs Amazon mobile-app sessions and page views).

Tips

• Compare avg_conversion_rate across ASINs to list products by conversion-rate differences.
• Low avg_buy_box_pct indicates competitive pressure or pricing issues.
• Use this alongside get_campaign_performance to see how ad spend relates to total sales.
• Use parent_asin to pull units, revenue, and sessions for every child in a variation family in one call instead of querying each child ASIN separately.
• browser_sessions, mobile_app_sessions, browser_page_views, and mobile_app_page_views are summed over the window; the avg_*_pct columns are the average of the daily percentages, matching the avg_buy_box_pct convention.

Watch out

• Business Reports have a ~72 hour delay. For today's revenue, use get_todays_sales, which reads order data that lands well ahead of that.

Related tools

When to use

Evaluate ASIN-level SP + SD advertising efficiency by comparing directly attributable ad spend against total product revenue, not just ad-attributed revenue.

Tips

• Use this as an ASIN-level SP + SD metric, not as complete brand or account ad spend.
• Use group_by=parent_asin to think in products with size/color variations instead of per child ASIN.
• Set include_zero_sales=true when diagnosing a product whose sales dropped to zero, so an ASIN/parent with ad spend but no Business Report sales row still appears.
• Set channel_split=true to separate Sponsored Products from Sponsored Display spend and sales per ASIN.
• High ppc_pct (above 50%) means the ASIN has heavy product-attributed SP + SD sales share.
• Sort by organic_sales to find products that sell well without heavy ad support.
• Ad rows stop at the latest Business Report date in the requested window. organic_sales subtracts SP same-SKU and SD promoted-ASIN sales from total_sales; total_attributed_ad_sales separately preserves halo-inclusive attribution.
• Compare TACOS trends over time to track progress toward organic ranking.

Watch out

• Sponsored Brands and DSP spend are not included because this tool only returns deterministic ASIN-grain SP + SD spend. For Sponsored Brands, use get_sb_campaign_performance.
• Campaign-level SP or SD spend can differ from ASIN-grain spend when attribution cannot be tied cleanly to one promoted ASIN.
• group_by=parent_asin rolls SP/SD spend to the parent using the child-to-parent map from Business Reports; an advertised ASIN with no Business Report row is treated as its own parent.
• Business Reports have a ~72 hour delay, so TACOS for recent days will be incomplete.

Related tools

When to use

Inspect search volume, per-ASIN funnel (impression-share -> click-share -> purchase-share), and conversion-rate comparisons. Use funnel_stage to tell 'no impressions' apart from 'impressions but no clicks' for a query/ASIN.

Tips

• Sort by cr_delta descending to list keywords where your conversion rate is above the market rate.
• Use min_volume to filter out long-tail keywords and keep higher-traffic query rows.
• Compare asin_impression_share_pct vs asin_purchase_share_pct to find keywords where you convert above your visibility share.
• Use funnel_stage (no_impressions / impressions_no_clicks / clicks_no_cart_adds / cart_adds_no_purchases / converting) to diagnose where an ASIN drops off for a query without reading the raw counts.
• Positive cr_delta means your brand converts better than the market for that query.

Watch out

• SQP data is weekly granularity. Dates align to Sunday-through-Saturday weeks, not arbitrary ranges.

Related tools

When to use

Inspect whether SQP query rows have observed paid search-term evidence or matching configured keyword targets, with campaign and ad group locations.

Tips

• Coverage matching uses normalized text equality only: case and whitespace are normalized; punctuation, stemming, and singular/plural variants are not collapsed.
• paid_spend, paid_clicks, paid_sales, and paid_orders come from matching ads search-term rows where the observed customer search term equals the normalized SQP query.
• keyword_evidence rows show configured keyword/target matches and keyword state separately from observed search-term metrics.
• advertised_asin_match_method identifies the campaign/ad-group advertised-product map used to connect ads evidence to the SQP ASIN.

Watch out

• Broad or phrase keyword coverage is configured coverage evidence, not proof that every exact SQP query variation will trigger.
• A data_gap state means no ads search-term or keyword rows were observed for the selected ads scope and SQP week.

Related tools

When to use

Inspect Amazon-reported repeat-purchase behavior by product and compare complete report periods without treating aggregate Brand Analytics data as customer-level order identity.

Tips

• Use period=month for a stable six-month series or period=quarter for four complete calendar quarters.
• Filter by ASIN when comparing repeat-customer share and repeat-purchase revenue across periods for one product.
• Read the returned start_date, end_date, period, and snapshot_date fields rather than inferring report boundaries from the request date.

Watch out

• This is aggregate Amazon Brand Analytics data, not customer-level order identity.
• period=all mixes weekly, monthly, and quarterly rows whose date ranges overlap; use a specific period for a single-grain time series.

Related tools

When to use

Inspect the Amazon search funnel for one ASIN or compare ASINs across complete Brand Analytics report weeks.

Tips

• Read start_date and end_date on each row; Brand Analytics periods are complete Sunday-Saturday weeks.
• Use min_impressions or min_clicks to keep broad ASIN comparisons bounded.
• The response flattens Amazon’s nested impression, click, cart-add, and purchase records without adding a score or prescribed action.

Watch out

• Search-attributed sales and conversion rate are Amazon report fields. They are not advertising-attribution metrics such as ACOS or ROAS.

Related tools

When to use

Read which ASIN pairs Amazon observed in the same market basket for a complete report week, including their source rank and combination percentage.

Tips

• Filter primary_asin to read the paired rows Amazon reported for one product.
• Use max_rank or min_combination_pct to bound a broad pair query.
• Treat each row as a directional primary-ASIN to paired-ASIN observation for the stated report week.

Watch out

• The tool returns pair facts only. It does not call a pair an opportunity or recommend a cross-sell.

Related tools

When to use

Read marketplace search-frequency ranks and Amazon-reported clicked-product shares without scanning the multi-gigabyte raw Search Terms report.

Tips

• Use top_terms for bounded ranked discovery, term_products with one exact term, and asin_terms with one exact ASIN.
• Keep explicit report-week dates when comparing results; the serving layer retains the most recent 42 days.
• Click share, conversion share, and search-frequency rank are Amazon report fields, not agentcentral scores.

Watch out

• A tenant can return serving_layer_not_available until a successful weekly Brand Analytics Search Terms refresh materializes its bounded serving tables.

Related tools

When to use

Use this to understand whether a brand is gaining category awareness, converting consideration into purchases, and acquiring new-to-brand customers compared with category peers.

Tips

• Compare customer_conversion_rate_vs_median to see where the brand converts better or worse than category peers.
• Use category_path with wildcards to isolate a category family.
• Track awareness_index, consideration_index, and sales_index over weekly computation dates.

Watch out

• Brand Metrics requires Amazon Ads Brand Metrics availability for the advertiser and category, so some profiles may return no rows.

Related tools

When to use

Assess category share-of-voice and engagement strength, including branded searches, detail page views, add-to-carts, and brand-customer counts versus category peers.

Tips

• Sort by awareness_index to find the strongest category visibility positions.
• Use branded_searches_vs_median, viewed_detail_page_vs_median, and add_to_carts_vs_median to separate brand search demand from shopping engagement.
• Compare consideration_index and sales_index to find categories where shoppers consider the brand but do not convert into sales.

Watch out

• Share-of-voice fields are Brand Metrics benchmarks, not ad-attributed campaign metrics. Use campaign tools for paid media spend and ACOS.

Related tools

When to use

Use this to measure how non-Amazon channels such as Google Ads, Facebook, Microsoft Ads, publishers, and creators drive shopping actions on Amazon through Attribution tags.

Tips

• Filter publisher to compare paid social, search, creator, and affiliate traffic.
• Use report_type=PRODUCTS when you need ASIN-level brand halo and new-to-brand attribution.
• Sort by purchase_rate to find efficient off-Amazon traffic sources, not just high-volume channels.

Watch out

• Amazon Attribution requires Attribution setup and eligible advertiser access. Profiles without Attribution advertisers can have no rows even when regular ads reporting works.

Related tools

When to use

Evaluate Sponsored Brands campaigns for brand awareness impact, new customer acquisition, and video engagement.

Tips

• Track ntb_orders (new-to-brand orders) to measure customer acquisition, not just revenue.
• branded_searches indicates how much brand awareness the campaign is driving.
• video_completes helps evaluate whether video creative is engaging enough.

Watch out

• SB campaigns lack per-ASIN attribution, so they are excluded from TACOS calculations.
• Ads data has a 3-day attribution lag. Recent days will show incomplete metrics.

Related tools

When to use

Evaluate Sponsored Display campaigns for retargeting effectiveness, viewability, and new customer reach.

Tips

• Low avg_viewability (below 40%) suggests your display placements are below the fold or in poor positions.
• Compare dpv (detail page views) against clicks to measure product page engagement.
• SD data is included in TACOS calculations, unlike SB data.

Watch out

• Ads data has a 3-day attribution lag. Recent days will show incomplete metrics.

Related tools

When to use

Use this when an agent needs SB/SD report views that do not have narrow tools yet, or when it needs a consistent cross-product report query for campaigns, ads, advertised products, search terms, targeting, purchased products, placements, or invalid traffic.

Tips

• Start with ad_product=SB and report_view=search_terms or targeting to inspect Sponsored Brands detail that was previously ingested but not exposed.
• ad_product=SB with report_view=targeting returns the retained keyword_bid alongside keyword text and match type, sortable by keyword_bid, for a warehouse-backed view of Sponsored Brands keyword bids.
• Use report_view=invalid_traffic to compare gross and invalid impressions/clicks across SP, SB, and SD.
• For common Sponsored Products campaign, ad group, keyword, search-term, product, or placement workflows, prefer the narrower SP tools when they give the agent a clearer schema.
• Use report_view=ad_groups or report_view=ads when you need a compact rollup before drilling into advertised products, search terms, or targets.

Watch out

• This is a retained reporting tool, not a live Ads API management surface.
• Not every report_view exists for every ad_product; unsupported combinations return structured metadata with supported views.
• Some ad_group and ads views are derived rollups over the closest retained Amazon report table rather than separate source report tables.
• Ads data has a 3-day attribution lag. Recent days will show incomplete metrics.

Related tools

When to use

Use this to evaluate programmatic display and video campaigns at the order, line item, and creative level.

Tips

• Sort by video_completions or video_completion_rate to compare video creative engagement.
• Use min_spend to return DSP rows with enough spend volume for stable comparisons.
• Compare viewability_rate against ROAS to separate media quality issues from conversion issues.

Watch out

• DSP rows appear only for Amazon Ads accounts with manager-account access to DSP advertisers.

Related tools

When to use

Use this to understand how shoppers move through Brand Stores by date, store, page, traffic source, or source tag, and which Store pages or traffic sources drive sales.

Tips

• Use dimension=page to find Store pages that get traffic but do not convert.
• Use dimension=source to compare Sponsored Brands, organic, and other Store traffic.
• Use dimension=tag to evaluate external links created with Store source tags.

Watch out

• Brand Store insights only appear for advertisers with Brand Stores available to the Ads profile.
• Visitors and new_to_store are store-level/date metrics; page, source, and tag breakdowns may return zero for those columns.

Related tools

When to use

Use this when you manage budgets or goals by portfolio and need one row per portfolio instead of one row per campaign.

Tips

• Sort by spend to find the portfolios using the most budget.
• Filter portfolio_id=unassigned to return campaigns without a portfolio assignment.
• Use this before changing budgets when a seller allocates spend by portfolio rather than individual campaign.

Watch out

• Portfolio assignment comes from the latest campaign snapshot at or before the query end date, so historical performance is grouped by that snapshot assignment.

Related tools

When to use

When SP, SB, or SD performance changed (ACOS spiked, sales dropped, spend increased) and you need to pinpoint which product-appropriate campaigns, ads, search terms, targets, or advertised products drove the change.

Tips

• Use equal-length periods for fair comparison (e.g. 30 days vs prior 30 days).
• Start with focus_metric=acos, then follow up with spend or sales for deeper analysis.
• Use ad_product=SB to compare campaign, ad, search-term, and targeting movers; use ad_product=SD to compare campaign, advertised-product, and targeting movers.
• The output ranks top movers by absolute change, making it easy to spot the biggest contributors.

Watch out

• Ads data has a 3-day attribution lag. Avoid including the last 3 days in your comparison window.
• SP, SB, and SD do not expose identical dimensions; the tool uses product-appropriate sections rather than forcing one shared schema.

Related tools

When to use

Inspect current campaign budget consumption or compare the latest retained capture across marketplace-local days.

Tips

• Use ad_product=ALL to compare Sponsored Products, Sponsored Brands, and Sponsored Display.
• Check captured_at and usage_updated_at before treating a row as current.
• Use campaign performance reports when you need finalized advertising spend.
• When a campaign-name filter matches nothing, diagnostics distinguish a name miss from an account with no scoped pacing rows.

Watch out

• budget_used_amount is derived from Amazon budget and usage percentage; it is an estimate, not finalized report spend. Retention keeps the latest capture for each marketplace-local day, not every intraday poll.

Related tools

When to use

Use this source-surface tool for tracked keyword rank snapshots, deterministic rank deltas, or rank rows joined to the SQP week containing the snapshot date.

Tips

• Use view="positions" with start_date/end_date for raw rank snapshots.
• Use view="changes" with current_date and compare_date for deterministic rank deltas.
• Use view="with_volume" with snapshot_date to join rank rows to SQP weekly volume/share data.

Watch out

• Rank snapshot frequency varies by plan, so read snapshot_date rather than assuming a fixed interval. view="with_volume" joins snapshot_date to the SQP week containing that date. For real-time rank checks, use get_current_rank.

Related tools

When to use

Use this when an agent needs promotion campaign results: how many shoppers clipped or redeemed a coupon, how much of a coupon budget is spent, which coupons or deals are still running, whether Amazon canceled or ended a deal, or the ASINs a promotion covered. Coupon and deal stats are cumulative lifetime values refreshed daily from Amazon’s GET_COUPON_PERFORMANCE_REPORT and GET_PROMOTION_PERFORMANCE_REPORT.

Tips

• Coupon stats are cumulative lifetime values per coupon, refreshed daily; budget_percentage_used shows how much of the coupon budget is consumed.
• Filter by asin to find which coupons cover a product or which deals include it.
• Filter by status (view=deal) to separate scheduled, running, ended, and canceled deals; Amazon-reported status is factual lifecycle state, not a recommendation.

Watch out

• Both views are rolling 90-day start windows, so promotions that started more than 90 days ago are not present. The diagnostics note’s min..max span is the earliest and latest observed promotion start dates in the synced table, not a retention or availability boundary. start_datetime and end_datetime are each promotion’s real start/end from the Amazon report (startDateTime/endDateTime); use report_window_start/report_window_end for the synced window dates. Seller-visible deal types are Best Deal and Lightning Deal only (Price Discount is vendor-only). Brand Tailored Promotions have no API and never appear here; Amazon Ads audience targeting is the programmatic route to the same shopper segments.

Related tools

When to use

Preview or submit explicit keyword bid values after the caller has selected keyword IDs and target bids.

Tips

• Always check current bids with get_keyword_performance before making changes.
• Use get_bid_recommendations to get Amazon suggested bids as a baseline.
• Changes exceeding 500% of the current bid will trigger a warning in the response.
• The tool pre-reads current bids automatically, so the response shows before and after values.

Watch out

• Minimum bid is $0.02 and maximum is $100. Bids outside this range will be rejected.
• This tool updates Sponsored Products keyword bids. Use update_target_bids for ASIN product targets, category targets, and auto targets.

Related tools

When to use

Preview or submit explicit bid values after the caller has selected Sponsored Products target IDs for ASIN PATs, category targets, or auto targeting clauses.

Tips

• Use get_keyword_performance to find target rows. For rows where keyword_type is TARGETING_EXPRESSION or TARGETING_EXPRESSION_PREDEFINED, the target ID currently appears in keyword_id.
• The tool pre-reads /sp/targets/list and returns campaign_id, ad_group_id, state, expression_type, and targeting summary when Amazon returns them.
• Changes exceeding 500% of the current bid will trigger a warning in the response.
• The default response is a preview; submit requires confirm=true and an idempotency_key.

Watch out

• Minimum bid is $0.02 and maximum is $100. Bids outside this range will be rejected.
• Keyword bids and target bids use separate Amazon Ads endpoints: /sp/keywords for keywords and /sp/targets for targeting clauses.

Related tools

When to use

Submit explicit keyword state changes after the caller has selected keyword IDs and target states.

Tips

• Use get_keyword_performance or get_search_terms to identify the keyword IDs before submitting state changes.
• The response shows old_state and new_state for each keyword ID.
• PAUSED keywords retain settings and can be re-enabled later.

Watch out

• Archiving is not exposed through this state update tool because the current Amazon Ads update endpoint rejects ARCHIVED.

Related tools

When to use

Submit keyword archives after the caller has selected keyword IDs and explicitly acknowledged the irreversible archive operation.

Tips

• The default response is a preview with current keyword state; no archive call is made unless confirm=true.
• The submit path requires both idempotency_key and archive_acknowledgement=true.
• Use update_keyword_state for ENABLED, PAUSED, and PROPOSED state changes.

Watch out

• Archived keywords cannot be re-enabled through the state update endpoint.

Related tools

When to use

Change the default bid for an entire ad group when you want to adjust bid levels across all keywords in that group at once.

Tips

• The ad group default bid applies to new keywords and keywords without individual bids.
• Keywords with individual bids are not affected by ad group bid changes.
• Use get_adgroup_performance to review current ad group spend, ACOS, and ROAS before changing bids.

Watch out

• Minimum bid is $0.02 and maximum is $100. Changes exceeding 500% trigger a warning.

Related tools

When to use

Increase or decrease bid multipliers for specific placements after analyzing placement performance data.

Tips

• Use get_placement_breakdown to inspect placement-level conversion metrics for this campaign.
• A percentage of 50 means bids are increased by 50% for that placement. 0 means no adjustment.
• Top of Search placements typically convert best but cost more.

Related tools

When to use

Submit explicit audience bid adjustment values after the caller has selected campaign IDs, audience IDs, source type, and percentage.

Tips

• Use get_audience_segments to inspect available audience IDs before setting an adjustment.
• BEHAVIOR_DYNAMIC is used for Amazon-built audiences; SPONSORED_ADS_AMC is used for AMC custom audiences.
• Amazon currently allows one audience bid adjustment on a campaign; setting a new one replaces the campaign-level audience adjustment payload.

Watch out

• REMOVE clears the campaign audience bid adjustment by sending an empty adjustment list.

Related tools

When to use

Set explicit Amazon-documented Off-Amazon campaign settings after the caller has supplied the complete target object.

Tips

• Run the default preview first; it returns the current object and the exact replacement object without writing.
• Use only fields and values documented by Amazon for the campaign’s marketplace and current API version.
• A confirmed submit requires confirm=true plus an idempotency_key. Success is reported only after the live readback matches the requested object.

Watch out

• This tool is for Sponsored Products campaigns. It does not manage Sponsored Brands or Sponsored Display settings.
• The object is sent as a complete verbatim value, not merged field by field. Omitted fields are not inferred.

Related tools

When to use

Submit a daily budget value for a Sponsored Products campaign after the caller has decided the target budget.

Tips

• Use get_budget_recommendations to inspect Amazon suggested budget fields alongside missed impressions, clicks, and sales.
• Use get_campaign_performance to inspect ROAS, ACOS, spend, and sales before submitting a budget value.
• The response shows the old and new budget values plus the percentage change.

Watch out

• Budget changes exceeding 500% of the current budget trigger a warning.

Related tools

When to use

Submit ENABLED, PAUSED, or PROPOSED state updates for Sponsored Products campaigns.

Tips

• PAUSED campaigns retain all settings and can be re-enabled later.
• Use get_campaign_performance to inspect ACOS, ROAS, spend, and sales before submitting state updates.
• PAUSED campaigns can be re-enabled later.

Watch out

• Archiving is not exposed through this state update tool because the current Amazon Ads update endpoint rejects ARCHIVED.

Related tools

When to use

Submit campaign archives after the caller has selected campaign IDs and explicitly acknowledged the irreversible archive operation.

Tips

• The default response is a preview with current campaign state; no archive call is made unless confirm=true.
• The submit path requires both idempotency_key and archive_acknowledgement=true.
• Use update_campaign_state for ENABLED, PAUSED, and PROPOSED state changes.

Watch out

• Archived campaigns cannot be re-enabled through the state update endpoint.

Related tools

When to use

Create Sponsored Brands campaign shells after the caller has selected campaign name, budget, dates, cost type, and initial state.

Tips

• Preview first; no Amazon write occurs unless confirm=true.
• Submit requires confirm=true and an idempotency_key.
• Budget values use marketplace currency guardrails.

Watch out

• This creates campaign structure only; agentcentral does not generate brand, budget, or creative recommendations.

Related tools

When to use

Change budgets for existing Sponsored Brands campaigns selected by campaign ID.

Tips

• Preview first to inspect current campaign state and budget where Amazon returns it.
• Submit requires confirm=true and an idempotency_key.
• Budget guardrails block obvious typo values before Amazon writes.

Related tools

When to use

Pause or re-enable Sponsored Brands campaigns without archiving them.

Tips

• Preview first to inspect current campaign state.
• Submit requires confirm=true and an idempotency_key.
• Use archive_sb_campaigns only when the user confirms permanent archive.

Watch out

• This tool intentionally does not expose ARCHIVED; archive is permanent and uses archive_sb_campaigns.

Related tools

When to use

Archive selected Sponsored Brands campaigns after explicit user acknowledgement.

Tips

• Preview pre-reads current campaign state.
• Submit requires confirm=true, idempotency_key, and archive_acknowledgement=true.
• Use update_sb_campaign_state for reversible pause/enable changes.

Watch out

• Amazon Common Campaign Management defines archive/delete as a terminal operation that cannot be reactivated through state update.

Related tools

When to use

Create Sponsored Brands ad groups under selected campaign IDs after the caller has selected names and initial state.

Tips

• Preview first; no Amazon write occurs unless confirm=true.
• Submit requires confirm=true and an idempotency_key.
• No public ad-group bid field is exposed in this tool.

Watch out

• No update_sb_ad_group_bid tool is exposed because the public proof did not pin a safe ad-group bid write field.

Related tools

When to use

Pause or re-enable Sponsored Brands ad groups without archiving them.

Tips

• Preview pre-reads current ad group state.
• Submit requires confirm=true and an idempotency_key.
• Use archive_sb_ad_groups only for permanent archive operations.

Related tools

When to use

Archive selected Sponsored Brands ad groups after explicit user acknowledgement.

Tips

• Preview pre-reads current ad group state.
• Submit requires confirm=true, idempotency_key, and archive_acknowledgement=true.
• Use update_sb_ad_group_state for reversible pause/enable changes.

Watch out

• Amazon Common Campaign Management defines archive/delete as a terminal operation that cannot be reactivated through state update.

Related tools

When to use

Create Sponsored Brands ads under selected ad group IDs after the caller supplies the documented creative payload.

Tips

• Preview first; no Amazon write occurs unless confirm=true.
• Submit requires confirm=true and an idempotency_key.
• The creative object is passed to Amazon as caller-supplied structured data.

Watch out

• agentcentral does not generate or recommend ad creative; the caller must provide the documented creative object.

Related tools

When to use

Pause or re-enable Sponsored Brands ads without archiving them.

Tips

• Preview pre-reads current ad state.
• Submit requires confirm=true and an idempotency_key.
• Use archive_sb_ads only for permanent archive operations.

Related tools

When to use

Archive selected Sponsored Brands ads after explicit user acknowledgement.

Tips

• Preview pre-reads current ad state.
• Submit requires confirm=true, idempotency_key, and archive_acknowledgement=true.
• Use update_sb_ad_state for reversible pause/enable changes.

Watch out

• Amazon Common Campaign Management defines archive/delete as a terminal operation that cannot be reactivated through state update.

Related tools

When to use

Create Sponsored Brands keyword, product, category, or theme targets after the caller has selected ad group IDs and target details.

Tips

• Preview first; no Amazon write occurs unless confirm=true.
• Submit requires confirm=true and an idempotency_key.
• Bid values are checked against marketplace bid guardrails.

Watch out

• This tool does not create campaigns, ad groups, ads, or creatives. It only creates targeting rows.

Related tools

When to use

Update bids for existing non-negative Sponsored Brands targets after selecting target IDs.

Tips

• Preview pre-reads current target state/bid.
• Submit requires confirm=true and an idempotency_key.
• Optimization rules can make some Amazon bid updates fail; failures are returned row-by-row from Amazon.

Related tools

When to use

Pause or re-enable existing non-negative Sponsored Brands targets without archiving them.

Tips

• Preview pre-reads current target state.
• Submit requires confirm=true and an idempotency_key.
• Use archive_sb_targets only for permanent archive operations.

Related tools

When to use

Archive selected non-negative Sponsored Brands targets after explicit user acknowledgement.

Tips

• Preview pre-reads current target state.
• Submit requires confirm=true, idempotency_key, and archive_acknowledgement=true.
• Use update_sb_target_state for reversible pause/enable changes.

Watch out

• Amazon Common Campaign Management defines ARCHIVED as a terminal state that cannot be reactivated.

Related tools

When to use

Create Sponsored Brands negative keyword, product, or category targets selected by the caller. Sponsored Brands negative keywords are created here with target_type=keyword.

Tips

• Preview first; no Amazon write occurs unless confirm=true.
• Submit requires confirm=true and an idempotency_key.
• Negative target creation does not accept bid fields.
• For negative keywords, use target_type=keyword. Read existing SB negatives first with get_sponsored_ads_entities_live (ad_product=SB, entity_type=negative_target) and harvest candidates from get_search_terms (ad_product=SB).

Related tools

When to use

Pause or re-enable existing Sponsored Brands negative targets without archiving them.

Tips

• Preview pre-reads current negative target state.
• Submit requires confirm=true and an idempotency_key.
• Use archive_sb_negative_targets only for permanent archive operations.

Related tools

When to use

Archive selected Sponsored Brands negative targets after explicit user acknowledgement.

Tips

• Preview pre-reads current negative target state.
• Submit requires confirm=true, idempotency_key, and archive_acknowledgement=true.
• Use update_sb_negative_target_state for reversible pause/enable changes.

Watch out

• Amazon Common Campaign Management defines ARCHIVED as a terminal state that cannot be reactivated.

Related tools

When to use

Create Sponsored Display campaign shells after the caller has selected names, tactic, start date, budget, cost type, and initial state.

Tips

• Preview first; no Amazon write occurs unless confirm=true.
• Submit requires confirm=true and an idempotency_key.
• When state is omitted, the tool prepares a paused campaign unless the caller explicitly selected enabled.

Watch out

• Only Amazon-source response rows are returned; agentcentral does not recommend tactics, budgets, or next actions.

Related tools

When to use

Change daily budgets for existing Sponsored Display campaigns selected by ID.

Tips

• Preview first to inspect the pre-read campaign row.
• Submit requires confirm=true and an idempotency_key.
• Budget guardrails block obvious typo values before Amazon writes.

Related tools

When to use

Pause or re-enable Sponsored Display campaigns without archiving them.

Tips

• Preview first to inspect current campaign state.
• Submit requires confirm=true and an idempotency_key.
• Use archive_sd_campaigns only when the user confirms permanent archive.

Watch out

• This tool intentionally does not expose archived; archive is permanent and uses archive_sd_campaigns.

Related tools

When to use

Submit Sponsored Display campaign archives after the caller has selected SD campaign IDs and explicitly acknowledged the irreversible archive operation.

Tips

• The default response is a preview with current Sponsored Display campaign state; no archive call is made unless confirm=true.
• The submit path requires confirm=true, idempotency_key, and archive_acknowledgement=true.
• Use get_sponsored_ads_entities_live with ad_product=SD and entity_type=campaign to inspect live SD campaign IDs before archiving.

Watch out

• Amazon documents this DELETE endpoint as setting status/state to archived; it is not a reversible pause operation.

Related tools

When to use

Create Sponsored Display ad groups after the caller has selected a campaign ID, name, default bid, and initial state.

Tips

• Preview first; no Amazon write occurs unless confirm=true.
• Submit requires confirm=true and an idempotency_key.
• Default bids use marketplace currency guardrails.

Related tools

When to use

Change default bids for existing Sponsored Display ad groups selected by ID.

Tips

• Preview first to inspect the pre-read ad group row.
• Submit requires confirm=true and an idempotency_key.
• Bid guardrails block obvious typo values before Amazon writes.

Related tools

When to use

Pause or re-enable Sponsored Display ad groups without archiving them.

Tips

• Preview first to inspect current ad group state.
• Submit requires confirm=true and an idempotency_key.
• Use archive_sd_ad_groups only for permanent archive operations.

Watch out

• This tool intentionally does not expose archived; archive is permanent and uses archive_sd_ad_groups.

Related tools

When to use

Submit Sponsored Display ad group archives after the caller has selected SD ad group IDs and explicitly acknowledged the irreversible archive operation.

Tips

• Preview first to inspect current ad group state.
• Submit requires confirm=true, idempotency_key, and archive_acknowledgement=true.
• Use get_sponsored_ads_entities_live with ad_product=SD and entity_type=ad_group to inspect IDs.

Watch out

• Amazon documents this DELETE endpoint as setting state/status to archived; it is not a reversible pause operation.

Related tools

When to use

Create Sponsored Display product ads after the caller has selected campaign, ad group, SKU or ASIN, and initial state.

Tips

• Preview first; no Amazon write occurs unless confirm=true.
• Submit requires confirm=true and an idempotency_key.
• Use get_ad_eligibility before creating ads for new ASINs.

Related tools

When to use

Pause or re-enable Sponsored Display product ads without archiving them.

Tips

• Preview first to inspect current product ad state.
• Submit requires confirm=true and an idempotency_key.
• Use archive_sd_product_ads only for permanent archive operations.

Watch out

• This tool intentionally does not expose archived; archive is permanent and uses archive_sd_product_ads.

Related tools

When to use

Submit Sponsored Display product ad archives after the caller has selected SD ad IDs and explicitly acknowledged the irreversible archive operation.

Tips

• Preview first to inspect current product ad state.
• Submit requires confirm=true, idempotency_key, and archive_acknowledgement=true.
• Use get_sponsored_ads_entities_live with ad_product=SD and entity_type=product_ad to inspect IDs.

Watch out

• Amazon documents this DELETE endpoint as setting state/status to archived; it is not a reversible pause operation.

Related tools

When to use

Create Sponsored Display targeting clauses after the caller has selected an ad group, expression type, expression predicates, optional bid, and initial state.

Tips

• Preview first; no Amazon write occurs unless confirm=true.
• Submit requires confirm=true and an idempotency_key.
• Use get_sponsored_ads_targeting_options to fetch Amazon-source targeting and bid fields before the caller chooses values.

Watch out

• Expressions are passed through as Amazon-documented predicate objects; agentcentral does not invent targeting recommendations.

Related tools

When to use

Submit Sponsored Display target bid changes after the caller has selected exact SD target IDs and bid values.

Tips

• Preview first to inspect current target state and bid.
• Submit requires confirm=true and an idempotency_key.
• Use get_sponsored_ads_entities_live with ad_product=SD and entity_type=target to inspect IDs.

Watch out

• Amazon documents bid as mutable only when the target's ad group does not have an enabled optimization rule.

Related tools

When to use

Pause or re-enable Sponsored Display targets without archiving them.

Tips

• Preview first to inspect current target state.
• Submit requires confirm=true and an idempotency_key.
• Use archive_sd_targets only for permanent archive operations.

Watch out

• This tool intentionally does not expose archived; archive is permanent and requires archive_sd_targets with archive_acknowledgement=true.

Related tools

When to use

Submit Sponsored Display target archives after the caller has selected SD target IDs and explicitly acknowledged the irreversible archive operation.

Tips

• Preview first to inspect current target state.
• Submit requires confirm=true, idempotency_key, and archive_acknowledgement=true.
• Use get_sponsored_ads_entities_live with ad_product=SD and entity_type=target to inspect IDs.

Watch out

• Use update_sd_target_state for reversible pause/enable flows; archive is permanent.

Related tools

When to use

Create Sponsored Display negative targeting clauses after the caller has selected ad group IDs and Amazon-documented negative expression predicates.

Tips

• Preview first; no Amazon write occurs unless confirm=true.
• Submit requires confirm=true and an idempotency_key.
• Amazon documents negative predicates such as asinSameAs and asinBrandSameAs.

Related tools

When to use

Pause or re-enable Sponsored Display negative targets without archiving them.

Tips

• Preview first to inspect current negative target state.
• Submit requires confirm=true and an idempotency_key.
• Use archive_sd_negative_targets only for permanent archive operations.

Watch out

• This tool intentionally does not expose archived; archive is permanent and uses archive_sd_negative_targets.

Related tools

When to use

Submit Sponsored Display negative target archives after the caller has selected SD negative target IDs and explicitly acknowledged the irreversible archive operation.

Tips

• Preview first to inspect current negative target state.
• Submit requires confirm=true, idempotency_key, and archive_acknowledgement=true.
• Use get_sponsored_ads_entities_live with ad_product=SD and entity_type=negative_target to inspect IDs.

Watch out

• Use update_sd_negative_target_state for reversible pause/enable flows; archive is permanent.

Related tools

When to use

Submit keyword creations when the caller has selected campaign IDs, ad group IDs, match types, and bid values.

Tips

• Use get_search_terms to inspect customer search terms and matched targeting before creating keyword records.
• Use get_bid_recommendations to inspect Amazon suggested bid fields for the selected keyword context.
• Use create_negative_keywords separately when the caller has selected negative keyword records to submit.

Watch out

• Amazon keyword text accepts letters, numbers, spaces, and . - + only; characters such as % or " return a per-row malformedValueError. Preview flags likely-unsupported characters as a non-blocking warning.

Related tools

When to use

Submit campaign-level or ad-group-level negative keyword records selected by the caller.

Tips

• Use get_search_terms sorted by spend to inspect high-spend zero-sale search terms.
• Campaign-level negatives (no ad_group_id) block the term across all ad groups in that campaign.
• Use NEGATIVE_EXACT when you want to block only the exact phrase, and NEGATIVE_PHRASE to block any query containing that phrase.

Watch out

• Amazon keyword text accepts letters, numbers, spaces, and . - + only; characters such as % or " return a per-row malformedValueError. Preview flags likely-unsupported characters as a non-blocking warning.

Related tools

When to use

Create Sponsored Products campaign shells after the caller has selected names, targeting type, daily budgets, and bidding strategy.

Tips

• Default to PAUSED for safer agent launch workflows.
• Use get_budget_recommendations only as Amazon-source context; users still choose the submitted budget.

Related tools

When to use

Create ad groups inside existing Sponsored Products campaigns after campaign IDs and default bids are selected.

Tips

• The tool pre-reads campaign state for context.
• Default state is PAUSED unless explicitly enabled.

Related tools

When to use

Attach advertised SKUs or ASINs to Sponsored Products ad groups before creating keywords or targets.

Tips

• Use get_ad_eligibility before creating product ads for new ASINs.
• Default state is PAUSED unless explicitly enabled.

Related tools

When to use

Pause, enable, or archive Sponsored Products ad groups or product ads after selecting IDs from live entity lookup.

Tips

• Use get_sp_entities_live with entity_type=ad_group or product_ad to fetch IDs first.
• Complete state preview: {"profile_id":"PROFILE_ID","entity_type":"ad_group","operation":"set_state","updates":[{"id":"222","state":"PAUSED"}],"confirm":false}.
• For a confirmed archive, use operation=archive with updates=[{"id":"222"}], confirm=true, an idempotency_key, and archive_acknowledgement=true.
• Use set_state to pause before using irreversible archive.

Watch out

• Archive uses Amazon delete endpoints and is irreversible; preview mode is the default.

Related tools

When to use

Create explicit Sponsored Products targets after the caller has selected campaign/ad group IDs, expression predicates, and bids.

Tips

• Use get_sp_targeting_options to fetch Amazon-source ASIN/category/refinement options.
• Use target_type=expression for advanced Amazon-documented predicates only.

Related tools

When to use

Pause, enable, or propose existing Sponsored Products targets without changing their bids.

Tips

• Use get_sp_entities_live with entity_type=target to pre-check current state.
• Use update_target_bids for bid changes.

Related tools

When to use

Irreversibly archive selected Sponsored Products targets after explicit user acknowledgement.

Tips

• Archive is irreversible; use update_sp_target_state to pause reversible targets.
• The tool pre-reads target details for audit context.

Watch out

• Amazon exposes archive through a delete endpoint; agentcentral presents it as archive.

Related tools

When to use

Add ad-group-level or campaign-level negative product/brand targets selected by the caller.

Tips

• Use get_sp_targeting_options with negative brand search before creating brand negatives.
• Use campaign scope when the exclusion should apply across ad groups.

Related tools

When to use

Pause or re-enable existing ad-group-level or campaign-level negative keywords after selecting IDs from live entity lookup.

Tips

• Use get_sp_entities_live with entity_type=negative_keyword to list IDs first.
• Submit requires confirm=true and an idempotency_key.
• Use archive_sp_negative_keywords only for permanent archive operations.

Related tools

When to use

Archive selected ad-group-level or campaign-level negative keywords after the caller explicitly acknowledges the irreversible archive operation.

Tips

• Preview first to inspect current state.
• Submit requires confirm=true, idempotency_key, and archive_acknowledgement=true.
• Use update_sp_negative_keyword_state for reversible pause/enable changes.

Watch out

• Amazon exposes archive through delete endpoints; agentcentral presents it as archive.

Related tools

When to use

Pause or re-enable existing ad-group-level or campaign-level negative targets without archiving them.

Tips

• Use get_sp_entities_live with entity_type=negative_target to list IDs first.
• Submit requires confirm=true and an idempotency_key.
• Use archive_sp_negative_targets only for permanent archive operations.

Related tools

When to use

Archive selected ad-group-level or campaign-level negative targets after the caller explicitly acknowledges the irreversible archive operation.

Tips

• Preview first to inspect current state.
• Submit requires confirm=true, idempotency_key, and archive_acknowledgement=true.
• Use update_sp_negative_target_state for reversible pause/enable changes.

Watch out

• Amazon exposes archive through delete endpoints; agentcentral presents it as archive.

Related tools

When to use

Use this before DSP campaign, ad group, target, or creative reads when you need to discover which DSP advertiser IDs the Ads profile can access.

Tips

• Use the returned DSP advertiser ID as amazon_ads_account_id when calling get_dsp_entities_live.
• Pair this with get_dsp_performance to connect retained DSP Reporting v3 rows to advertiser names and IDs.

Watch out

• This is a live advertiser discovery read only. Accessible advertisers depend on the Ads profile and token permissions.

Related tools

When to use

Use this when you need current DSP campaign/order, ad group/line-item, or target state directly from Amazon rather than retained reporting rows.

Tips

• Call get_dsp_advertisers_live first and pass the advertiserId as amazon_ads_account_id.
• Use entity_type="campaign" for DSP orders and entity_type="ad_group" for DSP line items; Amazon renamed those objects in DSP v1.
• Use next_token for pagination instead of increasing max_results beyond the bounded 100-row request cap.

Watch out

• DSP target reads require target_ids or ad_group_ids and may also use states and target_types filters; campaign_ids are not sent for targets because Amazon does not document that filter. Campaign/ad-group state filters are also rejected instead of guessed.

Related tools

When to use

Use before writes when stored data may lag or when an agent needs current Amazon entity IDs and states.

Tips

• Use this as the live pre-read surface for Sponsored Products management tools.
• For negative entities, scope can distinguish ad-group-level and campaign-level records.

Watch out

• This is a live Amazon Ads API call; keep filters narrow.

Related tools

When to use

Use when an agent needs current Amazon entity IDs, states, budgets, bids, moderation/serving fields, or readback context across SP/SB/SD without waiting for warehouse snapshots.

Tips

• Unsupported product/entity pairs return structured diagnostics and make no Amazon API call.
• Use SP-specific filters such as text_query, asins, expression_types, and match_types only with Sponsored Products entity families.
• Sponsored Brands keywords and their bids read with entity_type=target (or entity_type=keyword for KEYWORD targets only); the returned target_id works with update_sb_target_bids and archive_sb_targets.
• Read existing Sponsored Brands negatives with entity_type=negative_target (or negative_keyword) before creating new ones.
• Results are Amazon-source fields; agentcentral does not add recommended next actions.

Watch out

• SB uses token pagination and vendor media types; SD uses offset pagination with JSON GET endpoints. Keep filters narrow for live calls.
• Sponsored Brands targets come from Common Campaign Management; the bid is flattened to a number and keyword text/match type are surfaced alongside the raw Amazon row.

Related tools

When to use

Discover Amazon-provided keyword, product, category, and brand targeting inputs before explicit user-approved target creation.

Tips

• Results are Amazon-source fields, not agentcentral-authored recommendations.
• Use returned category/brand IDs in create_sp_targets or create_sp_negative_targets.

Watch out

• Endpoint availability and fields vary by marketplace and profile.

Related tools

When to use

Use when an agent needs one cross-product read surface for Amazon-provided targeting candidates, category/refinement metadata, product counts, or bid option fields before any explicit write workflow.

Tips

• For Sponsored Brands suggested bids, call with ad_product=SB, option_type=bid_recommendations, and landing_pages=[{asins:[...]}]. Amazon returns a campaign-level suggested CPC (minimumValue and recommendedValue), not per-keyword bids.
• Unsupported or ambiguous SB keyword/audience endpoints return diagnostics and make no Amazon call; AMC is out of scope.
• Use request_body when you need the exact Amazon schema for SD target or bid recommendations.
• Results are Amazon-source fields only; agentcentral does not add opportunity ranks or recommended next actions.

Watch out

• This is a live Amazon Ads API surface. Endpoint support and returned fields vary by ad product, marketplace, and account permissions.

Related tools

When to use

Get Amazon suggested Sponsored Products bid ranges before creating new keywords or adjusting existing bids, using either a planned ASIN set or an existing ad group as the auction context.

Tips

• The suggested_bid, range_low, and range_high values are returned by Amazon for the chosen campaign or ASIN context.
• The theme column preserves Amazon recommendation theme labels when returned by the API.
• Use keyword_performance separately when comparing Amazon suggested bid fields to historical seller performance.

Watch out

• This is a live API call with rate limiting. Avoid calling in tight loops.
• Amazon requires either ASIN context for a new ad group or campaign_id + ad_group_id for an existing ad group.
• Sponsored Brands has no per-keyword bid recommendation endpoint; use get_sponsored_ads_targeting_options (ad_product=SB, option_type=bid_recommendations, landing_pages) for the SB campaign-level suggested CPC.

Related tools

When to use

Return Amazon suggested budget levels and seven-day missed-impression, missed-click, and missed-sales fields for selected campaigns.

Tips

• High missed_impressions and missed_clicks indicate Amazon estimated delivery constrained by budget.
• Compare suggested_budget against current budget to quantify the difference between current and Amazon-suggested budget values.
• Use get_campaign_performance separately to inspect ROAS, ACOS, spend, and sales for the same campaigns.

Watch out

• This is a live API call with rate limiting. Avoid calling in tight loops.
• Amazon may return per-campaign errors in the same response when some campaign IDs are invalid or unavailable.

Related tools