Sylius Admin: Tool Reference

All 55 tools of the Sylius Admin server with parameters: products, variants, categories, attributes, options, images, countries, zones, shipping, tax categories and plugin data. Plus safeguards and special behavior.

Deutsche Version

Back to overview

Sylius Admin: Tool Reference

This documentation always describes the latest published version.

The server registers 55 tools. Claude Code prefixes every tool name with the name of the respective MCP server (syliusadmin-stage-mcp or syliusadmin-prod-mcp). The tables below list the names without prefix.

Overview

Category	Tools	Count
Products	`list_products`, `get_product`, `search_products`, `create_product`, `update_product`, `set_product_active`	6
Variants and prices	`list_variants`, `get_variant`, `add_variant`, `update_variant`, `update_variant_channel_pricing`	5
Categories (taxons)	`list_taxons`, `get_taxon`, `create_taxon`, `update_taxon`	4
Attributes	`list_product_attributes`, `get_product_attribute`, `create_product_attribute`	3
Options	`list_product_options`, `get_product_option`, `create_product_option`	3
Images	`list_product_images`, `add_product_image`, `list_taxon_images`, `add_taxon_image`	4
Channels	`list_channels`	1
Countries	`list_countries`, `get_country`, `create_country`, `update_country`	4
Zones	`list_zones`, `get_zone`, `create_zone`, `update_zone`	4
Shipping categories	`list_shipping_categories`, `get_shipping_category`, `create_shipping_category`, `update_shipping_category`	4
Shipping methods	`list_shipping_methods`, `get_shipping_method`, `create_shipping_method`, `update_shipping_method`, `archive_shipping_method`, `restore_shipping_method`	6
Tax categories	`list_tax_categories`, `get_tax_category`, `create_tax_category`, `update_tax_category`	4
Marketplace links (plugin)	`list_product_marketplace_links`, `get_product_marketplace_link`, `create_product_marketplace_link`, `update_product_marketplace_link`, `delete_product_marketplace_link`	5
Input fields (plugin)	`list_product_custom_input_fields`, `get_product_custom_input_field`	2
Total		55

Every list is paginated: page (from 1) and items_per_page (1 to 100, default 30). Codes (product, variant, category and so on) may only contain letters, digits, underscore and hyphen and be at most 255 characters long, otherwise the server rejects the call before anything is sent.

Products

Tool	Purpose	Required parameters	Optional parameters
`list_products`	List products	-	`page`, `items_per_page`, `code` (substring), `name` (substring)
`get_product`	Read one product	`code`	-
`search_products`	Search with all filters and sorting	-	`page`, `items_per_page`, `code`, `name`, `taxon_code`, `main_taxon_code`, `channel_code`, `sort_by` (`code`, `createdAt`, `name`), `sort_direction` (`asc`, `desc`), `locale` (required with `sort_by=name`)
`create_product`	Create a product, always disabled	`code`, `channel_codes`, `translations`	`main_taxon_code`, `option_codes`
`update_product`	Change a product, only passed fields	`code`	`channel_codes`, `translations`, `main_taxon_code`, `option_codes`, `enabled`
`set_product_active`	Make a product visible or hidden	`code`, `enabled`	-

Important rules:

channel_codes is required on create_product and must not be empty: a product without a channel is invisible in every shop.
translations is, per locale (for example de_DE), an object with at least name (2 to 255 characters). Further keys: slug, description, shortDescription, metaKeywords, metaDescription (meta fields at most 255 characters each) and the SEO fields below.
On update_product, translations are merged per locale and field with the existing data; locales not mentioned stay untouched. channel_codes and option_codes, in contrast, replace the whole list.
option_codes makes a product configurable. An empty value removes all options, but Sylius only applies that while the product has no variant yet; afterwards the old option list stays without an error message.
The server rejects activation (enabled=true via set_product_active or update_product) as long as the product has no variant. To do so it reads the product again before writing.

SEO fields of the translations

In addition to metaKeywords and metaDescription, the translations of products and categories accept the fields of the sylius-seo-suite-pro plugin:

Field	Rule
`metaTitle`	Text, at most 255 characters, not empty; `null` removes the override
`canonicalPathOverride`	Path of this shop with exactly one leading slash, not a URL; at most 255 characters
`robotsIndex`, `robotsFollow`	`true` or `false`
`metaDescription` (categories only)	At most 512 characters

These fields only exist where the shop's translation classes use the traits of the sylius-seo-suite-pro plugin. Otherwise the API ignores them without an error message: a successful call does not prove they were stored, so read the translation back.

