spree-fixed_amt_discount 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c28a61c314d743fe8799c4128a8f6824b62a7e00a1550440d73ae672fdbe3682
+  data.tar.gz: b51b1d703375a40682650893927325df26e489f4af3de49006296cf6ef627c34
+SHA512:
+  metadata.gz: a6580edf628464368d03c34970cbefb85f6ee6e02a52a09391423e6059da0c147b53a04d14460f2a4da4cc1c0aa2e3cd8691ce914461e0a4aa24e2d69667d555
+  data.tar.gz: f669e1e83f575cbe9b4c12a78b8781e86cd5bccbf3b2ebd77f19906f17156c08b19ad5707b073eeda520a1a2808604437e420c494941869f8de00f15d21fed77

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release.
+- Adds `Spree::Calculator::FixedAmountOnLineItems`, a promotion calculator that
+  spreads a single fixed discount amount across the actionable line items in
+  proportion to their value, so per-item tax is recalculated correctly.
+- Registered automatically for per-line-item promotion adjustments.
+- Requires Spree >= 5.6.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aypex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,72 @@
+# Spree::FixedAmtDiscount
+
+Spree's built-in `FlatRate` calculator doesn't handle fixed-amount discounts
+well once tax is involved. Attached to a *per-line-item* promotion adjustment,
+it applies the full amount to **every** line item — a £10 promo on a
+three-item basket discounts £30, not £10. Attached to a *whole-order*
+adjustment instead, it lands as a single order-level adjustment that can't be
+apportioned between tax categories, so a VAT-inclusive store ends up with the
+wrong tax breakdown. This gem adds a calculator that spreads one fixed amount
+across the basket's line items in proportion to their value, so each item's
+share — and its tax — comes out correct.
+
+## Installation
+
+Requires Spree >= 5.6 and Ruby >= 3.3.
+
+```bash
+bundle add spree-fixed_amt_discount
+```
+
+## Usage
+
+In the Spree admin: **Promotion → Actions → Create per-line-item adjustment**,
+then choose the **Fixed Amount (spread across line items)** calculator and set
+its amount and currency.
+
+## Behaviour
+
+- The discount is split across actionable line items weighted by
+  `price × quantity`, calculated **before** any discounts are applied — so
+  when this promotion stacks with another one, the split is still based on
+  each item's original price, not its already-discounted price.
+- Because the split is proportional, the shares are rounded to the currency's
+  minor unit and won't always sum exactly to the target amount. The last item
+  (ordered by `id`) absorbs whatever rounding remainder is left, so the shares
+  usually sum to the full discount. In rare baskets where the rounding can't
+  divide cleanly, the applied total can fall a few pence short of the
+  configured amount — it will never go over, and a line item will never be
+  surcharged.
+- If the discount amount is larger than the actionable total, it clamps to
+  that total — the order can be discounted to zero but never goes negative.
+- Line items excluded by the promotion's rules (e.g. per-item rules or
+  promotion-category restrictions) are left out of the split entirely. Their
+  value isn't counted in the denominator, so they don't dilute the discount
+  shared among the remaining eligible items.
+
+## Example
+
+A £10 discount across three line items worth £33.33, £33.33 and £33.34 splits
+as £3.33 / £3.33 / £3.34 — the third item picks up the extra penny so the
+shares sum to exactly £10.00.
+
+## Preferences
+
+| Preference | Type | Default | Description |
+|---|---|---|---|
+| `amount` | decimal | — | The fixed amount to discount, before it's spread across line items. |
+| `currency` | string | the default store's currency | The currency the amount is denominated in. |
+| `apply_only_on_full_priced_items` | boolean | `false` | When `true`, excludes items with a compare-at price from both the split's numerator and its denominator. |
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test_app
+bundle exec rspec
+```
+
+## Licence
+
+The gem is available as open source under the terms of the [MIT
+Licence](LICENSE).

data/Rakefile

@@ -0,0 +1,26 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+require 'spree/testing_support/extension_rake'
+
+RSpec::Core::RakeTask.new
+
+task :default do
+  if Dir['spec/dummy'].empty?
+    Rake::Task[:test_app].invoke
+    Dir.chdir('../../')
+  end
+  Rake::Task[:spec].invoke
+end
+
+desc 'Generates a dummy app for testing'
+task :test_app do
+  # Must be the require path, not the gem name -- common:test_app does a literal
+  # `require ENV['LIB_NAME']` and templates the same string into the dummy app.
+  ENV['LIB_NAME'] = 'spree/fixed_amt_discount'
+  ENV['DB'] ||= 'postgres'
+  # This gem ships no admin or storefront views, so the dummy app needs neither.
+  # Leaving both off also skips the Tailwind install and assets:precompile.
+  Rake::Task['extension:test_app'].execute
+end

data/app/models/spree/calculator/fixed_amount_on_line_items.rb

@@ -0,0 +1,91 @@
+require_dependency 'spree/calculator'
+
+module Spree
+  # Spreads a single fixed discount amount across the actionable line items in
+  # proportion to their value, so each item carries its own share and Spree
+  # recalculates per-item tax against it.
+  class Calculator::FixedAmountOnLineItems < Calculator
+    preference :amount, :decimal, default: 0
+    preference :currency, :string, default: -> { Spree::Store.default.default_currency }
+    preference :apply_only_on_full_priced_items, :boolean, default: false
+
+    def self.description
+      Spree.t(:fixed_amount_on_line_items)
+    end
+
+    # Returns this line item's non-negative share of the fixed amount.
+    # Spree::Promotion::Actions::CreateItemAdjustments negates the result and
+    # applies its own guard against a negative order total.
+    def compute(line_item = nil)
+      return 0 if line_item.nil?
+      return 0 unless preferred_currency.to_s.casecmp(line_item.currency.to_s).zero?
+
+      items = actionable_line_items(line_item.order)
+      return 0 unless items.include?(line_item)
+
+      total = items.sum(&:amount)
+      return 0 unless total.positive?
+
+      # Clamp: a fixed amount larger than the basket discounts it to zero, never
+      # below. Matches Spree::Calculator::PercentOnLineItem. Rounded to 2dp so a
+      # >2dp preferred_amount can't leave the last item's remainder off-currency.
+      budget = [preferred_amount, total].min.round(2)
+
+      share =
+        if line_item == items.last
+          # The last item absorbs the rounding remainder so the shares sum to
+          # (at most) the budget rather than drifting by a penny or two.
+          budget - items[0..-2].sum { |item| pro_rata(item, budget, total) }
+        else
+          pro_rata(line_item, budget, total)
+        end
+
+      # Guard against a negative remainder becoming a positive (surcharge)
+      # adjustment once Spree core negates it, and never exceed the item's own
+      # amount.
+      share.clamp(0, line_item.amount)
+    end
+
+    private
+
+    def pro_rata(item, budget, total)
+      # Floor, not round: rounding earlier shares up can push their sum past
+      # the budget, forcing the last item's remainder negative -- which core
+      # would then negate into a positive surcharge on that line item.
+      # Flooring guarantees the running sum never exceeds the budget, so the
+      # remainder is provably non-negative (at worst it's a small shortfall).
+      (budget * item.amount / total).floor(2)
+    end
+
+    def actionable_line_items(order)
+      return [] if order.nil?
+
+      # Sorted by id so "the last item" -- the one absorbing the remainder --
+      # is the same on every call. Core only computes against persisted line
+      # items; the to_i keeps an unsaved one from raising on comparison.
+      order.line_items.to_a.
+        select { |item| actionable?(order, item) }.
+        sort_by { |item| item.id.to_i }
+    end
+
+    # Excluded items must leave the actionable set entirely -- dropping them
+    # from the numerator alone would dilute the remaining items' shares and
+    # apply less than the promised amount.
+    def actionable?(order, item)
+      return false if preferred_apply_only_on_full_priced_items && on_sale?(item)
+      return true if promotion.nil?
+
+      promotion.line_item_actionable?(order, item)
+    end
+
+    def on_sale?(item)
+      item.variant&.compare_at_amount_in(item.currency).present?
+    end
+
+    # `calculable` is the Spree::Promotion::Actions::CreateItemAdjustments this
+    # calculator belongs to. A bare calculator (no action) has none.
+    def promotion
+      calculable.try(:promotion)
+    end
+  end
+end

data/config/locales/en.yml

@@ -0,0 +1,3 @@
+en:
+  spree:
+    fixed_amount_on_line_items: "Fixed Amount (spread across line items)"

data/lib/spree/fixed_amt_discount/engine.rb

@@ -0,0 +1,23 @@
+module Spree
+  module FixedAmtDiscount
+    class Engine < ::Rails::Engine
+      require 'spree/core'
+      isolate_namespace Spree
+      engine_name 'spree_fixed_amt_discount'
+
+      config.generators do |g|
+        g.test_framework :rspec
+      end
+
+      # Must be after_initialize, not a config/initializers file: spree_core
+      # ASSIGNS this array with `=` in its own after_initialize, which runs
+      # after engine initializers and would clobber an earlier registration.
+      # This engine is initialized after spree_core, so this block runs after
+      # core's. spec/spree/fixed_amt_discount/registration_spec.rb pins it.
+      config.after_initialize do
+        Rails.application.config.spree.calculators.promotion_actions_create_item_adjustments <<
+          Spree::Calculator::FixedAmountOnLineItems
+      end
+    end
+  end
+end

data/lib/spree/fixed_amt_discount/version.rb

@@ -0,0 +1,5 @@
+module Spree
+  module FixedAmtDiscount
+    VERSION = '0.1.0'.freeze
+  end
+end

data/lib/spree/fixed_amt_discount.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require 'spree/core'
+require 'spree/fixed_amt_discount/version'
+require 'spree/fixed_amt_discount/engine'

data/lib/spree-fixed_amt_discount.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Bundler auto-requires a gem by its *name*, so `gem "spree-fixed_amt_discount"`
+# in a host Gemfile issues `require "spree-fixed_amt_discount"`. The real entry
+# point is `spree/fixed_amt_discount` (matching the Spree::FixedAmtDiscount
+# namespace), so this shim keeps the default `Bundler.require` working.
+require 'spree/fixed_amt_discount'

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: spree-fixed_amt_discount
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Aypex
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: spree
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.6.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.6.0
+- !ruby/object:Gem::Dependency
+  name: spree_dev_tools
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Adds a promotion calculator that spreads a single fixed discount amount
+  across the actionable line items in proportion to their value, so each item's tax
+  is recalculated correctly instead of the discount landing as one untaxed order-level
+  adjustment.
+email: hello@aypex.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- app/models/spree/calculator/fixed_amount_on_line_items.rb
+- config/locales/en.yml
+- lib/spree-fixed_amt_discount.rb
+- lib/spree/fixed_amt_discount.rb
+- lib/spree/fixed_amt_discount/engine.rb
+- lib/spree/fixed_amt_discount/version.rb
+homepage: https://github.com/aypex-io/spree-fixed_amt_discount
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/aypex-io/spree-fixed_amt_discount
+  bug_tracker_uri: https://github.com/aypex-io/spree-fixed_amt_discount/issues
+  changelog_uri: https://github.com/aypex-io/spree-fixed_amt_discount/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Fixed amount Spree promotion spread pro-rata across line items
+test_files: []