listings_putListingsItem
Create a listing, or fully replace an existing one — PUT replaces every attribute, so for a targeted change use listings_patchListingsItem.
destructiveAmazon Seller (SP-API)sp.listingsItems_2021-08-01
Requires a write-enabled store. Takes the nested Amazon shape only: for Publish Queue cells (flat-file keys) use listings_submit_items, or listings_submit_feed for large batches. Amazon SP-API · putListingsItem · PUT /listings/2021-08-01/items/{sellerId}/{sku} Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.
Call it
In an AI client (MCP)
{
"name": "listings_putListingsItem",
"arguments": {
"store": "myStore-US",
"sku": "<sku>",
"product_type": "<product_type>",
"attributes": {}
}
}From code (Tool API)
curl -X POST https://api.sellersheetai.com/api/v1/tools/listings_putListingsItem \
-H "Authorization: Bearer $SELLERSHEET_API_KEY" \
-H "Content-Type: application/json" \
-d '{"store":"myStore-US","sku":"<sku>","product_type":"<product_type>","attributes":{}}'Arguments
| Name | Type | Description |
|---|---|---|
storerequired | string | the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim. |
skurequired | string | the merchant SKU — a new SKU creates, an existing one replaces. |
product_typerequired | string | the Amazon productType, e.g. 'LUGGAGE' (productTypeDefinitions_searchDefinitionsProductTypes finds it); 'PRODUCT' for LISTING_OFFER_ONLY. |
attributesrequired | object | {attribute_name: [value objects]} — every value is an ARRAY of objects carrying marketplace_id, text ones language_tag too, e.g. item_name [{"value": "My Product", "language_tag": "en_US", "marketplace_id": "ATVPDKIKX0DER"}]; merchant_suggested_asin [{"value": "B0XXXXXXXX", "marketplace_id": …}]; purchasable_offer [{"audience": "ALL", "currency": "USD", "our_price": [{"schedule": [{"value_with_tax": 29.99}]}]}]; fulfillment_availability [{"fulfillment_channel_code": "DEFAULT", "quantity": 10}]; main_product_image_locator [{"media_location": "https://…/img.jpg", "marketplace_id": …}]. Shapes, enums, units and required keys are productType-specific — take them from an existing listing (listings_getListingsItem returns exactly this shape), a catalog item (catalogItems_getCatalogItem) or the authoritative schema (productTypeDefinitions_getDefinitionsProductType). The marketplace id comes from get_user_context. |
requirements | string | LISTING (default — product facts + sales terms) | LISTING_OFFER_ONLY (sales terms only: condition_type, merchant_suggested_asin, purchasable_offer, fulfillment_availability, with product_type 'PRODUCT') | LISTING_PRODUCT_ONLY (product facts only; not for vendors).LISTINGLISTING_PRODUCT_ONLYLISTING_OFFER_ONLY |
included_data | string[] | datasets to return; default ['issues']; identifiers needs mode VALIDATION_PREVIEW.identifiersissues |
mode | string | 'VALIDATION_PREVIEW' validates without submitting (no write access needed); omit to submit. |
issue_locale | string | locale of Amazon's issue messages (e.g. 'en_US'); defaults to the marketplace's primary language. |
seller_id | string | Vendor Central only — the vendor code (sellingParty.partyId from vendorOrders_getPurchaseOrders); omit on a seller account. |
Result
Every tool answers {notification, data, human_action}; data carries:
data.status— ACCEPTED (queued) | INVALID | VALID (the preview passed).data.submissionId— this submission.data.issues— when INVALID — [{code, message, severity ERROR | WARNING | INFO, categories, attributeNames}]: fix them and resubmit without mode. After ACCEPTED, listings_getListingsItem after ~30 s shows whether the listing is BUYABLE.