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.

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.md
index 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.tsx
index 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')}
+ />
+ )}
<ToggleField
form={form}
diff --git a/packages/dashboard/src/schemas/commission-rate.ts b/packages/dashboard/src/schemas/commission-rate.ts
index 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.rb
index 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_delivery
validates :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 Spree
commission_rate_values.reset
end
+ 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_amount
return 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.yml
index 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 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
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 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 do
expect(build(:commission_rate, kind: 'fixed', value: 0)).not_to be_valid
end
+ # 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' do
rate = 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.rb
new file mode 100644
index 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