Products & PIM — API and MCP
Overview
This area exposes 74 operations. Each of them is at the same time an MCP tool.
This area is behind the module switch module.products. With the module off, these operations answer 404.
Operations
| Method | Path | Purpose | Permission | Parameters |
|---|---|---|---|---|
GET | /api/v1/price-lists | Collection of PriceList | products.pricing.manage · products.catalog.view | page, scope, customerId, active, q, brandId |
POST | /api/v1/price-lists | Create a PriceList | products.pricing.manage | + body |
DELETE | /api/v1/price-lists/{ulid} | Delete a PriceList | products.pricing.manage | ulid |
GET | /api/v1/price-lists/{ulid} | Read one PriceList | products.catalog.view | ulid |
PATCH | /api/v1/price-lists/{ulid} | Update a PriceList | products.pricing.manage | ulid, + body |
GET | /api/v1/product-categories | Collection of ProductCategory | products.catalog.view · products.catalog.manage | kind, parentId, q |
POST | /api/v1/product-categories | Create a ProductCategory | products.catalog.manage | + body |
DELETE | /api/v1/product-categories/{ulid} | Delete a ProductCategory | products.catalog.manage | ulid |
GET | /api/v1/product-categories/{ulid} | Read one ProductCategory | products.catalog.view · products.catalog.manage | ulid |
PATCH | /api/v1/product-categories/{ulid} | Update a ProductCategory | products.catalog.manage | ulid, + body |
POST | /api/v1/product-categories/{ulid}/move | Move product category — Move product category. Dedicated action endpoint — not a standard CRUD create. | products.catalog.manage | ulid, + body |
POST | /api/v1/product-configurations/preview | Konfiguration eines Artikels prüfen (Vorschau) — Prüft eine Auswahl (selections: [{optionUlid, qty}]) gegen den Konfigurator des Artikels productId, rechnet den Aufpreis und den Einzelpreis (Grundpreis aus der Preis-Engine für customerId/brandId/qty + Aufpreise) und nennt Verstöße — ohne etwas zu speichern. Mit fxRate (am Beleg eingefrorener Kurs, Fremdwährung je 1 EUR) steht unitPriceAmount in Belegwährung. Mit cartQty (belegweite Menge desselben Artikels) greift eine Staffel mit Basis cart_total; ohne die Angabe zählt qty. | products.catalog.view · products.catalog.manage | + body |
GET | /api/v1/product-delivery-times | Collection of ProductDeliveryTime | products.catalog.view · products.catalog.manage | page, active |
GET | /api/v1/product-entitlement-rules | Collection of ProductEntitlementRule | products.catalog.view · products.catalog.manage | page, productId, variantId, featureKey |
POST | /api/v1/product-entitlement-rules | Create a ProductEntitlementRule | products.catalog.manage | + body |
DELETE | /api/v1/product-entitlement-rules/{ulid} | Delete a ProductEntitlementRule | products.catalog.manage | ulid |
GET | /api/v1/product-entitlement-rules/{ulid} | Read one ProductEntitlementRule | products.catalog.view | ulid |
PATCH | /api/v1/product-entitlement-rules/{ulid} | Update a ProductEntitlementRule | products.catalog.manage | ulid, + body |
GET | /api/v1/product-facets | Katalog-Facetten mit Trefferzahl — Facetten der Artikelliste: je filterbarer, aktiver Eigenschaftsgruppe die aktiven Optionen mit Trefferzahl, dazu je Hersteller die Trefferzahl. Nimmt dieselben Filter wie GET /v1/products. Eine Facette zählt ohne ihre eigene Auswahl, damit weitere Optionen derselben Gruppe wählbar bleiben. Nicht filterbare Eigenschaften erscheinen nicht. | products.catalog.view · products.catalog.manage | q, type, status, active, brandId, categoryUlid, categoryId, streamUlid, sellable, configurable, barcode, productKind, isOwnProduct, manufacturerUlid, propertyOptionUlids, locale |
GET | /api/v1/product-manufacturers | Collection of ProductManufacturer | products.catalog.view · products.catalog.manage | page, active, q |
POST | /api/v1/product-manufacturers | Create a ProductManufacturer | products.catalog.manage | + body |
DELETE | /api/v1/product-manufacturers/{ulid} | Delete a ProductManufacturer | products.catalog.manage | ulid |
GET | /api/v1/product-manufacturers/{ulid} | Read one ProductManufacturer | products.catalog.view · products.catalog.manage | ulid |
PATCH | /api/v1/product-manufacturers/{ulid} | Update a ProductManufacturer | products.catalog.manage | ulid, + body |
GET | /api/v1/product-property-groups | Collection of ProductPropertyGroup | products.catalog.view · products.catalog.manage | page, active, variantForming, q |
POST | /api/v1/product-property-groups | Create a ProductPropertyGroup | products.catalog.manage | + body |
DELETE | /api/v1/product-property-groups/{ulid} | Delete a ProductPropertyGroup | products.catalog.manage | ulid |
GET | /api/v1/product-property-groups/{ulid} | Read one ProductPropertyGroup | products.catalog.view · products.catalog.manage | ulid |
PATCH | /api/v1/product-property-groups/{ulid} | Update a ProductPropertyGroup | products.catalog.manage | ulid, + body |
GET | /api/v1/product-stock | Collection of ProductStock | products.stock.view · products.stock.manage | page, belowReorder, onlyUnvalued, q |
PATCH | /api/v1/product-stock-take-lines/{ulid} | Updates the StockTakeLine resource. — Trägt den gezählten Ist-Bestand ein. version MUSS die zuvor gelesene Version sein — sonst 409 (ein zweiter Zählender war schneller). | products.stock.manage | ulid, + body |
GET | /api/v1/product-stock-takes | Collection of StockTake | products.stock.view · products.stock.manage | page, status, type, brandId |
POST | /api/v1/product-stock-takes | Create a StockTake | products.stock.manage | + body |
GET | /api/v1/product-stock-takes/{ulid} | Read one StockTake | products.stock.view · products.stock.manage | ulid |
PATCH | /api/v1/product-stock-takes/{ulid} | Update a StockTake | products.stock.manage | ulid, + body |
POST | /api/v1/product-stock-takes/{ulid}/adopt-expected | Aktuelle Bestände übernehmen — Übernimmt für alle NOCH UNGEZÄHLTEN Zeilen den eingefrorenen Sollstand als Zählwert — die Aussage „hier stimmt es", und damit ohne Differenz. Das ist die zweite Hälfte der Zettelinventur: auf Papier gezählt wird nur, was auffällt, und ohne diese Übernahme müsste trotzdem jede der womöglich tausenden übrigen Zeilen einzeln bestätigt werden, weil ungezählte Zeilen das Buchen blockieren. Bereits gezählte Zeilen bleiben unberührt — eine Übernahme darf eine Feststellung nie überschreiben. Bei blinder Zählung nicht verfügbar (422). | products.stock.manage | ulid, + body |
POST | /api/v1/product-stock-takes/{ulid}/book | Inventurdifferenzen buchen — Bucht die Differenzen als Bewegungsart inventory. FINAL — nicht rückgängig. Scheitert, solange ungezählte Zeilen offen sind. Läuft unter Zeilensperre in EINER Transaktion und bucht genau einmal; ein Sperr-Konflikt ist 409 (erneut versuchen). Über X-Idempotency-Key benennbar: die Wiederholung desselben Vorgangs bucht nichts nach. | products.stocktake.book | ulid, + body |
POST | /api/v1/product-stock-takes/{ulid}/cancel | Cancel product stock take — Cancel product stock take. Dedicated action endpoint — not a standard CRUD create. | products.stock.manage | ulid, + body |
POST | /api/v1/product-stock-takes/{ulid}/finish | Zählung abschließen — Schließt die Zählung ab (counting → counted). Differenzen sind jetzt prüfbar, gebucht ist noch nichts. | products.stock.manage | ulid, + body |
GET | /api/v1/product-stock-takes/{ulid}/lines | Collection of StockTakeLine | products.stock.view · products.stock.manage | ulid, page, onlyDifferences, onlyUncounted, productId, warehouseId, binId |
POST | /api/v1/product-stock-takes/{ulid}/populate | Zählzeilen anlegen und Sollstand einfrieren — Legt die Zählzeilen an und friert den Sollstand je Artikel UND Ort ein. Der Zuschnitt der Inventur (scope: warehouseIds, categoryIds, binTypes, productIds, conditions) wird dabei ausgewertet: bei aktivem Mehrlager entsteht eine Zeile je (Artikel, Lager), bei gesetzten binTypes eine Zeile je belegtem Lagerplatz. Optional productIds im Rumpf grenzt zusätzlich ein (Schnittmenge mit dem Zuschnitt); ohne Mehrlager-Add-on wie bisher eine Zeile je lagergeführtem Artikel. | products.stock.manage | ulid, + body |
GET | /api/v1/product-stock-takes/{ulid}/protocol | Retrieves a StockTake resource. — Zählprotokoll als PDF: je Zeile Soll, Ist, Differenz, Zeitstempel und Zähler — das Beweisdokument der Inventur. | products.stock.view · products.stock.manage | ulid |
POST | /api/v1/product-stock-takes/{ulid}/start | Zählung freigeben — Gibt die Zählung frei (draft → counting). Ab hier ist der Zuschnitt festgelegt. Scheitert mit 409, solange im Zuschnitt noch offene Picklisten laufen: der Zettel nennt dann die Menge VOR dem Griff, das Buch die danach — und die Inventur bucht anschließend eine Differenz, die es nie gab. | products.stock.manage | ulid, + body |
GET | /api/v1/product-stock-value | Retrieves a ProductStockValue resource. — Bestandswert nach gleitendem Durchschnitt: Gesamtsumme, Zeilen je Artikel und Zustand und — ausdrücklich — die Zahl der Artikel ohne bekannten Einstandspreis. B-Ware (Zustand ≠ Neuware) steht als eigene Zeile zum Durchschnitt der Neuware desselben Artikels (keine automatische Abwertung); Summen in conditionOnHand/conditionValueAmount/conditionUnvaluedOnHand. Negativer Bestand wird mit 0 bewertet (kein Abzug vom Gesamtwert) und in negativeStockLines/negativeStockOnHand ausgewiesen. | products.stock.view · products.stock.manage | categoryId, onlyUnvalued, limit |
GET | /api/v1/product-stock/{productUlid} | Read one ProductStock | products.stock.view · products.stock.manage | productUlid |
PATCH | /api/v1/product-stock/{productUlid} | Update a ProductStock | products.stock.manage | productUlid, + body |
POST | /api/v1/product-stock/{productUlid}/adjust | Bestand korrigieren — Korrigiert den Bestand des Artikels und schreibt die Bewegung in das append-only Bestandsjournal (Herkunft manual). Ein Negativ-Bestand wird abgewiesen (409), solange er nicht ausdrücklich erlaubt ist. | products.stock.manage | productUlid, + body |
GET | /api/v1/product-stream-fields | Collection of ProductStreamField | products.catalog.view · products.catalog.manage | — |
GET | /api/v1/product-streams | Collection of ProductStream | products.catalog.view · products.catalog.manage | page, q |
POST | /api/v1/product-streams | Create a ProductStream | products.catalog.manage | + body |
DELETE | /api/v1/product-streams/{ulid} | Delete a ProductStream | products.catalog.manage | ulid |
GET | /api/v1/product-streams/{ulid} | Read one ProductStream | products.catalog.view | ulid |
PATCH | /api/v1/product-streams/{ulid} | Update a ProductStream | products.catalog.manage | ulid, + body |
GET | /api/v1/product-variants | Collection of ProductVariant | products.catalog.view · products.catalog.manage | page, productId |
POST | /api/v1/product-variants | Create a ProductVariant | products.catalog.manage | + body |
DELETE | /api/v1/product-variants/{ulid} | Delete a ProductVariant | products.catalog.manage | ulid |
GET | /api/v1/product-variants/{ulid} | Read one ProductVariant | products.catalog.view · products.catalog.manage | ulid |
PATCH | /api/v1/product-variants/{ulid} | Update a ProductVariant | products.catalog.manage | ulid, + body |
GET | /api/v1/product-versions | Collection of ProductVersion | products.catalog.view · products.catalog.manage | page, productId |
POST | /api/v1/product-versions | Create a ProductVersion | products.catalog.manage | + body |
DELETE | /api/v1/product-versions/{ulid} | Delete a ProductVersion | products.catalog.manage | ulid |
GET | /api/v1/product-versions/{ulid} | Read one ProductVersion | products.catalog.view · products.catalog.manage | ulid |
PATCH | /api/v1/product-versions/{ulid} | Update a ProductVersion | products.catalog.manage | ulid, + body |
GET | /api/v1/products | Collection of Product | products.catalog.view · products.catalog.manage | page, type, status, brandId, categoryId, categoryUlid, isOwnProduct, active, productKind, sellable, configurable, streamUlid, q, barcode, manufacturerUlid, propertyOptionUlids, order[name], order[defaultPriceAmount], customerId |
POST | /api/v1/products | Create a Product | products.catalog.manage | + body |
POST | /api/v1/products/bulk | Create a ProductBulkAction | products.catalog.manage | + body |
POST | /api/v1/products/duplicate | Create a ProductDuplicate | products.catalog.manage | + body |
POST | /api/v1/products/import | Create a ProductImport | products.catalog.manage | + body |
DELETE | /api/v1/products/{ulid} | Delete a Product | products.catalog.manage | ulid |
GET | /api/v1/products/{ulid} | Read one Product | products.catalog.view · products.catalog.manage | ulid |
PATCH | /api/v1/products/{ulid} | Update a Product | products.catalog.manage | ulid, + body |
POST | /api/v1/products/{ulid}/generate-variants | Varianten aus den Achsen erzeugen — Spannt aus den Achsen des Variantensets das kartesische Produkt der aktiven Optionen auf und legt fehlende Varianten idempotent an. Ein Rumpf ist nicht nötig. | products.catalog.manage | ulid, + body |
GET | /api/v1/stock-condition-changes | Collection of StockConditionChange | products.stock.view · products.stock.manage · products.stock.change_condition | productId, warehouseId |
POST | /api/v1/stock-condition-changes | Artikelzustand umbuchen — Bucht qty Stück eines Artikels vom Zustand fromCondition in den Zustand toCondition (new, refurbished, used, damaged) — z. B. geprüfte B-Ware wird Neuware. Eigene Bewegungsart im Bestandsjournal, Bewertung unverändert. Nur freier Bestand des Quellzustands ist umbuchbar (sonst 409). Bei Mehrlager optional warehouseId/binId (Abgang und Zugang am selben Platz). | products.stock.change_condition | + body |
Purpose texts that do not follow the standard pattern are taken verbatim from the interface description in the code.