Amazon Catalog MCP Tool Reference

When to use

Look up detailed product information for a specific ASIN, including title, item dimensions, declared package dimensions, images, and current BSR.

Tips

• Check item_status to verify the product is in an active state.
• sales_rank/sales_rank_category is the most specific subcategory rank; main_category_rank/main_category is the headline "#N in <Department>" rank shown on the product page.
• BSR gives a relative indicator of sales volume within its category. Lower is better.
• package_height, package_width, package_length, and package_weight are Amazon catalog attributes for the declared shipped package; use package_snapshot_date to assess freshness.
• Image URLs and bullet_points are useful for listing audit workflows.

Related tools

When to use

Monitor BSR across your entire catalog to identify top sellers and products losing rank.

Tips

• sales_rank is the most specific subcategory rank; main_category_rank is the broad department rank ("#N in <Department>"). The two can differ by orders of magnitude.
• Use max_rank=10000 to focus on products in the top 10,000 of their subcategory.
• Lower BSR means higher sales velocity. Track BSR trends over time by running this daily.
• Compare BSR against actual sales data from get_sales_velocity to validate.

Related tools

When to use

List A+ documents, verify which ASINs are assigned to one exact document, distinguish Brand Story from product-specific A+ by Amazon content type and locale, or find active brand ASINs missing that selected document.

Tips

• Start with documents, then pass the exact content_reference_key to relations or coverage. Duplicate names and localized variants are common.
• In relations and coverage, content_type and locale come from Amazon publish records. Brand Story appears as content_type BrandStory even though Amazon omits that value from its published enum.
• Use coverage with an exact brand match to audit one localized Brand Story or product-specific A+ document against the latest active catalog ASINs.

Watch out

• Requires Brand Registry enrollment. Returns empty document results if Brand Registry is not active.
• Coverage is document-specific. Select the intended locale and content reference key rather than matching a document by name.
• This read tool does not create, edit, or submit A+ Content. Use assign_brand_story_asins only for an existing approved Brand Story after reviewing this exact document’s relations.

Related tools

When to use

Understand the variation family structure for a product, find all child ASINs under a parent, or determine if an ASIN is a parent or child.

Tips

• Pass either a parent or child ASIN and the tool will show the full family tree.
• The variation theme (size, color, etc.) tells you which attribute differentiates the children.
• Use this to identify all child ASINs when you need to check inventory or pricing across the family.

Related tools

When to use

Use this to inspect listing completeness, Amazon listing issue signals, missing content, offer/fulfillment availability counts, and source-provided issue details.

Tips

• Use view="summary" to scan listing completeness and issue counts.
• Use view="issues" to inspect Amazon issue codes, affected attributes, and raw issue JSON.
• Filter by asin or sku when reviewing one listing before an update_listing preview.

Watch out

• Snapshots refresh weekly. For a live 'is this ASIN buyable right now' check, fan out across get_buybox_status, get_listing_restrictions, and get_fba_eligibility (all live SP-API), and cross-reference get_suppressed_listings.

Related tools

When to use

Inspect listing quality states across Amazon issues, missing content, offer availability, and fulfillment availability.

Tips

• Run with cleanup_focus=amazon_error to return rows with Amazon error-level listing issues.
• Use cleanup_focus=missing_core_content to find listings missing title, brand, or main image.
• Use cleanup_reasons and issue_attribute_names to group rows by captured listing quality signal.

Watch out

• The tool reads weekly listing quality snapshots; it does not perform live Seller Central validation. Use update_listing in preview mode before submitting changes.

Related tools

When to use

Use this to see what listing content actually changed between snapshots: title, brand, or description edits, main-image swaps, bullet rewrites, gallery-image changes, and backend keyword changes.

Tips

• Each row is one changed field with previous_value and current_value, so you can see exactly what changed. The source field tags whether it came from the catalog diff or the keyword diff.
• Array fields (bullet_points, image_urls) are compared as JSON, so a reordering counts as a change. The image set covers the full gallery, not just the main image.
• Backend search-term changes diff at weekly cadence and need two weekly Listings Items snapshots before they appear.

Watch out

• Amazon exposes no native listing edit-history API; this is computed from Agent Central's own snapshots, so it only sees changes from one captured snapshot to the next and a recent edit appears once the following snapshot lands.
• Video and A+ module-level content are not diffed: Amazon has no supported read feed for listing video, and A+ change status plus last-update time is on get_aplus_status.

Related tools

When to use

Use this before update_listing or create_listing when an attribute accepts a limited set of values, for example diet_type or allergen_information on a Grocery product type, so the agent can set the accepted key instead of guessing.

Tips

• The Listings Items API takes the enum key, not the display name: diet_type uses "vegan", not "Vegan", as an array item like {"value": "vegan"}.
• An unfiltered summary returns at most 50 enum_values per attribute. Check enum_value_count and truncated_attributes before treating it as complete.
• Pass attributes=[...] to get uncapped values and schema details for those attributes. Targeted results fail rather than truncate when they exceed 512 KB.
• Use schema view for the full raw schema when it is at most 512 KB.

