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 the refund backfill free of model references
Damian Legawiecebdf3a8c60bc
diff --git a/docs/plans/6.0-multi-vendor-marketplace.md b/docs/plans/6.0-multi-vendor-marketplace.mdindex f41fb99b3b..052d7bfe2d 100644--- a/docs/plans/6.0-multi-vendor-marketplace.md+++ b/docs/plans/6.0-multi-vendor-marketplace.md@@ -725,6 +725,8 @@ Even before this lands, work touching adjacent areas should:- **The split adopts the paid order rather than replacing it, and moves rows rather than copying them** (RESOLVED 2026-08-20, shipped). Completion builds one draft order holding the whole basket so it can be paid as one; the split then makes that order the group's first child and hands the other partitions' rows to new siblings. The alternative — build N fresh orders and destroy the original — was written first and rejected on two counts: the original is the record the payment was taken against and the row carrying the unique `cart_id` that makes completion replayable, so destroying it orphans money and breaks resumption. Rows **move** (`update_all` on the owner FK) rather than being re-copied from the cart, because everything was costed once inside the completion lock and re-deriving would ask the pricing and tax engines a question already answered — possibly getting a different one. The group takes the order's number so the customer keeps the reference they saw at checkout, and children suffix off it (`R1001-1`), following the same reads-its-parent shape as fulfillment and payment numbers.- **Splitting a parcel between sellers divides everything hanging off it** (RESOLVED 2026-08-20, shipped). A fulfillment holding two sellers' goods becomes two, and the cost the customer was quoted is apportioned between them by the value each half carries (largest-remainder), never copied onto both. The first implementation cloned the fulfillment wholesale and charged delivery twice — the group totalled more than the customer paid, caught by a totals spec rather than by review. The honest reading is that one quote for one parcel no longer describes two; a marketplace wanting each seller quoted separately gets that by giving sellers their own delivery methods, which packs their goods separately from the start and leaves nothing to divide. **Three things divide with it**, each missed on the first pass because a divided parcel is the only case where a row's owner keeps its id while its contents change: the parcel's own tax lines, discounts and fees (re-pointing by `fulfillment_id` finds nothing for the clone, so the source kept tax on a charge it no longer bore and the sibling shipped untaxed), the **selected delivery rate** (a fulfillment restates its cost from its rate whenever amounts refresh, so leaving the rate whole quietly restored the full charge on both halves the next time anything touched them), and the **stock reservations** on the moving line items (scoped by `order_id` at release, so one child would have released everyone's and each sibling none).- **Per-seller commission needed no commission-engine change** (RESOLVED 2026-08-20, verified). Each child order publishes its own `order.placed`, which `OrderCommissionSubscriber` already answers, and `Commissions::CommissionOrder` already partitions by `line_item.seller_id` and skips nil-seller lines — so the seller children are commissioned and the first-party child correctly is not, with no marketplace branch anywhere in the engine. This is the payoff of the Phase 2 decision to key commission on the line item's own seller snapshot rather than on the order.+- **A promotion is redeemed by a checkout, not by an order** (RESOLVED 2026-08-21, shipped). `Promotion#credits_count` counted distinct `order_id`s carrying its discount rows, so a split checkout — which leaves a row on every child — spent a `usage_limit` two or three times over on one customer's single redemption, and a promotion capped at 100 uses ran out early for everyone. Counting now collapses on `COALESCE(orders.order_group_id, orders.id)`, so a group's children are one use between them and an ungrouped order is itself; `adjusted_credits_count` and `used_by?` exclude the asking order's **whole group** rather than just the order, via `Order#sibling_order_ids` (`[id]` when ungrouped). Coupon codes and the one-use-per-customer rule were checked and need nothing — a code's `used` flag lives on the code, and `used_by?` answers a boolean. The adjacent lesson: anything counting "how many times has this been used" must ask what a *use* is, because the split turned one of them into several without changing any of those call sites.+- **A single-seller checkout stamps its order with the seller** (RESOLVED 2026-08-21, shipped). The split gate returns early on one partition, which was right about not making a group and wrong about doing nothing: the line items carried `seller_id` (so commission worked) while `orders.seller_id` stayed null — and that column is what `Seller#orders` and the seller branch's `current_seller.orders` read, so a seller's own order list would have been empty for every basket bought only from them. The single-partition path now stamps the order before returning.- **The seller is asked about through a concern, so the container stays neutral** (RESOLVED 2026-08-20, shipped). `OrderGroup#sellers`, `#seller_count` and `#includes_first_party?` live in `Spree::Marketplace::OrderGroup`, included into the model rather than written on it, and `PaymentSplit` carries no seller reader at all (its order answers). Decision 8 says the group is a domain-neutral primitive whose other three planned consumers — split-by-location, split-by-availability, B2B split-by-company-location — have no seller, and "first party" means nothing to any of them. The readers are genuinely useful to a marketplace operator and the admin serializer renders them; keeping them in a concern is what lets both be true. Worth doing on the boundary rather than later, since the moment those fields ship they are client-visible API.- **The split must say "re-sum, don't regenerate" explicitly** (RESOLVED 2026-08-20, shipped). `Carts::RecalculateTotals` takes `resum_only:`, and the split passes it. The freeze was previously inferred from `completed?`, which is `completed_at.present?` — and the children are still **drafts** when they are re-summed, so the guard did not fire: the promotion adjuster deleted the discounts just moved onto each child and re-tested one seller's subset against a threshold the whole basket met, and the tax provider deleted the moved tax lines and re-derived them from today's rates. The service's own docstring claimed it was avoiding exactly this. A lifecycle predicate was the wrong instrument for an intent the caller knows and the record does not; the parameter states it. Pinned by a spec asserting an order-level £6 promotion survives the split intact (£3 per child, group total equal to what was charged) — the failure was silent and money-visible, and only a totals assertion catches it.- **A shared payment is bounded, re-allocated and refunded per child — never voided wholesale** (RESOLVED 2026-08-20, shipped). Four consequences of one payment covering several orders, each of which fails silently in a different direction: a partial capture forks the payment (`split_uncaptured_amount`), so the remainder must **carry the uncaptured shares with it** or the sellers who have not shipped point at an authorization that no longer holds their money; `Orders::Cancel` on a grouped child **refunds that child's captured share** instead of voiding the payment, since voiding would release the siblings' authorization and un-pay sellers still shipping; `Payment#owner` being an `OrderGroup` means `gateway_options` asks it for `ship_total`/`additional_tax_total`/`discount_total`/`last_ip_address`, so the group answers all of them by roll-up (without which **every** post-placement gateway call on a split checkout raised); and every refund now carries `order_id` (stamped from the payment when it can answer, named by the caller when it cannot), which is what lets `Order#refunds` stay one plain association and the admin refunds endpoint keep working.diff --git a/spree/core/db/migrate/20260820000004_add_order_to_spree_refunds.rb b/spree/core/db/migrate/20260820000004_add_order_to_spree_refunds.rbindex a2bd6b39b7..0419b6e9e1 100644--- a/spree/core/db/migrate/20260820000004_add_order_to_spree_refunds.rb+++ b/spree/core/db/migrate/20260820000004_add_order_to_spree_refunds.rb@@ -15,11 +15,14 @@ class AddOrderToSpreeRefunds < ActiveRecord::Migration[8.1]reversible do |direction|direction.up do+ # A correlated UPDATE rather than Active Record: the same statement+ # runs on every adapter, and a migration should not depend on models+ # that may be renamed long after it has run.execute <<~SQL.squish- UPDATE #{Spree::Refund.table_name}+ UPDATE spree_refundsSET order_id = (- SELECT order_id FROM #{Spree::Payment.table_name}- WHERE #{Spree::Payment.table_name}.id = #{Spree::Refund.table_name}.payment_id+ SELECT order_id FROM spree_payments+ WHERE spree_payments.id = spree_refunds.payment_id)WHERE order_id IS NULLSQL