MCP Products Tools

Listings Accounts Get

listings_accounts_get — Read-only.

List the connected sales-channel accounts together with their inventory capabilities (quantity update, price update, quantity push). Use the returned values as the channel argument of products_revise_inventory.

Takes no parameters.

Product Delete

product_delete — Writes data.

Delete one or more products by id, optionally also removing their listings from connected sales channels. Deleted products cannot be restored.

items (array, required)

items[].id (integer, required)

items[].channels (boolean) — Also delete the product listings from connected sales channels.

Product Export

product_export — Read-only.

Export a single product with selected field values plus gemstone, metal and image data. Provide exactly one of product_id or product_sku.

product_id (integer)

product_sku (string)

fields (array) — Extra custom field codes to append, see product_listfields. This does NOT filter the response – the full product is always returned and these are added to it.

Product Export Additional Fields

product_export_additional_fields — Read-only.

List the dynamic per-channel export field definitions (active listings, listing URLs, per-account variants) usable with product_export.

Takes no parameters.

Product Import

product_import — Writes data.

Create a NEW product (always a create — SKU must be unique, else an error). product_type 0 is a jewelry item (type, model and collection are required); product_type 1 is a loose stone (only the first gemstones[] entry is used, as the main stone). Accepts core fields, metals, gemstones (linked/created by code), sizes, image URLs, videos, quantity and custom fields. NOTE: images[] URLs are fetched server-side; unknown fields{} codes are persisted as custom fields, and invalid ones fail silently.

product_type (integer, required) — 0 = jewelry item, 1 = loose stone. One of: 0, 1.

catalog_code (string) — SKU. Provide catalog_code or sku (one required); must be unique.

sku (string) — Alias of catalog_code.

title (string, required)

type (string) — Material/model type title. Required when product_type = 0.

model (string) — Required when product_type = 0.

collection (string) — Required when product_type = 0.

loose_type (integer/string) — Loose-stone type (product_type 1 only): 0 non-precious, 1 precious (default), 2 diamond, 3 pearl.

description (string)

price (number)

quantity (integer)

total_carat_weight (number)

title_in_description (string)

not_for_sale (boolean)

tags (array)

sizes (array) — Ring/product sizes; sizes[0] is the base value.

images (array) — Image URLs, fetched and stored server-side.

metals (array)

metals[].name (string, required) — Metal name; auto-created in your catalog if new.

metals[].purity (string/number) — Karat/purity; auto-created if new.

metals[].weight (number)

gemstones (array) — Stones linked/created by `code` (upsert against your gemstone catalog; there is no gemstone_id reference). Free-text taxonomy (color/clarity/cut/shape/type/…) auto-creates catalog rows. Same item shape as gemstone_import.

gemstones[].type (string/integer, required) — 0 non-precious, 1 precious, 2 diamond, 3 pearl, or free text.

gemstones[].code (string) — Unique key in your gemstone catalog (max 50 chars); auto-generated if omitted.

gemstones[].name (string)

gemstones[].color (string)

gemstones[].clarity (string)

gemstones[].cut (string)

gemstones[].shape (string)

gemstones[].treatment (string)

gemstones[].creation_method (string)

gemstones[].polish (string)

gemstones[].symmetry (string)

gemstones[].intensity (string)

gemstones[].overtone (string)

gemstones[].carat (number/string)

gemstones[].gemstone_total_carat_weight (number)

gemstones[].amount (integer) — Default: 1.

gemstones[].dimensions (string)

gemstones[].fluorescence (string)

gemstones[].unique (string)

gemstones[].quantity (integer/string)

gemstones[].price (number)

gemstones[].carat_price (number/string)

gemstones[].comments (string)

gemstones[].proprotion_depth (string) — Note the codebase spelling “proprotion”.

gemstones[].proprotion_length (string)

gemstones[].proprotion_width (string)

gemstones[].proprotion_table (string)

gemstones[].proprotion_crown_angle (string)

gemstones[].proprotion_crown_height (string)

gemstones[].proprotion_pavilion_angle (string)

gemstones[].proprotion_pavilion_depth (string)

gemstones[].proprotion_star_length (string)

gemstones[].proprotion_lower_half (string)

gemstones[].proprotion_girdle (string)

gemstones[].proprotion_culet (string)

gemstones[].certificate_num (string)

gemstones[].certificate_num2 (string)

gemstones[].certificate_text (string)

gemstones[].certificate_text2 (string)

gemstones[].certificate_file (string) — Certificate PDF URL, fetched server-side (SSRF-guarded).

gemstones[].certificate_file2 (string)

gemstones[].certificate_file_external (string) — GIA/IGI provider ref, form “<provider>_<mode>”, e.g. GIA_pdf.

gemstones[].certificate_file2_external (string)

gemstones[].fields (object) — Custom gemstone field values keyed by field code.

videos (array)

videos[].type (string, required) — One of: youtube, vimeo, valigara, segoma, v360viewer, sirvviewer, external.

videos[].url — Video URL (may be an array of URLs when type = external).

