Preislisten
Gib Firmen und Kunden eigene Preise - Prozent auf den Katalogpreis plus Festpreise pro Produkt - während dein Shop den Katalog weiter cacht.
Eine Preisliste - Gold, Silver, Dealer - gibt einer Gruppe von Käufern eigene Preise. Du weist sie einer Firma oder einem Kunden zu, und cmssy berechnet Warenkorb, Checkout und Bestellungen dieses Käufers serverseitig danach. Der Katalog, den ein Besucher liest, ändert sich nicht - deine Produktseiten bleiben anonym und cachebar.
Was eine Liste enthält
- Ein Prozentabschlag auf den Katalogpreis, -1000 bis 99,99 mit höchstens zwei Nachkommastellen; unter 0 ist es ein Aufschlag über den Katalogpreis (-10 = 10 % mehr). Er gilt für jedes Produkt, für das die Liste keinen Festpreis hat, und für jede Mengenstaffel dieses Produkts. Gespeichert wird er in Basispunkten, gerechnet in ganzen Zahlen: kaufmännisch gerundet auf eine ganze Minor-Einheit, ein kostenloses Produkt bleibt bei 0, ein bezahltes fällt nie unter 1 Minor-Einheit.
- Festpreise pro Produkt, in Minor-Einheiten, jeweils mit optionalen Mengenstaffeln. Ein Produkt mit Varianten bekommt einen Festpreis pro Variante, nie einen für das ganze Produkt. Ein Festpreis darf über dem Katalogpreis liegen - auch ein Vertragspreis ist ein Preis.
Ein Festpreis schlägt den Prozentabschlag; gibt es keins von beiden, zahlt der Käufer den Katalogpreis. Festpreise gibt es je Währung: Ein Produkt oder eine Variante hat in jeder Währung, in der es verkauft wird, eine eigene Zeile, und eine Zeile bepreist nur Warenkörbe in ihrer Währung. Der Prozentsatz geht vom Preis in der Währung des Warenkorbs ab. Zwischen Währungen wird nichts umgerechnet. Ein Festpreis für ein später entferntes Produkt oder eine entfernte Variante bepreist nichts; die Liste markiert ihn als entfernt, damit du ihn löschen kannst.
Zeitraum. Eine Liste kann einen Beginn (startsAt) und ein Ende (endsAt) haben, beide optional. Vor dem Beginn und ab dem Ende bepreist sie niemanden: Ihre Käufer zahlen Katalogpreise, und eine abgelaufene Firmenliste fällt nicht auf die eigene Liste eines Kunden zurück. Ein bereits mit der Liste bepreister Warenkorb wird beim nächsten Lesen neu bepreist, und ein Checkout zu den alten Preisen wird mit CART_REPRICED abgelehnt. Bestellungen behalten ihre Preise. Die Seite der Liste und PriceList.active zeigen, ob sie gerade gilt.
Wer nach welcher Liste zahlt
Eine Liste pro Käufer, nie zwei übereinander:
- Ein Kunde, der zu einer Firma gehört, zahlt immer nach der Liste der Firma - oder den Katalogpreis, wenn die Firma keine hat. cmssy lehnt es ab, so einem Kunden direkt eine Liste zuzuweisen: weise sie der Firma zu. Eine Liste, die der Kunde vor dem Firmenbeitritt hatte, wird ignoriert, solange er dazugehört.
- Ein Kunde ohne Firma kann eine eigene Liste haben - ein VIP oder ein einzelner Händler.
- Ein Gast zahlt den Katalogpreis.
Listen verwalten
Listen liegen unter Commerce → Preislisten. Lege eine mit Namen und Prozentsatz an und öffne sie dann, um Festpreise pro Produkt oder Variante hinzuzufügen. Das Löschen einer Liste entfernt ihre Festpreise und hebt die Zuweisung bei allen Firmen und Kunden auf; Bestellungen behalten den Namen, mit dem sie berechnet wurden.
Die Seite einer Liste hat einen Tab je Währung: die Standardwährung und jede zusätzliche Währung aus Einstellungen → Region und Steuern. Jeder Tab zeigt die Festpreise dieser Währung und ihre Anzahl, und ein in einem Tab angelegter Preis ist in dessen Währung. Eine Liste macht ein Produkt nicht in einer Währung verkäuflich: Ein Produkt ohne eigenen Preis in der Währung des Warenkorbs wird darin nicht verkauft, mit oder ohne Liste. Wie Währungen funktionieren, steht unter Commerce.
Zuweisen kannst du eine Liste auf der Seite des Kunden oder auf einem Firmen-Record in dessen Modell. Die Seite einer Liste zeigt unter Zugewiesen an, wer nach ihr zahlt: Firmen und Kunden, jeweils mit Link zum Record. Die Anmelde-E-Mail eines Kunden siehst du nur mit customers:view. Die Berechtigungen:
models:edit- Listen und ihre Festpreise anlegen, bearbeiten und löschen;models:viewliest sie.customers:manage- einer Firma oder einem Kunden eine Liste zuweisen.customers:viewreicht, um zu sehen, welche Listen es gibt.
Ein ERP-Sync schreibt Festpreise in großen Mengen: priceList.setEntries in der Admin-API schreibt bis zu 1000 auf einmal, alles oder nichts - eine fehlerhafte Zeile lehnt den ganzen Aufruf ab, und der Fehler nennt jede fehlerhafte Zeile mit Index.
Aus Spotlight und dem MCP-Server
Spotlight und der MCP-Server (ab 0.108.0) bieten dieselben Operationen mit denselben Berechtigungen: list_price_lists, get_price_list, create_price_list, update_price_list, delete_price_list, set_price_list_entry, set_price_list_entries, remove_price_list_entries, set_customer_price_list und set_company_price_list.
set_price_list_entry und set_price_list_entries nehmen currency je Zeile: weggelassen ist die Zeile der Standardwährung, eine zusätzliche Währung schreibt ihre eigene Zeile. remove_price_list_entries mit currency entfernt nur die Zeile dieser Währung, ohne es alle Zeilen des Produkts oder der Variante in allen Währungen.
Wie ein Preis entsteht
cmssy berechnet eine Position in dieser Reihenfolge:
- Katalogpreis - der Preis des Produkts oder der Variante in der Währung des Warenkorbs. Ein Produkt ohne Preis in dieser Währung wird darin nicht verkauft.
- Preisliste - die Liste des Käufers, falls vorhanden und innerhalb ihres Zeitraums. Ein Festpreis für Produkt oder Variante in der Währung des Warenkorbs gewinnt, und seine eigenen Mengenstaffeln ersetzen die des Produkts. Sonst geht der Prozentsatz der Liste vom Preis und von jeder Staffel ab.
- Mengenstaffel - die günstigste Staffel, die die Menge erreicht, nie über dem Preis aus Schritt 2.
- Rabattcode - geht von der Warenkorbsumme ab, nicht von einer Position.
- Steuer - Preise sind inklusive oder exklusive Steuer, eine Einstellung für den ganzen Workspace.
Warenkorb, Checkout und account.prices rechnen mit demselben Code, ein Shop berechnet also nie selbst einen Preis. Jeder berechnete Preis nennt, was ihn gesetzt hat: catalogue (keine Liste gilt), price_list_entry (ein Festpreis) oder price_list_percent.
Preise im Headless-Shop
Der Preis eines Käufers ist persönlich, deshalb kommt er nie in eine Produktabfrage - sonst wäre jeder Katalogabruf mitgliedsabhängig und nicht mehr cachebar. Das Muster stattdessen:
- Katalog anonym rendern und cachen. Produktlisten und Produktseiten lesen
public.model.recordsgenau wie für einen abgemeldeten Besucher, mit Katalogpreisen. Schlüssle eine gecachte Seite nie nach dem Mitglied. - Nach der Anmeldung die Käuferpreise darüberlegen. Frag
account.pricesnach den Produkten auf dem Bildschirm - höchstens 100 Einträge pro Aufruf - mit demAuthorization: Bearer <accessToken>des Mitglieds. Ohne Mitglieds-Token wird der Aufruf abgelehnt. - Diese Antwort nie für andere Besucher cachen. Kein geteilter Fetch-Cache, kein CDN. Lies sie in einer dynamischen Route oder einer Server Action und setze die Preise in die bereits gerenderte Seite ein.
query BuyerPrices($workspaceId: ID!, $items: [PriceQueryItem!]!) {
account {
prices(workspaceId: $workspaceId, items: $items) {
recordId
variantKey
currency
price
priceMax
listed
basePrice
source
tiers { minQty price }
}
}
}Jeder Eintrag ist { recordId, variantKey }, wobei variantKey die ProductVariant.id der Delivery-API ist. Lass ihn bei einem Produkt mit Varianten weg, um eine Spanne zu bekommen: price ist der niedrigste, priceMax der höchste Preis, tiers ist leer - der "ab"-Preis einer Listing-Karte. Beträge sind in Minor-Einheiten. listed ist true, wenn eine Liste den Preis gesetzt hat, für ein "Dein Preis"-Label. basePrice ist der Katalogpreis vor der Liste, für einen durchgestrichenen "Statt"-Preis, und source sagt, was price gesetzt hat. Bei einer Spanne beschreiben beide die günstigste Variante. Ein unbekanntes oder verborgenes Produkt fehlt in der Antwort - ordne Zeilen über recordId und variantKey zu, nicht über die Position.
Für ein Badge wie "Deine Preise: Dealer Gold" liest du den Namen der Liste aus dem Profil des Mitglieds. Er ist null, wenn keine Liste gilt, und ein Mitglied sieht immer nur seine eigene:
query MyPriceList($workspaceId: ID!) {
account {
profile(workspaceId: $workspaceId) {
priceList { name }
}
}
}Mit @cmssy/core 19.11.0 oder neuer schickt getBuyerPrices die Preisabfrage für dich.
Eine Liste nach dem Preis des Käufers sortiert
Um eine Kategorie nach dem zu sortieren, filtern oder blättern, was der Käufer zahlt - "Preis aufsteigend", "unter 50" -, frag account.catalogPrices. Es nimmt dieselben filter, stockState, sku und locale wie public.model.records, dazu priceMin/priceMax in Minor-Einheiten, sort (PRICE_ASC oder PRICE_DESC), limit und offset. Es liefert nur Preiszeilen, in Reihenfolge: die Records selbst liest du aus dem gecachten Katalog mit public.model.recordsByIds.
query BuyerListing($workspaceId: ID!, $offset: Int) {
account {
catalogPrices(
workspaceId: $workspaceId
modelSlug: "products"
filter: { category: "tools" }
priceMax: 5000
sort: PRICE_ASC
limit: 24
offset: $offset
) {
total
hasMore
items { recordId price priceMax currency source }
}
}
}Ein Produkt mit Varianten wird nach seiner günstigsten Variante bepreist. Jede Zeile ist in der Währung des Kanals. Eine Liste mit mehr als 2000 Produkten wird abgelehnt, bis filter sie eingrenzt. Jeder Aufruf belastet das Delivery-Budget wie die 2000 Records, die er durchsuchen kann.
Jede Delivery-Antwort, die mit einem Mitglieds-Token gelesen wird, trägt Cache-Control: private, no-store. Halte dich auch auf deinem Server daran: lege die Preise eines Mitglieds nie in einen geteilten Fetch-Cache.
Warenkorb und Checkout
Der Warenkorb wird für den berechnet, der ihn liest. Bei jedem Lesen und Schreiben berechnet cmssy die Positionen neu, die für eine andere Liste berechnet wurden - ein Gast meldet sich an, ein Mitglied meldet sich ab, eine Liste wird zugewiesen oder entfernt. unitPrice ist der Betrag, der berechnet wird; snapshot.basePrice ist der Katalogpreis vor Liste und Mengenstaffeln, für einen durchgestrichenen "statt"-Preis. Er ist null bei einer Position, die vor den Preislisten hinzugefügt wurde.
query CartPrices($workspaceId: ID!) {
cart {
get(workspaceId: $workspaceId) {
items {
id
quantity
unitPrice
currentPrice
priceMismatch
snapshot { price basePrice currency }
}
subtotal
}
}
}Ändern sich Prozentsatz oder Festpreise einer Liste, werden Warenkörbe, die bereits danach berechnet sind, nicht neu berechnet. Die Position zeigt den neuen Preis in currentPrice mit priceMismatch: true, und der Checkout berechnet, was im Warenkorb steht.
Wenn der Checkout ablehnt
Hat die Neuberechnung den Warenkorb verändert, seit der Käufer ihn zuletzt gesehen hat, lehnt cart.checkout ab, statt einen Betrag zu berechnen, den niemand angezeigt hat. Der Grund steht in extensions.reason des GraphQL-Fehlers:
CART_REPRICED(CodeBAD_USER_INPUT) - die Preise des Käufers haben sich geändert. Der Warenkorb ist bereits mit den neuen Preisen gespeichert: lies ihn erneut, zeig die neuen Summen, lass den Käufer bestätigen und rufcart.checkoutnoch einmal auf.CART_CURRENCY_CHANGED(CodeCONFLICT) - eine Position würde jetzt in einer anderen Währung als der Warenkorb berechnet;extensions.itemIdnennt sie. Entferne die Position und füge das Produkt erneut hinzu.
Mit @cmssy/core 19.11.0 oder neuer liefert checkoutErrorReason(error) beide Gründe.
Rabattcodes wirken zusätzlich zur Liste: Ein Code wird von der nach Liste berechneten Zwischensumme abgezogen, und auch der Mindestbestellwert eines Codes wird an ihr gemessen.
Bestellungen
Eine Bestellung friert die Liste ein, nach der sie berechnet wurde. Ihr Name steht an der Bestellung im Admin und in get_order und bleibt, auch wenn die Liste umbenannt oder gelöscht wird. Auf jeder Bestellposition:
price- der berechnete Stückpreis, mit Liste und Mengenstaffel.listPrice- der Katalog-Stückpreis vor Liste und Mengenstaffeln. Ohne Liste ist es der Preis vor Mengenstaffeln, wie bisher; bei einem Vertragspreis über dem Katalog kann er unterpriceliegen.listUnitPrice- der Stückpreis nach der Liste, vor Mengenstaffeln.priceSource- was den Preis gesetzt hat:catalogue,price_list_entryoderprice_list_percent.
Bestellungen, die aufgegeben wurden, bevor diese beiden Felder gespeichert wurden, haben keines davon. get_order liefert sie ab MCP-Server 0.111.0.
Bearbeitest du eine Bestellung im Admin, werden ihre Produktpositionen mit den aktuellen Werten der eingefrorenen Liste neu berechnet, oder zu Katalogpreisen, wenn die Liste gelöscht wurde. Eine manuelle Bestellung wird nach der Liste des gewählten Kunden berechnet.
Nächste Schritte
- Commerce - Warenkorb, Checkout und Bestellungen, die eine Liste bepreist.
- Kunden - Kunden und Firmen, denen du eine Liste zuweist.
- Mitglieder-Authentifizierung - Anmeldung und das Access-Token, das
account.pricesbraucht.