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
Keep a flat fee from charging delivery
Damian Legawiec36a5a3737607
diff --git a/docs/plans/6.0-multi-vendor-marketplace.md b/docs/plans/6.0-multi-vendor-marketplace.mdindex 123a5de5a5..4a0b603c49 100644--- a/docs/plans/6.0-multi-vendor-marketplace.md+++ b/docs/plans/6.0-multi-vendor-marketplace.md@@ -90,6 +90,10 @@ 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.++**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.+**Precedence (RESOLVED 2026-06-25; reshaped 2026-08-17 — `acts_as_list`, shipped): an ordered list, not a fixed ladder.** Rates carry `position` via `acts_as_list scope: :store_id` and are walked top-down, first match wins — so the order an operator sees in the table *is* the precedence, and reordering is dragging a row rather than reasoning about an integer. **New rates are created at the top** (`add_new_at: :top`): a rate exists to say something more specific than what is already there, and appending would file it behind the catch-all that matches everything. Seeds put a disabled marketplace-wide rate at the bottom, which makes the product-then-category-then-seller order merchants asked for fall out for free without hardcoding it. Ordering is deliberately **not** derived from how specific a rate's rules look: a rate may name a product, a category and a seller at once, so there is no single dimension to sort on, and "narrowest wins" guesses at an intent the operator can simply state.**The failure mode this model has, and which every change near it must be checked against:** a rate that matches everything makes every rate below it unreachable, and the mistakes that produce one are all silent widenings — a rate charging *more* sales than anybody asked it to, with a 200 saying it worked. Three separate instances surfaced while building this, each needing a deliberate refusal rather than a sensible default: a rules payload naming an unreachable record used to drop that rule (leaving a narrow rate global), an unregistered rule kind used to be skipped by `assign_typed_association` (same result), and the seeded catch-all was created at the top of the list by `add_new_at: :top` (shadowing every targeted rate on a store that already had some, once enabled). `CommissionRate#global?` exists so the condition is at least visible — the admin marks such a rate — and any future work on rules, ordering or seeding should ask what happens when its input is wrong in the widening direction.diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/settings/commission-rates.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/settings/commission-rates.tsxindex cd568b519e..5519882cc9 100644--- a/packages/dashboard/src/routes/_authenticated/$storeId/settings/commission-rates.tsx+++ b/packages/dashboard/src/routes/_authenticated/$storeId/settings/commission-rates.tsx@@ -441,12 +441,17 @@ function CommissionRateFormFields({ form }: { form: UseFormReturn<CommissionRate<FieldError errors={[errors.commission_tax_rate]} /></Field>- <ToggleField- form={form}- name="include_shipping"- label={t('admin.fields.commission_rate.include_shipping.label')}- help={t('admin.fields.commission_rate.include_shipping.help')}- />+ {/* 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. */}+ {kind === 'percentage' && (+ <ToggleField+ form={form}+ name="include_shipping"+ label={t('admin.fields.commission_rate.include_shipping.label')}+ help={t('admin.fields.commission_rate.include_shipping.help')}+ />+ )}<ToggleFieldform={form}diff --git a/packages/dashboard/src/schemas/commission-rate.ts b/packages/dashboard/src/schemas/commission-rate.tsindex 40f5606080..0861d93593 100644--- a/packages/dashboard/src/schemas/commission-rate.ts+++ b/packages/dashboard/src/schemas/commission-rate.ts@@ -112,7 +112,8 @@ export function commissionRateValuesToParams(): {},tax_inclusive: v.tax_inclusive,- include_shipping: v.include_shipping,+ // Only a percentage can charge delivery; a flat fee is per sale.+ include_shipping: v.kind === 'percentage' ? v.include_shipping : false,min_amount: decimalOrNull(v.min_amount),max_amount: decimalOrNull(v.max_amount),commission_tax_rate: taxPercentage === null ? null : taxPercentage / 100,diff --git a/spree/core/app/models/spree/commission_rate.rb b/spree/core/app/models/spree/commission_rate.rbindex f98aff0db5..3c9d8294b2 100644--- a/spree/core/app/models/spree/commission_rate.rb+++ b/spree/core/app/models/spree/commission_rate.rb@@ -80,6 +80,11 @@ module Spree# A flat fee that charges nothing anywhere would be skipped for every sale,# which reads as a rate that does not work rather than one that is off.validate :fixed_rate_states_an_amount+ # A flat fee is charged per sale, so there is nothing sensible for it to+ # charge on a parcel: the same amount again would double the fee for one+ # sale. A marketplace wanting a flat charge on delivery states it as its+ # own rate.+ validate :flat_fee_does_not_charge_deliveryvalidates :min_amount, :max_amount, numericality: { greater_than_or_equal_to: 0 }, allow_nil: true# A fraction, bounded like the store preference it overrides: the number is# multiplied straight into what a seller is charged, so a figure above 1@@ -254,6 +259,12 @@ module Spreecommission_rate_values.resetend+ def flat_fee_does_not_charge_delivery+ return unless fixed? && include_shipping?++ errors.add(:include_shipping, Spree.t('errors.messages.flat_fee_cannot_charge_delivery'))+ end+def fixed_rate_states_an_amountreturn unless fixed?return if @pending_amounts.present? || commission_rate_values.any?diff --git a/spree/core/config/locales/en.yml b/spree/core/config/locales/en.ymlindex 69ba78a8a6..38e5729cf3 100644--- a/spree/core/config/locales/en.yml+++ b/spree/core/config/locales/en.yml@@ -903,6 +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 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 3679ce85dc..9255390976 100644--- a/spree/core/spec/models/spree/commission_rate_spec.rb+++ b/spree/core/spec/models/spree/commission_rate_spec.rb@@ -98,6 +98,15 @@ RSpec.describe Spree::CommissionRate, type: :model doexpect(build(:commission_rate, kind: 'fixed', value: 0)).not_to be_validend+ # Charging the flat amount again per parcel would bill one sale twice, so+ # a marketplace wanting a flat delivery charge states it as its own rate.+ it 'refuses to also charge delivery' 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/)+ end+it 'retires a currency dropped from the set' dorate = create(:commission_rate, :fixed, store: store, amounts: { 'USD' => 5, 'GBP' => 4 })diff --git a/spree/core/spec/probe15_spec.rb b/spree/core/spec/probe15_spec.rbnew file mode 100644index 0000000000..0fcff3d685--- /dev/null+++ b/spree/core/spec/probe15_spec.rb@@ -0,0 +1,14 @@+require 'spec_helper'+RSpec.describe 'flat fee cannot charge delivery' do+ let(:store) { @default_store }++ it 'refuses the combination' do+ rate = build(:commission_rate, :fixed, store: store, include_shipping: true)+ puts "valid?: #{rate.valid?} #{rate.errors.full_messages.inspect}"+ expect(rate).not_to be_valid+ end++ it 'still allows a percentage to charge delivery' do+ expect(build(:commission_rate, store: store, include_shipping: true)).to be_valid+ end+end