listings_patchListingsItem
Patch attributes on an existing listing (JSON Patch) without replacing it — the tool for fixing a suppressed listing or changing price, inventory, title or images.
destructiveAmazon Seller (SP-API)sp.listingsItems_2021-08-01
Several patches may travel in one call. Amazon SP-API · patchListingsItem · PATCH /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_patchListingsItem",
"arguments": {
"store": "myStore-US",
"sku": "<sku>",
"product_type": "<product_type>",
"patches": []
}
}From code (Tool API)
curl -X POST https://api.sellersheetai.com/api/v1/tools/listings_patchListingsItem \
-H "Authorization: Bearer $SELLERSHEET_API_KEY" \
-H "Content-Type: application/json" \
-d '{"store":"myStore-US","sku":"<sku>","product_type":"<product_type>","patches":[]}'Early access — the Tool API is open on request, contact us.
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 of an existing listing. |
product_typerequired | string | the listing's productType — data.summaries[0].productType from listings_getListingsItem. |
patchesrequired | object[] | [{op, path, value}], at least one. op: add | replace | merge | delete (delete is not supported for vendors — Amazon returns 400). path: '/attributes/<attribute_name>'. value: the attribute's value ARRAY in exactly the shape listings_getListingsItem returns under data.attributes.<name> — read it first and patch only the paths you change; model a new attribute from catalogItems_getCatalogItem or from productTypeDefinitions_getDefinitionsProductType (the authoritative schema: enums, units, required keys). Examples — title: {"op": "replace", "path": "/attributes/item_name", "value": [{"value": "New Title", "language_tag": "en_US", "marketplace_id": "ATVPDKIKX0DER"}]}; price: path /attributes/purchasable_offer, value [{"audience": "ALL", "currency": "USD", "our_price": [{"schedule": [{"value_with_tax": 29.99}]}]}]; FBM stock: path /attributes/fulfillment_availability, value [{"fulfillment_channel_code": "DEFAULT", "quantity": 50}]; main image: path /attributes/main_product_image_locator, value [{"media_location": "https://…/img.jpg", "marketplace_id": "ATVPDKIKX0DER"}]. |
included_data | string[] | datasets to return; default ['issues']; identifiers needs mode VALIDATION_PREVIEW.identifiersissues |
mode | string | 'VALIDATION_PREVIEW' validates the patches without applying them (no write access needed); omit to apply. |
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 the result.
Body (Amazon schema)
productType*: string
patches*: [{op*: add | replace | merge | delete, path*, value: [object]}] (min 1)Gotchas
- A delete op must carry the attribute's EXACT current array as value, copied from listings_getListingsItem — an empty, omitted or simplified value comes back INVALID. Detach a child from its variation family: three delete ops — parentage_level, child_parent_sku_relationship, variation_theme — each with its current array; confirm with listings_getListingsItem. Add a child to a family: read variation_theme[0].name on the PARENT (e.g. COLOR_NAME), then on the CHILD replace parentage_level [{"value": "child", "marketplace_id": …}], child_parent_sku_relationship [{"child_relationship_type": "variation", "parent_sku": "PARENT-SKU", "marketplace_id": …}], variation_theme [{"name": "COLOR_NAME", "marketplace_id": …}] and the themed attribute itself (color …); confirm on the parent with included_data ['relationships'].