Watch out

• Product Type Definitions is a live Amazon call and requires Seller Central credentials for the marketplace, cached five minutes per seller, marketplace, product type, requirements, parentage, locale, and version.
• Raw schemas larger than 512 KB are refused. Targeted attribute details use the same ceiling; split large requests into smaller attributes lists.

Related tools

When to use

Assign an existing approved Brand Story to additional ASINs when you know the exact content_reference_key and need Amazon’s complete current assignment set preserved.

Tips

• Start with get_aplus_status view=relations and copy the exact content_reference_key. Do not infer a key from the document name.
• Preview first. It shows requested additions, already assigned ASINs, unchanged assignments, the exact complete replacement set, and the fingerprint required on submit.
• Amazon replaces the complete relation set. The tool constructs an add-only union and refuses a submit when its fresh relation set no longer matches the preview fingerprint.
• The document must be Amazon-reported as approved BrandStory. Product-specific A+ Content and other content types are rejected.

Watch out

• Submissions are disabled until the controlled production Brand Story canary explicitly enables the guarded write mode. Preview remains available.
• An Amazon transport failure after reservation is reported as unknown. Do not retry with a new idempotency key; inspect the exact current relations first.
• The immediate post-submit readback is bounded. If it does not exactly match the expected replacement set, the tool reports partial or failed rather than claiming success.

Related tools

When to use

Create a product that is not already in Amazon’s catalog, or submit the full set of product facts and sales terms required for a catalog listing.

Tips

• Use create_listing_offer instead when the ASIN already exists and you only need a seller SKU plus sales terms.
• Use get_listing_restrictions first to check the selected ASIN or product type for account-specific restrictions.
• Check the response for missing or malformed attributes before submission.
• Run preview first; submit with confirm=true and a unique idempotency_key only after Amazon returns a valid preview.
• The submission can be accepted for processing before the listing becomes buyable.

Watch out

• Do not use this full-catalog path merely to add a new SKU to an existing ASIN. It requires product facts that an offer-only submission does not.

Related tools

When to use

Add a new seller SKU to an existing ASIN without making a full catalog contribution. Price and fulfillment are optional, so the SKU can be created inactive and completed later.

Tips

• Check listing restrictions for the ASIN and condition before submitting.
• The tool first proves that the SKU is unused and the ASIN exists in the selected marketplace.
• Amazon validation receives merchant_suggested_asin, condition_type, and any supplied price, fulfillment, battery, or dangerous-goods declarations under LISTING_OFFER_ONLY.
• A confirmed submission performs one bounded Listings Items readback. The response separates Amazon acceptance from SKU-to-ASIN verification.
• Omit price and fulfillment when you intentionally want an inactive SKU; add those sales terms later with the dedicated price and quantity tools.
• For a new FBA SKU, set the Amazon-fulfilled channel during creation. Use convert_listings_to_fba only when the SKU already exists as seller fulfilled.

Watch out

• The tool will not replace or relink an existing SKU. Amazon-fulfilled channel codes and non-new condition requirements are marketplace-specific; Amazon validation is authoritative.

Related tools

When to use

Switch existing FBM listings to FBA before creating an inbound plan. Use create_listing_offer instead when the seller SKU does not exist yet.

Tips

• Preview reports each SKU’s ASIN, current channels, target channel, FBA eligibility, reason codes, and Amazon validation issues.
• The submitted patch adds the marketplace’s Amazon-fulfilled channel and deletes DEFAULT. A listing already in the requested FBA-only state returns a no-op.
• Confirmed rows receive one bounded Listings Items readback, so Amazon acceptance and observed fulfillment state remain separate facts.
• A transport failure is recorded as unknown and stops the remaining batch rather than expanding a potentially partial conversion.

Watch out

• Amazon rejects affected products when required battery or dangerous-goods attributes are missing. Amazon validation preview is authoritative.
• Conversion changes listing fulfillment availability only. It does not create an inbound plan, move inventory, or make FBA units sellable.
• The tool blocks listings with additional fulfillment channels and marketplaces without a documented fixed FBA channel rather than guessing.

Related tools

When to use

Change listing content attributes such as title, Item Highlight, bullets, description, keywords, or images after reviewing the current Amazon listing state.

Tips

• Call it once without confirm to review current values, the resolved product type, the exact patch set, and Amazon’s validation response.
• Use Amazon Listings Items API attribute format for values, such as item_name: [{ value: "New title", marketplace_id: "ATVPDKIKX0DER" }].
• For Item Highlight, use title_differentiation with the same array and object value shape. Amazon documents a 125-character limit; verify the current Product Type Definition for the marketplace and product type before submitting.
• Use a stable idempotency_key for the business action, such as listing-SKU-attribute-YYYYMMDD.
• Use update_price for pricing, update_inventory_quantity for seller-managed quantities, and convert_listings_to_fba for an FBM-to-FBA conversion.

