Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Charge a flat commission fee for every unit sold
Damian Legawiec0ef6d989b905
diff --git a/docs/plans/6.0-multi-vendor-marketplace.md b/docs/plans/6.0-multi-vendor-marketplace.mdindex 4a0b603c49..586900332f 100644--- a/docs/plans/6.0-multi-vendor-marketplace.md+++ b/docs/plans/6.0-multi-vendor-marketplace.md@@ -90,7 +90,9 @@ Two specifics worth copying rather than inventing. Tiering is expressed as thres**`include_shipping` on the rate** (default `false`): when the resolved rate has it, the same calculation also runs against the vendor order's delivery amounts, persisting a fulfillment-scoped `CommissionLine`. The surveyed OSS competitor commissions shipping via a global-rate-only flag, and Amazon-style referral fees include it; the legacy module was items-only (its order-level "reverse fee" only prorates *item* commission on whole-order refunds — shipping is excluded from its base). Ours is per-rate — strictly more flexible than a global-only flag, and off by default so legacy behavior is preserved.-**Percentage only (RESOLVED 2026-08-17, shipped).** A flat fee cannot charge delivery: the fee is charged once per sale, so applying the same amount to a parcel bills one sale twice — a £5 rate on a three-item order was charging £20. The flag is refused on a `fixed` rate and the toggle is hidden for one, matching the surveyed OSS engine, which reads its shipping flag off the percentage default only. A marketplace wanting a flat charge on delivery states it as its own rate.+**Percentage only (RESOLVED 2026-08-17, shipped).** A flat fee cannot charge delivery. A percentage answers "what share of this money is ours?", and postage is money; a flat fee answers "what do we charge for handling this?", and the parcel is part of the sale already being charged for — so a £5 rate on a three-item order was billing £20. The flag is refused on a `fixed` rate and the toggle is hidden for one, matching the surveyed OSS engine, which reads its shipping flag off the percentage default only. A marketplace wanting a flat charge on delivery states it as its own rate, which composes correctly because rates resolve independently.++**Flat fees multiply by quantity (RESOLVED 2026-08-17, shipped).** A flat fee is charged per unit sold, not once per line — three cameras in one line earn the same as three bought one at a time. Charging per line would have let the shopper set the fee through cart grouping alone, and would have made quantity matter under a percentage but not under a flat fee, so switching a rate between the two kinds silently changed more than the number. **No per-line/per-order toggle**, for two reasons. Per-unit is what merchants assume — the large marketplaces state their flat charges as "per unit" and "per item", and that is the industry vocabulary. And a per-*order* mode has no coherent answer in this engine, because rates resolve per line: a basket with a camera at 8% and a book at £2 has no single rate to charge the order with. The enterprise platform reviewed for this reaches the same conclusion structurally — its per-order charges are a separate seller-fee concept in its ledger, never a mode of its commission engine, whose order-level total is documented only as the sum of its lines. A per-order platform charge, if wanted later, is its own entity rather than a flag here. The floor and cap still apply per line, to the multiplied total — which is the first time they do useful work on a flat rate, since one could not previously exceed itself.**Per-currency amounts (RESOLVED 2026-08-17, shipped).** A flat fee's amounts live in `spree_commission_rate_values`, one row per currency, rather than a single `currency` column on the rate — which had meant a dollar-priced rate silently not applying to a euro sale, so a seller's rate depended on how the buyer paid. A rate is skipped for a currency it states no amount in and the sale falls to the next rate: converting one currency's figure into another would invent a fee nobody set. `currency` survives on the rate for one purpose only — naming the currency a *percentage* rate's floor or cap is stated in.diff --git a/packages/dashboard/src/locales/ar.json b/packages/dashboard/src/locales/ar.jsonindex 55939aa0af..3fecc51bc0 100644--- a/packages/dashboard/src/locales/ar.json+++ b/packages/dashboard/src/locales/ar.json@@ -1711,7 +1711,7 @@"help": "تُتجاهل النسب المعطّلة عند الاحتساب."},"amounts": {- "help": "تُحتسب لكل عملية بيع. العملة المتروكة فارغة لا تحتسبها هذه النسبة، وتنتقل تلك المبيعات إلى النسبة التالية.",+ "help": "تُحتسب عن كل وحدة مباعة. العملة المتروكة فارغة لا تحتسبها هذه النسبة، وتنتقل تلك المبيعات إلى النسبة التالية.","label": "رسوم ثابتة"},"bounds": {diff --git a/packages/dashboard/src/locales/de.json b/packages/dashboard/src/locales/de.jsonindex e78797e623..1c72b114cd 100644--- a/packages/dashboard/src/locales/de.json+++ b/packages/dashboard/src/locales/de.json@@ -1700,7 +1700,7 @@"help": "Deaktivierte Sätze werden bei der Berechnung übersprungen."},"amounts": {- "help": "Pro Verkauf berechnet. Eine leer gelassene Währung berechnet dieser Satz nicht — solche Verkäufe fallen an den nächsten Satz.",+ "help": "Wird für jede verkaufte Einheit berechnet. Eine leer gelassene Währung berechnet dieser Satz nicht — solche Verkäufe fallen an den nächsten Satz.","label": "Pauschale"},"bounds": {diff --git a/packages/dashboard/src/locales/en.json b/packages/dashboard/src/locales/en.jsonindex bfb5f490bb..10480525fd 100644--- a/packages/dashboard/src/locales/en.json+++ b/packages/dashboard/src/locales/en.json@@ -1700,7 +1700,7 @@"help": "Disabled rates are skipped when charging a sale."},"amounts": {- "help": "Charged per sale. A currency left empty is one this rate does not charge — those sales fall to the next rate.",+ "help": "Charged for every unit sold. A currency left empty is one this rate does not charge — those sales fall to the next rate.","label": "Flat fee"},"bounds": {diff --git a/packages/dashboard/src/locales/fr.json b/packages/dashboard/src/locales/fr.jsonindex 07c9714c67..f381177212 100644--- a/packages/dashboard/src/locales/fr.json+++ b/packages/dashboard/src/locales/fr.json@@ -1700,7 +1700,7 @@"help": "Les taux désactivés sont ignorés lors de la facturation."},"amounts": {- "help": "Facturé par vente. Une devise laissée vide n'est pas facturée par ce taux — ces ventes passent au taux suivant.",+ "help": "Facturé pour chaque unité vendue. Une devise laissée vide n'est pas facturée par ce taux — ces ventes passent au taux suivant.","label": "Montant fixe"},"bounds": {diff --git a/packages/dashboard/src/locales/pl.json b/packages/dashboard/src/locales/pl.jsonindex 394fc91e01..89986ca5a2 100644--- a/packages/dashboard/src/locales/pl.json+++ b/packages/dashboard/src/locales/pl.json@@ -1714,7 +1714,7 @@"help": "Wyłączone stawki są pomijane przy naliczaniu."},"amounts": {- "help": "Naliczana za sprzedaż. Waluta pozostawiona pusta nie jest naliczana przez tę stawkę — takie sprzedaże trafiają do następnej.",+ "help": "Naliczana za każdą sprzedaną sztukę. Waluta pozostawiona pusta nie jest naliczana przez tę stawkę — takie sprzedaże trafiają do następnej.","label": "Opłata stała"},"bounds": {diff --git a/packages/dashboard/src/locales/zh-CN.json b/packages/dashboard/src/locales/zh-CN.jsonindex d3c52de21f..43c7271515 100644--- a/packages/dashboard/src/locales/zh-CN.json+++ b/packages/dashboard/src/locales/zh-CN.json@@ -1697,7 +1697,7 @@"help": "停用的费率在计费时会被跳过。"},"amounts": {- "help": "按每笔销售收取。留空的货币不由该费率收费,这些销售将适用下一条费率。",+ "help": "按售出的每件商品收取。留空的货币不由该费率收费,这些销售将适用下一条费率。","label": "固定费用"},"bounds": {diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/settings/commission-rates.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/settings/commission-rates.tsxindex 5519882cc9..a15665ff89 100644--- a/packages/dashboard/src/routes/_authenticated/$storeId/settings/commission-rates.tsx+++ b/packages/dashboard/src/routes/_authenticated/$storeId/settings/commission-rates.tsx@@ -441,9 +441,9 @@ function CommissionRateFormFields({ form }: { form: UseFormReturn<CommissionRate<FieldError errors={[errors.commission_tax_rate]} /></Field>- {/* A flat fee is charged once per sale, so there is nothing for it to- charge on a parcel — the same amount again would bill one sale- twice. A marketplace wanting that states it as its own rate. */}+ {/* A parcel is part of the sale a flat fee already charges for, so the+ same amount again would bill one sale twice. A marketplace wanting a+ flat charge on delivery states it as its own rate. */}{kind === 'percentage' && (<ToggleFieldform={form}diff --git a/spree/core/app/services/spree/commissions/calculate_line.rb b/spree/core/app/services/spree/commissions/calculate_line.rbindex 5eda3381e2..6a1a230761 100644--- a/spree/core/app/services/spree/commissions/calculate_line.rb+++ b/spree/core/app/services/spree/commissions/calculate_line.rb@@ -97,13 +97,17 @@ module Spreeprivate- # A fixed rate is a flat fee for the sale, charged once however many units- # it covered — quantity is what a percentage already accounts for through- # the base.+ # Both kinds scale with quantity: a percentage through the base, which is+ # already the line's total, and a flat fee by multiplying.def charge_for(rate, subject, currency)- # A flat fee is charged in the sale's own currency; the rate only got- # this far because it states an amount there.- return clamp(rate, rate.amount_for(currency).to_d) if rate.fixed?+ # A flat fee is charged per unit sold, in the sale's own currency — the+ # rate only got this far because it states an amount there. Charging it+ # once per line would let the shopper decide the fee: three cameras+ # bought together would earn a third of three bought separately.+ #+ # A fulfillment has no quantity, and never reaches this branch — a flat+ # rate is barred from charging delivery.+ return clamp(rate, rate.amount_for(currency).to_d * subject.quantity) if rate.fixed?clamp(rate, self.class.base_for(rate, subject) * rate.value / 100)enddiff --git a/spree/core/config/locales/en.yml b/spree/core/config/locales/en.ymlindex 38e5729cf3..0157514170 100644--- a/spree/core/config/locales/en.yml+++ b/spree/core/config/locales/en.yml@@ -903,7 +903,7 @@ en:exactly_one_of_cart_or_order: must belong to exactly one of cart or orderexactly_one_of_line_item_or_fulfillment: must be charged against exactly one of a line item or a fulfillmentexactly_one_tax_identifier_owner: must belong to exactly one of customer, cart or order- flat_fee_cannot_charge_delivery: is not available on a flat fee, which is charged once per sale — add a separate rate to charge delivery+ flat_fee_cannot_charge_delivery: is not available on a flat fee, which already charges for the sale the delivery belongs to — add a separate rate to charge deliveryintegration_connection_failed: could not connect with the saved credentialsintegration_type_not_registered: is not a registered integrationinvalid_commission_rule: is not a commission rule kind this store hasdiff --git a/spree/core/spec/models/spree/commission_rate_spec.rb b/spree/core/spec/models/spree/commission_rate_spec.rbindex 9255390976..cc3ee6c56a 100644--- a/spree/core/spec/models/spree/commission_rate_spec.rb+++ b/spree/core/spec/models/spree/commission_rate_spec.rb@@ -104,7 +104,7 @@ RSpec.describe Spree::CommissionRate, type: :model dorate = build(:commission_rate, :fixed, store: store, include_shipping: true)expect(rate).not_to be_valid- expect(rate.errors[:include_shipping].first).to match(/once per sale/)+ expect(rate.errors[:include_shipping].first).to match(/already charges for the sale/)endit 'retires a currency dropped from the set' dodiff --git a/spree/core/spec/services/spree/commissions/calculate_line_spec.rb b/spree/core/spec/services/spree/commissions/calculate_line_spec.rbindex f6ea008390..d865822a7e 100644--- a/spree/core/spec/services/spree/commissions/calculate_line_spec.rb+++ b/spree/core/spec/services/spree/commissions/calculate_line_spec.rb@@ -26,11 +26,34 @@ RSpec.describe Spree::Commissions::CalculateLine doexpect(call(line_item: three).amount).to eq(30)end- it 'charges a fixed rate once, however many units it covered' do+ # Charging a flat fee once per line would let the shopper set the fee: three+ # cameras in one line would earn a third of three bought one at a time.+ it 'charges a flat fee for every unit sold' dothree = create(:line_item, order: order, price: 100, quantity: 3)- fixed = create(:commission_rate, :fixed, store: store, value: 2.5, currency: 'USD')+ fixed = create(:commission_rate, :fixed, store: store, amounts: { 'USD' => 2.5 })- expect(call(rate: fixed, line_item: three).amount).to eq(2.5)+ expect(call(rate: fixed, line_item: three).amount).to eq(7.5)+ end++ # The invariant behind charging per unit: what the marketplace earns is a+ # property of the sale, not of how the shopper happened to group their cart.+ it 'earns the same whether units share a line or not' do+ fixed = create(:commission_rate, :fixed, store: store, amounts: { 'USD' => 2.5 })+ together = create(:line_item, order: order, price: 100, quantity: 3)+ separately = create_list(:line_item, 3, order: order, price: 100, quantity: 1)++ grouped = call(rate: fixed, line_item: together).amount+ split = separately.sum { |item| call(rate: fixed, line_item: item).amount }++ expect(grouped).to eq(split)+ end++ it 'caps a flat fee that multiplied past the cap' do+ ten = create(:line_item, order: order, price: 100, quantity: 10)+ fixed = create(:commission_rate, :fixed, store: store, amounts: { 'USD' => 2.5 },+ currency: 'USD', max_amount: 12)++ expect(call(rate: fixed, line_item: ten).amount).to eq(12)endit 'snapshots the rate that applied' do