MCP workflows: read and update shop data

These examples show tool arguments, not HTTP request bodies. An assistant normally builds them from your instruction. IDs, SKU, language and ETag below are illustrative: use values returned by your installation. Try writes in a development shop with fictitious data.

Select the shop and language

1. Call netseller_list_shops with {} and choose the intended shop.
2. Call netseller_list_shop_languages with {"shopId": 1}.
3. If working with prices, call netseller_list_shop_currencies with {"shopId": 1}.
4. Pass that context explicitly to subsequent tools that support it.

These tools require orientation and settings:read. Do not assume that an installation uses English, CHF or shop ID 1.

Find and read a product

Requires catalog read and catalog:read.

Call netseller_list_products to find an exact SKU:

{"shopId": 1, "language": "en", "sku": "DEMO-001"}

Select the matching returned product ID, then call netseller_get_product:

{"shopId": 1, "language": "en", "productId": 123}

Read the returned data and retain meta.etag if you intend to edit. For broader lists, follow pagination; the first page is not the entire catalog. Embedded product variants describe active variants only. Use netseller_list_variants with productId and active: "all" when reconciling draft variants.

Example instruction:

In the selected shop, find SKU DEMO-001 and show its English name and current status. Do not change anything.

Change a product name

Additionally requires catalog write and catalog:write. Read the product first, confirm the intended record and language, and call netseller_update_product with only the changed fields:

{
  "shopId": 1,
  "language": "en",
  "productId": 123,
  "etag": "\"example-validator\"",
  "changes": {"name": "Demo travel mug"}
}

Replace example-validator with the exact latest meta.etag, preserving its surrounding quotes. This placeholder is not a valid validator for your product. The changes object is a partial update; do not copy read-only fields from a response into it.

Read the product again after success and verify the stored name. Localized content uses the selected language; shared product fields can affect other assigned shops.

Write and retry rules

Situation	Action
Protected update	Read the matching resource first and pass its unchanged meta.etag as etag. A validator from a different resource is not interchangeable.
Missing validator / HTTP 428	Read the resource and supply the required validator.
Stale validator / HTTP 412	Re-read, compare the current data with your intended change, and submit an adjusted update with the new validator. Do not blindly overwrite another edit.
Create tool requires idempotencyKey	Generate a stable key for that one logical creation, for example demo-product-20261014-001. Keep it with the request.
Timeout during an idempotent create	Retry the same operation with exactly the same payload and key. A new key may create a duplicate.
HTTP 409 idempotency_conflict	The key was used for a different payload. Resolve which operation was intended; use a new key only for a genuinely new creation.
Validation error	Correct the reported fields using the tool schema and discovered IDs.

Idempotency and ETags solve different problems: a key prevents duplicate creation on an exact retry; an ETag prevents overwriting a newer resource version. Supply these arguments only where the tool schema defines them. Weak validators and * cannot replace the required strong ETag.

Replace a collection or import a batch

A replacement operation can remove omitted entries. Read the current collection, preserve entries you intend to keep, and submit only writable fields. For example, netseller_replace_shop_footer_columns replaces all maintained footer columns; an empty collection clears them. It requires shop-configuration write and content:write.

For larger catalog imports, use the catalog import-job tools and their advertised payload rather than a long series of guessed calls. Use the supported dry run, inspect per-record results and resume with the current expected cursor. Keep external-reference identifiers stable across retries. Catalog import jobs do not replace the separate tools for all definitions, media and relationships.

Consult the Commerce API reference for the underlying business rules and response schemas. The connected tool’s schema remains the reference for MCP argument names.