Watch out

• item_highlights and product_highlights are not Listings Items API attributes. The tool rejects them rather than remapping because schemas can vary by product type.
• Amazon can return a legacy product type in a listing summary. The tool uses PTD’s marketplace-specific canonical value and reports both values when they differ.
• Amazon error 90251 describes the submitted patch request, not necessarily stored listing state. Conditional Product Type Definition rules can require a companion attribute in the same validation-preview patch set even when it is already stored; review the current value before including it in a confirmed submission.
• Requires Seller Central credentials and a Seller ID. Confirmed submissions are recorded in action history with pre-submit current values and submitted values.

Related tools

When to use

Change base listing prices, schedule sales, set or update Amazon List Price (MSRP), or change Amazon Business prices, industry-segment offers, and quantity discounts after reviewing the current listing state and confirming the exact listing patch submission.

Tips

• Call it once without confirm to preview exact SKUs, target prices or sale dates, and Amazon validation output.
• Use sale_price with sale_start_date and sale_end_date (YYYY-MM-DD) to schedule a temporary sale price.
• Use clear_sale_price=true to remove the scheduled discounted_price from the consumer offer.
• Set list_price to update Amazon's List Price (MSRP, the strikethrough reference price). It patches the top-level list_price attribute, which is distinct from the consumer price.
• For business_quantity_discount_plan, fixed values are per-unit prices in the marketplace currency; percent values are percentage discounts from the B2B price.
• Use clear_business_quantity_discount_plan=true to remove quantity tiers without deleting the B2B offer.
• Use business_segment_prices for B2B_AUTOMOTIVE, B2B_EDUCATION, B2B_FED_GOVERNMENT, B2B_FOODSERVICE_HOSPITALITY, B2B_GOVERNMENT, B2B_HEALTHCARE, B2B_INDUSTRIAL, B2B_REAL_ESTATE, or B2B_STARTUP. Support is checked against the seller and marketplace product-type definition before Amazon validation.
• A segment entry requires price unless remove=true. Optional minimum_seller_allowed_price and quantity_discount_plan apply only to that segment; omitted fields are preserved. remove=true cannot be combined with price fields or tiers.
• Segment updates and removals select marketplace, currency, and audience. They do not replace ALL, B2B, or untargeted segments. Removal deletes the entire selected segment offer, not the listing.
• Segment readback verifies submitted attributes, not buyer-visible eligibility or the effective price for every customer. Inspect Amazon issues and get_listing_offers freshness; segment-only writes do not queue a consumer-price listing-offer refresh.
• Use a stable idempotency_key for the business action, such as price-SKU-YYYYMMDD.
• Set minimum and maximum seller allowed prices when you want Amazon-side bounds around the submitted consumer price.
• The tool patches the top-level purchasable_offer attribute using audience ALL for consumer pricing and audience B2B for general Amazon Business pricing, explicit industry audiences for segment pricing, and the top-level list_price attribute for List Price.

Watch out

• Requires Seller Central credentials and a Seller ID. Amazon Business fields require seller enrollment and product-type support for the selected marketplace; Amazon validation preview is authoritative. Confirmed submissions are capped at marketplace price bounds and recorded in action history as submitted values.

Related tools

When to use

Change available listing quantities after reviewing current fulfillment availability, especially to mark seller-fulfilled SKUs in stock or out of stock.

Tips

• Call it once without confirm to preview current quantity, ASIN, product type, and the target quantity.
• Use quantity=0 to mark a seller-fulfilled SKU out of stock.
• Use a stable idempotency_key for the business action, such as inv-SKU-YYYYMMDD.
• The default fulfillment_channel_code is DEFAULT, the seller-fulfilled offer channel.

Watch out

• Requires Seller Central credentials and a Seller ID. Amazon-fulfilled channels do not accept seller-managed quantities; use convert_listings_to_fba for an FBM-to-FBA conversion. FBA warehouse stock remains controlled by Amazon inventory and inbound workflows.

Related tools

When to use

Understand what customers praise or complain about for a product without reading individual reviews manually.

Tips

• Use negative topics to group complaint themes by mentions, occurrence percentage, and star-rating impact.
• Use STAR_RATING_IMPACT when you care more about rating movement than mention volume.
• Compare child ASIN metrics against parent and browse-node metrics to see whether an issue is product-specific.

Watch out

• Amazon refreshes Customer Feedback data weekly. The API requires enough review volume and expects a child ASIN.

Related tools

When to use

Read current monthly topic percentages from Amazon, or inspect older captured responses with explicit snapshot age and paused-source status.

Tips

• Use view="live" when current Amazon data is required.
• Use view="history" with snapshot_date for one captured response, or a bounded date range for several snapshots.
• Read snapshot_date, snapshot_age_days, freshness_state, and history_source before comparing stored rows.

Watch out

• Stored Customer Feedback ingestion is intentionally paused. History rows are stale snapshots and never claim to be current.
• The live API requires enough review volume and expects a child ASIN.

Related tools