fields (object) — Custom product field values keyed by field code, see product_listfields.

Product Listfields

product_listfields — Read-only.

List all available product field definitions (code, title, type) usable in product_export, product_import and product_update payloads.

Takes no parameters.

Product Search

product_search — Read-only.

Search products by SKU. Returns matching sku and product_id pairs.

sku (string or array of strings)

Product Sold

product_sold — Writes data.

Register a sale of a product: decrements its stock quantity and optionally ends or revises the channel listings. NOT IDEMPOTENT: each call decrements again. If a call times out or the result is unclear, do NOT retry – read the product’s quantity first and decide from that, because a blind retry sells the same item twice and can oversell the listing on the sales channel.

product_id (integer, required)

quantity (integer) — Default: 1.

stock_id (integer) — Stock location id to decrement, see order_stocks. Effectively required: omitting it decrements stock 0, which is not a real location, so nothing changes and the call still reports success.

sold_action (string) — Optionally end (‘remove’) or revise channel listings after the decrement. One of: remove, revise.

Product Update

product_update — Writes data.

Update an existing product by product_id: core fields (sku/catalog_code, title, description, price, tags, quantity), gemstones, metals, images, videos, sizes and custom fields. The actions object controls whether gemstones/metals/images are added to or override the existing ones (default override). May start channel revision batches when quantities change. DESTRUCTIVE DEFAULT: gemstones, metals and images REPLACE what is on the product unless the `actions` object says otherwise. Sending a partial gemstones[] therefore DELETES the stones you left out – including certificated grading data that cannot be re-derived. Never send these arrays reconstructed from memory or from a partial read: read the product first, and if you only mean to add, set the matching `actions` entry to add. If you are only changing a scalar field such as title or price, omit the arrays entirely.

product_id (integer, required)

catalog_code (string) — New SKU; must be unique.

sku (string) — Alias of catalog_code.

model (string)

collection (string)

type (string)

title (string)

description (string)

price (number)

tags (array) — Replaces all existing tags.

not_for_sale (boolean)

update_channels_quantity (integer) — Revise/end channel listings when the quantity changes. One of: 0, 1.

total_carat_weight (number)

gemstones (array) — Same item shape as gemstone_import / product_import.gemstones. See actions.gemstones for add-vs-override.

gemstones[].type (string/integer, required) — 0 non-precious, 1 precious, 2 diamond, 3 pearl, or free text.

gemstones[].code (string) — Unique key in your gemstone catalog (max 50 chars); auto-generated if omitted.

gemstones[].name (string)

gemstones[].color (string)

gemstones[].clarity (string)

gemstones[].cut (string)

gemstones[].shape (string)

gemstones[].treatment (string)

gemstones[].creation_method (string)

gemstones[].polish (string)

gemstones[].symmetry (string)

gemstones[].intensity (string)

gemstones[].overtone (string)

gemstones[].carat (number/string)

gemstones[].gemstone_total_carat_weight (number)

gemstones[].amount (integer) — Default: 1.

gemstones[].dimensions (string)

gemstones[].fluorescence (string)

gemstones[].unique (string)

gemstones[].quantity (integer/string)

gemstones[].price (number)

gemstones[].carat_price (number/string)

gemstones[].comments (string)

gemstones[].proprotion_depth (string) — Note the codebase spelling “proprotion”.

gemstones[].proprotion_length (string)

gemstones[].proprotion_width (string)

gemstones[].proprotion_table (string)

gemstones[].proprotion_crown_angle (string)

gemstones[].proprotion_crown_height (string)

gemstones[].proprotion_pavilion_angle (string)

gemstones[].proprotion_pavilion_depth (string)

gemstones[].proprotion_star_length (string)

gemstones[].proprotion_lower_half (string)

gemstones[].proprotion_girdle (string)

gemstones[].proprotion_culet (string)

gemstones[].certificate_num (string)

gemstones[].certificate_num2 (string)

gemstones[].certificate_text (string)

gemstones[].certificate_text2 (string)

gemstones[].certificate_file (string) — Certificate PDF URL, fetched server-side (SSRF-guarded).

gemstones[].certificate_file2 (string)

gemstones[].certificate_file_external (string) — GIA/IGI provider ref, form “<provider>_<mode>”, e.g. GIA_pdf.

gemstones[].certificate_file2_external (string)

gemstones[].fields (object)

metals (array)

metals[].name (string, required) — Metal name; auto-created in your catalog if new.

metals[].purity (string/number) — Karat/purity; auto-created if new.

metals[].weight (number)

sizes (array) — Empty array clears all sizes.

images (array) — Image URLs, fetched server-side. See actions.images (default add).

videos (array) — Videos are always fully replaced (all deleted, then re-added), regardless of actions.

videos[].type (string, required) — One of: youtube, vimeo, valigara, segoma, v360viewer, sirvviewer, external.

videos[].url — Video URL (may be an array of URLs when type = external).

quantity (integer)

