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
Let a seller refund when they cancel an order
Damian Legawiec1c1366c96a74
diff --git a/docs/api-reference/seller.yaml b/docs/api-reference/seller.yamlindex 4f0959947e..3ae85f41eb 100644--- a/docs/api-reference/seller.yaml+++ b/docs/api-reference/seller.yaml@@ -16438,9 +16438,13 @@ paths:the marketplace's own list.The goods go back on the shelf and the payment authorization is- released. Money already taken is **not** returned: that is the- operator's decision, so this endpoint accepts no refund arguments at- all rather than defaulting one a caller could override.+ released either way. `refund_payments` also hands back what the buyer+ paid for these goods — a seller is merchant of record for their own+ child order, and on a split checkout only that order's share of the+ group's payment is settled.++ There is no `refund_amount`: withdrawing from the whole order returns+ what that order was paid, and a partial figure is a return.parameters:- name: X-Spree-Seller-Idin: header@@ -16610,6 +16614,9 @@ paths:type: stringnullable: truedescription: Free text beside the reason+ refund_payments:+ type: boolean+ description: Hand back what the buyer paid for this order's goodsnotify_customer:type: booleandescription: Email the customer about the cancellationdiff --git a/docs/plans/6.0-seller-order-management.md b/docs/plans/6.0-seller-order-management.mdindex ddc9dbda7d..1c473c0f4c 100644--- a/docs/plans/6.0-seller-order-management.md+++ b/docs/plans/6.0-seller-order-management.md@@ -4,7 +4,7 @@**Target:** Spree 6.0**Depends on:** `6.0-multi-vendor-marketplace.md` (Seller identity, the `/api/v3/seller` branch, order splitting, the fund ledger — all shipped), `6.0-returns-exchanges-claims.md` (Return/Exchange/Claim + their fifteen workflows — shipped), `6.0-fulfillment-and-delivery.md` (Fulfillment status model, `Fulfillments::Fulfill`/`Cancel`/`Resume` — shipped), `6.0-admin-spa.md` (panel composition, the three-package split)**Author:** Damian Legawiec-**Last updated:** 2026-09-03+**Last updated:** 2026-09-05## Summary@@ -50,6 +50,10 @@ The reversal path needs nothing new either: a refund on a fulfilled order alread**Still not the seller's:** the group's `Payment` (capture, void, adding a payment), order edits, approvals, and refunds on an order that is not theirs. Those remain endpoints that do not exist.+**Cancelling refunds too (amended 2026-09-05).** The seller cancel endpoint first shipped without `refund_payments`, on the reasoning that returning money already taken was the operator's call. That contradicted this very decision: a seller who withdraws from an order they cannot fulfil is the party who took that money, and routing the refund through the operator makes them a ticket queue exactly as described above. The endpoint now accepts `refund_payments`, and the seller panel offers the same switch the operator has.++The bound needs nothing new. `Orders::Cancel#amount_paid` sums only this order's `payment_splits` on a grouped order, and `settle_grouped_payments` refunds share by share, capped at each `net_captured_amount` and skipping any share mid-capture — so a seller cancelling can only reach their own child's money. `refund_amount` stays off the seller endpoint: withdrawing from the whole order returns what that order was paid, and a partial figure is a return, which has its own endpoint and its own ceiling.+### 2. The seller panel reproduces the dashboard's structure, minus operator-only cardsThe order page becomes the same two-column `ResourceLayout` the dashboard uses, with the same card vocabulary in the same order. What a seller sees is a subset, decided per card by whether the seller owns the question:diff --git a/packages/seller-dashboard/src/components/orders/order-cancel-dialog.tsx b/packages/seller-dashboard/src/components/orders/order-cancel-dialog.tsxindex d9e796ad6c..8065f782d7 100644--- a/packages/seller-dashboard/src/components/orders/order-cancel-dialog.tsx+++ b/packages/seller-dashboard/src/components/orders/order-cancel-dialog.tsx@@ -14,11 +14,10 @@ import { useReasons } from '../../hooks/use-reasons'/*** Withdrawing from an order this seller cannot fulfil.*- * Deliberately offers no refund control: the goods return to the shelf and- * the authorization is released either way, but giving back money already- * taken is the operator's decision, and the endpoint accepts no refund- * argument at all rather than showing a seller a switch that would be- * refused.+ * The refund is offered because a seller is merchant of record for their own+ * child order — the party who owes the buyer their money back is the party+ * who took it. On a split checkout the workflow settles through this order's+ * own payment shares, so a seller can never reach a sibling's money.*/export function OrderCancelDialog({ orderId, onClose }: { orderId: string; onClose: () => void }) {const { t } = useTranslation()@@ -35,6 +34,7 @@ export function OrderCancelDialog({ orderId, onClose }: { orderId: string; onCloawait cancel.mutateAsync({cancel_reason_id: values.cancel_reason_id || undefined,cancel_note: values.cancel_note.trim() || undefined,+ refund_payments: values.refund_payments,notify_customer: values.notify_customer,})onClose()@@ -46,6 +46,7 @@ export function OrderCancelDialog({ orderId, onClose }: { orderId: string; onCloreturn (<SharedOrderCancelDialogform={form}+ showRefundreasonField={/* The reasons are the marketplace's — the operator decides what theyare. A marketplace that has not curated them can still be pulleddiff --git a/packages/seller-dashboard/src/hooks/use-order.ts b/packages/seller-dashboard/src/hooks/use-order.tsindex c9851f5134..ad877287dc 100644--- a/packages/seller-dashboard/src/hooks/use-order.ts+++ b/packages/seller-dashboard/src/hooks/use-order.ts@@ -17,8 +17,12 @@ export function useOrder(orderId: string) {export function useCancelOrder(orderId: string) {return useOrderMutation(orderId,- (params?: { cancel_reason_id?: string; cancel_note?: string; notify_customer?: boolean }) =>- sellerClient().orders.cancel(orderId, params),+ (params?: {+ cancel_reason_id?: string+ cancel_note?: string+ refund_payments?: boolean+ notify_customer?: boolean+ }) => sellerClient().orders.cancel(orderId, params),)}diff --git a/packages/seller-dashboard/src/locales/en.json b/packages/seller-dashboard/src/locales/en.jsonindex 91d518b2cd..0fc769112f 100644--- a/packages/seller-dashboard/src/locales/en.json+++ b/packages/seller-dashboard/src/locales/en.json@@ -49,13 +49,15 @@"orders": {"detail": {"cancel": {- "description": "The goods go back on the shelf and the customer is no longer charged for them. Any money already taken is returned by the marketplace, not here.",+ "description": "The reason and note are recorded on the order, and any payments are settled.",+ "keep_order": "Keep order",+ "no_reason": "No reason given","note_label": "Note","note_placeholder": "Only staff see this note","notify_customer": "Email the customer",- "keep_order": "Keep order","reason_label": "Reason",- "no_reason": "No reason given"+ "refund_payments": "Refund the customer",+ "refund_payments_help": "Money already taken is returned. An unclaimed authorization is released either way."},"fulfillments": {"add_tracking_title": "Add tracking",@@ -342,7 +344,6 @@"shipping_title": "Edit Shipping Address"},"billing_address": "Billing address",- "cancel": "Cancel order","columns": {"fulfillment": "Fulfillment","number": "Order",diff --git a/packages/seller-dashboard/src/pages/order.tsx b/packages/seller-dashboard/src/pages/order.tsxindex aafd1b9c9c..5dc4e66fe3 100644--- a/packages/seller-dashboard/src/pages/order.tsx+++ b/packages/seller-dashboard/src/pages/order.tsx@@ -1,5 +1,6 @@import { PageHeader } from '@spree/dashboard-core'import { DropdownMenuItem, ResourceLayout, StatusBadge } from '@spree/dashboard-ui'+import { XCircleIcon } from '@spree/dashboard-ui/icons'import { useParams } from '@tanstack/react-router'import { useState } from 'react'import { useTranslation } from 'react-i18next'@@ -75,7 +76,8 @@ export function OrderPage() {destructiveItems={cancelable ? (<DropdownMenuItem variant="destructive" onClick={() => setCanceling(true)}>- {t('orders.cancel')}+ <XCircleIcon className="size-4" />+ {t('admin.pages.orders.detail.actions.cancel')}</DropdownMenuItem>) : undefined}diff --git a/packages/seller-sdk/src/seller-client.ts b/packages/seller-sdk/src/seller-client.tsindex c3219ceeae..3bf33262f9 100644--- a/packages/seller-sdk/src/seller-client.ts+++ b/packages/seller-sdk/src/seller-client.ts@@ -391,13 +391,20 @@ export class SellerClient {/*** Withdraws from an order this seller cannot fulfil.*- * Takes a reason from the marketplace's own list and an optional note.- * Never a refund: the authorization is released either way, but returning- * money already taken is the operator's decision.+ * `refund_payments` hands back what the buyer paid for these goods — a+ * seller is merchant of record for their own child order, and on a split+ * checkout only that order's share is settled. There is no+ * `refund_amount`: withdrawing from the whole order returns what that+ * order was paid, and a partial figure is a return.*/cancel: (id: string,- params?: { cancel_reason_id?: string; cancel_note?: string; notify_customer?: boolean },+ params?: {+ cancel_reason_id?: string+ cancel_note?: string+ refund_payments?: boolean+ notify_customer?: boolean+ },options?: RequestOptions,): Promise<Order> =>this.request<Order>('PATCH', `/orders/${id}/cancel`, { ...options, body: params }),diff --git a/spree/api/app/controllers/spree/api/v3/seller/orders_controller.rb b/spree/api/app/controllers/spree/api/v3/seller/orders_controller.rbindex 0b51e86ba7..6974211324 100644--- a/spree/api/app/controllers/spree/api/v3/seller/orders_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/seller/orders_controller.rb@@ -28,11 +28,17 @@ module Spree# A seller withdrawing from an order they cannot fulfil, naming a# reason from the marketplace's own list.#- # Deliberately takes no `refund_payments` or `refund_amount`: the- # workflow releases the authorization either way, but returning money- # already taken is the operator's decision, and leaving the arguments- # off is what keeps that true rather than a default a caller could- # override.+ # `refund_payments` hands back what the buyer paid for these goods.+ # A seller is merchant of record for their own child order, so the+ # party who owes that money back is the party who took it — and on a+ # split checkout the workflow settles through this order's own+ # payment splits, capped at each share, so a seller can never reach+ # a sibling's money.+ #+ # Deliberately takes no `refund_amount`: withdrawing from the whole+ # order returns what that order was paid, and a seller choosing a+ # partial figure is a return, which has its own endpoint and its own+ # bound.def cancelwith_order_lock doresult = Spree.order_cancel_workflow.call(@@ -40,6 +46,7 @@ module Spreecanceler: try_spree_current_user,reason: cancel_reason,note: params[:cancel_note].presence,+ refund_payments: params[:refund_payments].to_b,notify_customer: params[:notify_customer].to_b)diff --git a/spree/api/spec/controllers/spree/api/v3/seller/orders_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/seller/orders_controller_spec.rbindex f4033abc5b..dfbf486091 100644--- a/spree/api/spec/controllers/spree/api/v3/seller/orders_controller_spec.rb+++ b/spree/api/spec/controllers/spree/api/v3/seller/orders_controller_spec.rb@@ -201,6 +201,29 @@ RSpec.describe Spree::Api::V3::Seller::OrdersController, type: :controller doexpect(response).to have_http_status(:not_found)expect(theirs.reload).not_to be_canceledend++ # A seller is merchant of record for their own child order, so the party+ # who owes the buyer their money back is the party who took it.+ it 'hands back what the buyer paid when asked' do+ patch :cancel, params: { id: mine.prefixed_id, refund_payments: true }, as: :json++ expect(response).to have_http_status(:ok)+ expect(mine.reload).to be_canceled+ end++ # The seller decides whether to refund, never how much: withdrawing from+ # the whole order returns what that order was paid.+ it 'ignores a partial amount the seller names' do+ expect(Spree.order_cancel_workflow).to receive(:call).+ with(hash_excluding(:refund_amount)).+ and_return(Spree::ServiceModule::Result.new(true, mine))++ patch :cancel, params: {+ id: mine.prefixed_id, refund_payments: true, refund_amount: '1.00'+ }, as: :json++ expect(response).to have_http_status(:ok)+ endenddescribe 'PATCH #cancel with a reason' dodiff --git a/spree/api/spec/integration/spree/api/v3/seller/orders_spec.rb b/spree/api/spec/integration/spree/api/v3/seller/orders_spec.rbindex c3adc49779..2ee4e1341f 100644--- a/spree/api/spec/integration/spree/api/v3/seller/orders_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/seller/orders_spec.rb@@ -111,9 +111,13 @@ RSpec.describe 'Seller Orders API', type: :request, swagger_doc: 'api-reference/the marketplace's own list.The goods go back on the shelf and the payment authorization is- released. Money already taken is **not** returned: that is the- operator's decision, so this endpoint accepts no refund arguments at- all rather than defaulting one a caller could override.+ released either way. `refund_payments` also hands back what the buyer+ paid for these goods — a seller is merchant of record for their own+ child order, and on a split checkout only that order's share of the+ group's payment is settled.++ There is no `refund_amount`: withdrawing from the whole order returns+ what that order was paid, and a partial figure is a return.DESCparameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true@@ -126,6 +130,10 @@ RSpec.describe 'Seller Orders API', type: :request, swagger_doc: 'api-reference/description: 'A reason from GET /order_cancellation_reasons'},cancel_note: { type: :string, nullable: true, description: 'Free text beside the reason' },+ refund_payments: {+ type: :boolean,+ description: "Hand back what the buyer paid for this order's goods"+ },notify_customer: { type: :boolean, description: 'Email the customer about the cancellation' }}}diff --git a/spree/core/spec/workflows/spree/grouped_order_refunds_spec.rb b/spree/core/spec/workflows/spree/grouped_order_refunds_spec.rbindex 902bdce520..22132352e8 100644--- a/spree/core/spec/workflows/spree/grouped_order_refunds_spec.rb+++ b/spree/core/spec/workflows/spree/grouped_order_refunds_spec.rb@@ -153,4 +153,41 @@ RSpec.describe 'refunding a child order of a split checkout' doexpect(Spree::Refund.where(originator: exchange).map(&:payment).uniq).to eq([payment])endend++ # Cancelling a child order is the other way money goes back, and a seller+ # may cancel their own. The bound has to hold there too: the workflow reads+ # this order's shares, never the whole payment.+ describe Spree::Orders::Cancel do+ # A dispatched order cannot be withdrawn from, so these use orders that+ # have not gone out — which is the case a seller actually cancels.+ before do+ [order, sibling].each do |placed|+ placed.fulfillments.update_all(status: 'unfulfilled')+ placed.update_columns(fulfillment_status: 'unfulfilled')+ placed.reload+ end+ end++ it 'refunds only this order’s share of the group payment' do+ result = described_class.call(order: order, refund_payments: true)++ expect(result).to be_success++ refunds = Spree::Refund.where(order_id: order.id)+ expect(refunds.sum(&:amount)).to eq(100)+ # The sibling's captured share is untouched, and its own order has no+ # refund written against it.+ expect(Spree::Refund.where(order_id: sibling.id)).to be_empty+ expect(sibling_split.reload.captured_amount).to eq(100)+ end++ it 'releases the authorization without refunding when not asked' do+ result = described_class.call(order: order, refund_payments: false)++ expect(result).to be_success+ expect(Spree::Refund.where(order_id: order.id)).to be_empty+ # The share it reserved but never drew is given up.+ expect(split.reload.authorized_amount).to eq(split.captured_amount)+ end+ endend