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.

Let a seller refund when they cancel an order

Damian Legawiec1c1366c96a74
diff --git a/docs/api-reference/seller.yaml b/docs/api-reference/seller.yaml
index 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-Id
in: header
@@ -16610,6 +16614,9 @@ paths:
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/docs/plans/6.0-seller-order-management.md b/docs/plans/6.0-seller-order-management.md
index 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 cards
The 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.tsx
index 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; onClo
await 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; onClo
return (
<SharedOrderCancelDialog
form={form}
+ showRefund
reasonField={
/* The reasons are the marketplace's — the operator decides what they
are. A marketplace that has not curated them can still be pulled
diff --git a/packages/seller-dashboard/src/hooks/use-order.ts b/packages/seller-dashboard/src/hooks/use-order.ts
index 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.json
index 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.tsx
index 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.ts
index 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.rb
index 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 cancel
with_order_lock do
result = Spree.order_cancel_workflow.call(
@@ -40,6 +46,7 @@ module Spree
canceler: 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.rb
index 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 do
expect(response).to have_http_status(:not_found)
expect(theirs.reload).not_to be_canceled
end
+
+ # 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)
+ end
end
describe 'PATCH #cancel with a reason' do
diff --git a/spree/api/spec/integration/spree/api/v3/seller/orders_spec.rb b/spree/api/spec/integration/spree/api/v3/seller/orders_spec.rb
index 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.
DESC
parameter 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.rb
index 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' do
expect(Spree::Refund.where(originator: exchange).map(&:payment).uniq).to eq([payment])
end
end
+
+ # 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
+ end
end