Create one catalog product as one row per variant on a catalog sheet. A variant whose option is still a size range (such as XS-XXL or 28-36), or 2 or more variants with two price attributes and no barcode_mode, returns needs_input until a catalog plan_token from plan_import is sent. SKU is optional and is never a reason for needs_input. On a planned write, accepted_gaps must equal the signed list. Empty brand, type, and an unexpanded size can still block. An empty barcode is not a gap when barcode_choice is none or cloudlabels_ean13. Otherwise an empty barcode can still block. Selling Price and attribute names are not price_without_currency or unknown_columns blockers. manual_fixes counts variants of this product and omits row indexes. A normal product with explicit sizes is unchanged, including 10 or more variants. plan_token is optional. When a token is sent, its signed answers must cover the relevant questions and barcode_mode must match barcode_choice. A token without answers is rejected: call plan_import again. Do not pick a default. When a plan_token is sent, it must record enable_catalog true and a barcode_choice, and barcode_mode must match that choice. This tool does not turn Catalog on and does not turn on the barcode generator. When the token is accepted, the result includes import_check. If mismatch is true, tell the user and do not hide it. There is one sellingPrice role. Put a second price in attributes only after the user agrees to that column. Writes Name, SKU, Brand, Type, Selling Price, optional Unit Cost, Description, and Notes by Catalog role (fieldMappings). Roles are photo, name, sku, barcode, unitCost, sellingPrice, type, brand, totalQty, defaultLocation, variantOption1, variantOption2, description, notes. Without a role map, the English names are used. option_1 and option_2 go to the variant option columns (role variantOption1/variantOption2, or Group option 1 and 2, Colour and Size). Category is Type. Optional top-level description and notes, plus per-variant overrides, write through those roles. type, selling_price, brand, unit_cost, description, and notes fail with a mapping error when the role is unmapped: add_column if needed, then adopt_catalog_sheet with role_overrides. Do not send those through attributes. Optional attributes write only visible extra columns that no catalog role maps to, by the exact header from get_sheet_settings. Each name is resolved the same way createItems resolves fields (lowercase, trim, column id). The resolved column must be an extra. Names that match barcode/ean/ean-13/gtin/upc, look like data1, or collide with another header after lowercase/trim are refused. Role-mapped names (Name, SKU, Barcode, prices, Type, Brand, Photo, option 1/2, qty, location, Description, Notes, and the rest) and hidden columns (including Shopify reserved data13-28 and hidden data slots) are refused. Unknown names are rejected and the error lists only the valid extras. At most 20 keys, each value 500 characters or fewer. Variant rows are inserted in one batch. Optional variant.barcode supplies a GTIN for that row. If no barcode is given, Show choices together. Clickable form if the client supports it. Otherwise one number, only when it cannot show choices. Wait. Do not choose for the user. Do not continue until the user has answered. Do you want barcodes? No, no barcodes now (barcode_mode="none"). Cloudlabels generates EAN-13 (codes starting with 2 are internal store codes, not registered GS1 codes), barcode_mode="cloudlabels_ean13". This call only. Does not change sheet settings. I have my own codes (own GTIN). No option is recommended. A needs_input error lists those options. Cloudlabels can generate EAN-13 only. If the organization has opted in to its GS1 company prefix for this column and the sheet standard is EAN-13, UPC-A, or EAN-8, each new row reserves the next prefix number before saving and barcodeSource is gs1_prefix. The cell stores the digit body without the check digit. A full prefix is an error and does not fall back to a random code. Pass image_url only as a public https image; the same URL can be repeated for sizes that share a photo. Optional unit_cost at product level can be overridden per variant. Optional option_1_label/option_2_label rename the sheet axes only when rename_sheet_axes is true, or when the current labels are empty or the catalog defaults (Group option 1 / Group option 2). Otherwise the sheet labels are kept and the response says so. A variant column header is renamed to the axis name when it is empty, Group option 1 or Variant option 1 on the first axis, Group option 2 or Variant option 2 on the second axis, or the exact default for that column id (Data 1 to Data 60 with one space, such as Data 11 on data11). Headers such as data12, Data 11, Data 99, or Data 5 on a different column are custom and are kept unless rename_sheet_axes is true. If the new name matches another column header, visible or hidden, that header is kept and the response says the name is already used. The response says which columns were renamed and which were kept. The column id and catalog role stay the same. Retry the same product name with the same option_1, option_2, and sku values to get the saved rows back with already_existed: true and no new rows. attributes, description, and notes on that retry are not applied. If that product name already has a different variant list, the call fails and lists the saved variants. It does not merge them. Use add_catalog_variants to add variants to that product. Extra copies of the same option pair that are already on the sheet are left in place, and the first matching set is returned. Optional idempotency_key is stored for 24 hours for this organization and this tool when mcp_idempotency exists. The same key and the same arguments return the stored result and do not insert again. The same key with different arguments is rejected. A key that is still in progress is rejected. The in-process guard remains: for 10 minutes in this server process it returns the first success for that organization and key even when the arguments differ, and it is not shared across servers. Without a key, overlapping calls for the same organization, sheet, and product name are serialized in this process only. 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.