Variants and prices

Tool	Purpose	Required parameters	Optional parameters
`list_variants`	List variants	-	`product_code`, `page`, `items_per_page`, `code`, `name`
`get_variant`	Read one variant	`code`	-
`add_variant`	Create a variant	`product_code`, `code`, `channel_pricings`	`translations`, `option_value_codes`, `enabled`, `tax_category_code`, `shipping_category_code`, `shipping_required`, `tracked`, `on_hand`, `weight`, `width`, `height`, `depth`, `position`
`update_variant`	Change a variant, without prices	`code`	`translations`, `option_value_codes`, `enabled`, `tax_category_code`, `shipping_category_code`, `shipping_required`, `tracked`, `on_hand`, `weight`, `width`, `height`, `depth`, `position`
`update_variant_channel_pricing`	Set the price for exactly one channel	`code`, `channel_code`, `price`	`original_price`, `minimum_price`, `clear_original_price`, `clear_minimum_price`

Prices are whole numbers in the smallest currency unit (cents) and at least 0.
channel_pricings on add_variant is, per channel code, an object with price and optionally originalPrice and minimumPrice. It must cover every channel the product is assigned to, otherwise the server aborts before writing with a clear message.
If the product has options, every variant needs option_value_codes with exactly one value per option code of the product, no more and no fewer. update_variant replaces the option values completely.
update_variant_channel_pricing leaves all other channels as well as the channel's originalPrice and minimumPrice untouched, unless you pass a new value or the matching clear_* flag.
Tax and shipping category can be assigned with these tools but not removed again. onHold (reservations) is not writable. on_hand and the dimensions must be at least 0.

Categories (taxons)

Tool	Purpose	Required parameters	Optional parameters
`list_taxons`	List categories with nested children	-	`page`, `items_per_page`
`get_taxon`	Read one category	`code`	-
`create_taxon`	Create a category	`code`, `translations`	`parent_code`, `enabled` (default `true`)
`update_taxon`	Change or move a category	`code`	`translations`, `parent_code`, `clear_parent`, `enabled`, `position`

There is no filter by code or name: to search, page through the list or use get_taxon.
parent_code and clear_parent are mutually exclusive. Changing the name does not regenerate the slug.
The response of list_taxons grows with the depth of the tree; use a small items_per_page for deep category trees.

Attributes and options

Tool	Purpose	Required parameters	Optional parameters
`list_product_attributes`	List attribute definitions	-	`page`, `items_per_page`
`get_product_attribute`	Read one attribute definition	`code`	-
`create_product_attribute`	Create an attribute definition	`code`, `type`, `translations`	`translatable` (default `true`), `configuration`, `position`
`list_product_options`	List options	-	`page`, `items_per_page`
`get_product_option`	Read one option with values	`code`	-
`create_product_option`	Create an option with values	`code`, `translations`, `values`	`position`

Attribute types the server documents: text, textarea, checkbox, integer, float, percent, datetime, date, select. The type is not checked locally; Sylius rejects an unknown type. Type and code cannot be changed after creation. select requires configuration with choices.
Each value in create_product_option has its own code, which must be unique across all options (for example color_red instead of red), and translations with the key value.
There are no update or delete tools for attributes and options.

Images

Tool	Purpose	Required parameters	Optional parameters
`list_product_images`	List the images of a product	`product_code`	`page`, `items_per_page`, `variant_code`
`add_product_image`	Add an image	`product_code` and exactly one of `image_path` or `cdn_url`	`image_type`, `variant_codes` (not with `cdn_url`)
`list_taxon_images`	List the images of a category	`taxon_code`	`page`, `items_per_page`
`add_taxon_image`	Add a category image	`taxon_code` and exactly one of `image_path` or `cdn_url`	`image_type`

image_path: the server reads the file locally and uploads the bytes as a multipart upload. This requires SYLIUS_IMAGE_UPLOAD_BASE_DIR; the file must lie inside it, be .jpg, .jpeg, .png, .gif or .webp and be at most 10,000,000 bytes.
cdn_url: an image that already lives on the CDN. Only the http(s) URL (at most 255 characters) is stored, nothing is uploaded and no local file is read. This requires the shop plugin sylius-cdn-product-images.
Images cannot be changed or deleted through this server.

Channels, countries, zones

