Add catalog variants
add_catalog_variantsAdd new variants to one existing catalog product on a catalog sheet. If get_import_guide or plan_import is missing, reconnect MCP. Do not invent barcodes, size steps, or currency. This is the follow-up after a confirmed plan. It does not take plan_token. Always call it with dry_run true first, then the same arguments without dry_run. Do not use it to import a whole file. Pass product_id (an existing variant row id on that sheet) or name (the exact style name). Does not create a product, does not change existing rows, and does not turn Catalog or the barcode generator on. option_1 and option_2 are the variant options (Colour and Size, or the mapped option columns). SKU is optional. A saved colour and size is skipped and listed under existing. A repeated option pair in this request, or a different SKU for a saved pair, is listed under conflicts and is not written. At most 100 variants. dry_run true returns added, existing, and conflicts and writes nothing. A dry run does not store idempotency_key. Pass idempotency_key on the write. The server assigns barcodes only when the barcode generator is already on. Do not send a barcode. Brand and type are copied from the existing product when omitted, and apply only to the new rows. Selling price and unit cost are written only when sent, and only on the new rows. Price changes on existing rows use bulk_update_items with the column header, not the sellingPrice role. The plan item limit still applies. Without a key, overlapping calls for the same organization, sheet, and product name are serialized in this process only. With a key, the in-process guard returns the first success for 10 minutes in this server process even when the arguments differ, and it is not shared across servers. Optional idempotency_key. Omit this field when it is not used. Null, an empty string, or only spaces are also treated as omitted. Use a unique value such as a UUID. The same key and the same arguments return the stored result for 24 hours and set idempotent_replay to true. A key still in progress is rejected until the lease expires (15 minutes by default). The same key can also stay reserved until the lease expires (15 minutes by default) after a call failed after writing rows, so check whether those rows were saved before trying again. The same key with different arguments is rejected. A stored result over 200 KB is replaced by a short summary of ids and counts.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"sheet_number": "<sheet_number>",
"variants": "<variants>"
},
"name": "add_catalog_variants"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| type | No | ||
| brand | No | ||
| notes | No | ||
| dry_run | No | ||
| variants | Yes | ||
| unit_cost | No | ||
| product_id | No | ||
| description | No | ||
| sheet_number | Yes | ||
| selling_price | No | ||
| idempotency_key | No | Optional. Omit this field when it is not used. An empty string is also treated as omitted. Use a unique value such as a UUID when you send one. Same key and same arguments return the stored result for 24 hours in this organization, with idempotent_replay true. A different payload is rejected. |