fields (object) — Custom product field values keyed by field code. Unknown codes are stored; invalid values fail silently.

actions (object) — add appends to existing; override deletes existing first. Defaults: gemstones/metals = override, images = add.

actions.gemstones (string) — One of: add, override.

actions.metals (string) — One of: add, override.

actions.images (string) — One of: add, override.

Product Update Listings

product_update_listings — Writes data.

Start an asynchronous batch revising the channel listings of the given products with their latest product data, optionally pushing stock quantities. Rate limited; returns started batch ids – poll batch_info for completion.

ids (array, required)

channels (array of strings or the string ‘ALL’, required) — Either the literal string ‘ALL’, or an array of channel targets. Most marketplaces revise per account and need “<Channel>_<accountId>” – Amazon and eBay including their regional marketplaces, plus Etsy, Shopify, Walmart, WooCommerce, Sears and Shein. A bare channel name matches nothing for those. The rest (BigCommerce, Bonanza, TargetPlus, Magento, Magento2, Rapnet, Shop, Social, CustomChannel, LightspeedPOS) take the bare name. Account ids come from listings_accounts_get. Identifiers are case-sensitive and are not brand spellings: Ebay, not eBay.

push_qty (boolean) — Default: false.

push_qty_set_from_product (boolean) — Default: false.

Products Copy Data

products_copy_data — Writes data. Beta: this tool is being rolled out and may not be available on your account yet.

Copy selected field values from one product onto other products (“between products” mode of the Copy Data page). `fields` are field codes such as basic_gemstones or basic_metals – call it once with a wrong code and the error returns the full valid list for this client. Set overwrite=true to replace values that are already set on the targets, otherwise only empty ones are filled. The source product is dropped from the targets automatically. This starts an asynchronous BATCH and returns started_batch_ids – nothing has changed when the call returns; poll batch_info and read batches_errors if it reports failures. overwrite=true DESTROYS the targets’ existing values for the chosen fields, with no undo and no record of what they were. Confirm the exact target count and field list with the user before setting it, and prefer overwrite=false unless they asked for replacement. Pass dry_run=true first to see the resolved target count and which ids do not exist.

source_product_id (integer, required)

target_product_ids (array, required)

fields (array, required)

overwrite (boolean) — Default: false.

dry_run (boolean) — Return what this call WOULD do, without doing it. Use it first whenever you are not certain of the scope, and show the projection to the user before calling for real. Default: false.

Products Export

products_export — Read-only.

Export products as structured rows. Supports pagination (offset/limit), selecting the returned fields, sorting by create/update date and filtering by model, type and tags. Returns items plus total_items_count.

offset (integer) — Default: 0.

limit (integer) — Default: 20.

fields (array)

sort (string) — Default: “create_date asc”. One of: create_date asc, create_date desc, update_date asc, update_date desc.

model (array)

type (array)

tags (array)

Products Get

products_get — Read-only.

List products with pagination. Returns full product payloads including SKU, product type, title, price, quantity, gemstones, images, videos and custom fields.

page_size (integer) — Default: 20.

page_num (integer) — Default: 1.

Products Post

products_post — Writes data.

Post products to a sales channel account using a posting template (see products_post_templates_list). Starts an asynchronous batch; poll batch_info for completion. This publishes listings that real buyers can see and purchase, and `ids` has no upper bound – confirm the exact product count and the target account with the user before calling. Posting cannot be undone from here; a wrong listing has to be ended on the channel afterwards.

ids (array, required)

channel (string, required) — Platform identifier as Valigara stores it, not a brand spelling: eBay is `Ebay`. Each regional marketplace is its own value (AmazonUK is not Amazon). One of: AAFES, Amazon, AmazonAU, AmazonCA, AmazonCN, AmazonDE, AmazonES, AmazonFR, AmazonIN, AmazonIT, AmazonJP, AmazonMX ….

account_id (integer, required)

post_template_id (integer, required) — From products_post_templates_list. Use -1 for a channel’s built-in “General” template, which is what Shopify and WooCommerce return when no custom template exists – it is a real id, not a sentinel for “none”.

Products Post Templates List

products_post_templates_list — Read-only.

List the posting templates available per sales channel account. Use the returned channel, account_id and posting_template_id with products_post.

Takes no parameters.

Products Revise Inventory

products_revise_inventory — Writes data.

Start an asynchronous batch pushing price and/or quantity updates of the given products to one sales channel account. At least one of revise_price or revise_quantity must be true. Returns started batch ids; poll batch_info for completion.

ids (array, required)

channel (string, required) — A channel ACCOUNT, not a channel: “<platform>_<account_id>”, e.g. the value listings_accounts_get returns for the account you mean. The platform part uses Valigara’s identifier (eBay is `Ebay`); the account id decides which of the client’s shops on that platform is updated, so getting it wrong pushes prices or stock to the wrong storefront.

revise_price (boolean) — Default: false.

revise_quantity (boolean) — Default: false.

push_qty (boolean) — Default: false.

push_qty_set_from_product (boolean) — Default: false.