Tool	Purpose	Required parameters	Optional parameters
`list_channels`	Look up channel codes (read-only)	-	-
`list_countries`	List countries	-	`page`, `items_per_page`
`get_country`	Read a country	`code`	-
`create_country`	Register a country	`code`	`enabled` (default `true`)
`update_country`	Enable or disable a country	`code`, `enabled`	-
`list_zones`	List zones	-	`page`, `items_per_page`
`get_zone`	Read a zone	`code`	-
`create_zone`	Create a zone	`code`, `name`, `type`, `members`	`scope` (default `all`), `priority` (default 0)
`update_zone`	Change a zone	`code`	`name`, `members`, `priority`

Countries have no name the API lets you write; update_country only toggles enabled.
A zone's type is country, province or zone and determines what members contains. type, scope and code cannot be changed after creation. On update_zone, members replaces the whole list and must not be empty.

Shipping categories and shipping methods

Tool	Purpose	Required parameters	Optional parameters
`list_shipping_categories`	List shipping categories	-	`page`, `items_per_page`
`get_shipping_category`	Read one category	`code`	-
`create_shipping_category`	Create a category	`code`, `name`	`description`
`update_shipping_category`	Change a category	`code`	`name`, `description`
`list_shipping_methods`	List shipping methods	-	`page`, `items_per_page`, `archived`
`get_shipping_method`	Read a shipping method	`code`	-
`create_shipping_method`	Create a shipping method	`code`, `zone_code`, `calculator`, `translations`	`configuration`, `channel_codes`, `rules`, `enabled` (default `true`), `position`, `min_delivery_time_days`, `max_delivery_time_days`
`update_shipping_method`	Change a shipping method	`code`	`zone_code`, `calculator`, `configuration`, `translations`, `channel_codes`, `rules`, `enabled`, `position`, `min_delivery_time_days`, `max_delivery_time_days`
`archive_shipping_method`	Archive a shipping method (instead of deleting)	`code`	-
`restore_shipping_method`	Restore an archived shipping method	`code`	-

Shipping categories are not translatable (name and description are plain fields) and cannot be linked to a shipping method through the API in this Sylius version.
calculator and rules[].type are not checked against a fixed list because Sylius' registry is extensible; Sylius itself rejects unknown values. Known are the calculators flat_rate, per_unit_rate (both with an amount per channel) and free (no configuration).
configuration and channel-dependent rules need an entry for every channel of the shop, not only the assigned ones, for example {"WEB": {"amount": 500}} (amount in cents).
On update_shipping_method, channel_codes, rules and configuration each replace the complete data, while translations are merged per locale and field.
Delivery time values are between 0 and 1000 days, the maximum must not be below the minimum.

Tax categories

Tool	Purpose	Required parameters	Optional parameters
`list_tax_categories`	List tax categories	-	`page`, `items_per_page`, `code`, `name` (each a case-insensitive substring)
`get_tax_category`	Read a tax category	`code`	-
`create_tax_category`	Create a tax category	`code`, `name`	`description`
`update_tax_category`	Change name or description	`code`	`name`, `description`

The code of a tax category is the value for tax_category_code on variants. The server deliberately does not manage tax rates.

Data from shop plugins

Tool	Purpose	Required parameters	Optional parameters
`list_product_marketplace_links`	List marketplace links	-	`product_code`, `page`, `items_per_page`
`get_product_marketplace_link`	Read a link	`link_id` (numeric)	-
`create_product_marketplace_link`	Create a link	`product_code`, `reference`	`type` (`amazon` or `shopware_store`), `amazon_domain`
`update_product_marketplace_link`	Change a link	`link_id`	`reference`, `type`, `amazon_domain`, `clear_amazon_domain`
`delete_product_marketplace_link`	Remove a link	`link_id`	-
`list_product_custom_input_fields`	List input field definitions	-	`product_code`, `page`, `items_per_page`
`get_product_custom_input_field`	Read a definition	`field_id` (numeric)	-

A marketplace link sends buyers of a product to Amazon or the Shopware Store instead of the cart. A product has at most one link. For Amazon, reference is the ASIN (10 characters), for shopware_store a https://store.shopware.com/... URL. Valid Amazon domains: de, com, co.uk, fr, it, es, nl, pl, se, ca. The product of a link can only be set on creation.
Input field definitions (for example engraving text, date, select) are read-only; creating and changing them is done in the Sylius admin.

What the tools do not do

Area	Behavior
Deleting	The only delete operation is `delete_product_marketplace_link`. The client rejects `DELETE` on all other resources, even where the API would offer it. Shipping methods are archived.
Orders, customers, promotions	No tools, and the path allowlist blocks them in addition.
Channels	Read-only.
Rollback	There is none. Objects already created remain if a later operation of a series fails.