Skip to content

armgit / spree

Public Imported from GitHub
0

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.

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.md
index 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.json
index 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.json
index 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.json
index 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.json
index 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.json
index 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.json
index 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.tsx
index 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' && (
<ToggleField
form={form}
diff --git a/spree/core/app/services/spree/commissions/calculate_line.rb b/spree/core/app/services/spree/commissions/calculate_line.rb
index 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 Spree
private
- # 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)
end
diff --git a/spree/core/config/locales/en.yml b/spree/core/config/locales/en.yml
index 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 order
exactly_one_of_line_item_or_fulfillment: must be charged against exactly one of a line item or a fulfillment
exactly_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 delivery
integration_connection_failed: could not connect with the saved credentials
integration_type_not_registered: is not a registered integration
invalid_commission_rule: is not a commission rule kind this store has
diff --git a/spree/core/spec/models/spree/commission_rate_spec.rb b/spree/core/spec/models/spree/commission_rate_spec.rb
index 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 do
rate = 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/)
end
it 'retires a currency dropped from the set' do
diff --git a/spree/core/spec/services/spree/commissions/calculate_line_spec.rb b/spree/core/spec/services/spree/commissions/calculate_line_spec.rb
index 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 do
expect(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' do
three = 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)
end
it 'snapshots the rate that applied' do