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
Ask how to resolve a claim instead of guessing
Damian Legawiecce14b19bff56
diff --git a/packages/admin-sdk/src/params.ts b/packages/admin-sdk/src/params.tsindex 2413c95770..df9e940142 100644--- a/packages/admin-sdk/src/params.ts+++ b/packages/admin-sdk/src/params.ts@@ -220,6 +220,12 @@ export interface ClaimResolveParams {refund_method?: 'original_payment' | 'store_credit'/** Decimal amount; defaults to the claim total */amount?: string | number+ /**+ * Which claim lines to send a replacement for. Omit to keep whatever the+ * claim was opened with — the merchant usually decides what to send when+ * resolving, not when the customer first reported the problem.+ */+ replacement_line_item_ids?: string[]}export interface ReturnRefundParams {diff --git a/packages/dashboard/src/components/spree/order-post-sale-cards.tsx b/packages/dashboard/src/components/spree/order-post-sale-cards.tsxindex 9d2f96483b..0e30956033 100644--- a/packages/dashboard/src/components/spree/order-post-sale-cards.tsx+++ b/packages/dashboard/src/components/spree/order-post-sale-cards.tsx@@ -34,7 +34,12 @@ import {useOrderClaims,useOrderExchanges,} from '../../hooks/use-post-sale'-import { CreateClaimDialog, CreateExchangeDialog, fulfilledUnits } from './post-sale-create-dialogs'+import {+ CreateClaimDialog,+ CreateExchangeDialog,+ fulfilledUnits,+ ResolveClaimDialog,+} from './post-sale-create-dialogs'/** Exchanges on an order, with the actions available at each status. */export function OrderExchangesCard({ order }: { order: Order }) {@@ -189,6 +194,7 @@ export function OrderClaimsCard({ order }: { order: Order }) {const { data } = useOrderClaims(orderId)const { create, approve, resolve, deny, cancel } = useClaimActions(orderId)const [creatingClaim, setCreatingClaim] = useState(false)+ const [resolving, setResolving] = useState<Claim | null>(null)const claims = data?.data ?? []// A claim is about ordered items, so it never depends on anything shipping.@@ -248,24 +254,10 @@ export function OrderClaimsCard({ order }: { order: Order }) {</DropdownMenuItem>)}{claim.status === 'approved' && (- <>- <DropdownMenuItem- onClick={() =>- resolve.mutate({ claimId: claim.id, resolution: 'refund' })- }- >- <BanknoteIcon className="size-4" />- {t('admin.pages.orders.detail.claims.actions.resolve_refund')}- </DropdownMenuItem>- <DropdownMenuItem- onClick={() =>- resolve.mutate({ claimId: claim.id, resolution: 'replacement' })- }- >- <TruckIcon className="size-4" />- {t('admin.pages.orders.detail.claims.actions.resolve_replacement')}- </DropdownMenuItem>- </>+ <DropdownMenuItem onClick={() => setResolving(claim)}>+ <BanknoteIcon className="size-4" />+ {t('admin.pages.orders.detail.claims.actions.resolve')}+ </DropdownMenuItem>)}{claim.status === 'open' && (<DropdownMenuItem onClick={() => deny.mutate({ claimId: claim.id })}>@@ -324,6 +316,23 @@ export function OrderClaimsCard({ order }: { order: Order }) {</CardContent></Card>+ {resolving && (+ <ResolveClaimDialog+ claim={resolving}+ onClose={() => setResolving(null)}+ onSubmit={({ resolution, refundMethod, amount, replacementLineItemIds }) => {+ resolve.mutate({+ claimId: resolving.id,+ resolution,+ refundMethod,+ amount,+ replacementLineItemIds,+ })+ setResolving(null)+ }}+ />+ )}+{creatingClaim && (<CreateClaimDialogorder={order}diff --git a/packages/dashboard/src/components/spree/post-sale-create-dialogs.tsx b/packages/dashboard/src/components/spree/post-sale-create-dialogs.tsxindex c757c974c2..3f03312fa9 100644--- a/packages/dashboard/src/components/spree/post-sale-create-dialogs.tsx+++ b/packages/dashboard/src/components/spree/post-sale-create-dialogs.tsx@@ -1,4 +1,4 @@-import type { Order } from '@spree/admin-sdk'+import type { Claim, Order } from '@spree/admin-sdk'import {Button,Dialog,@@ -15,6 +15,7 @@ import {SelectItem,SelectTrigger,SelectValue,+ Switch,Textarea,} from '@spree/dashboard-ui'import { useState } from 'react'@@ -399,3 +400,177 @@ export function CreateClaimDialog({</Dialog>)}++/**+ * Deciding how to make a claim right. This is where the merchant chooses —+ * not at claim creation, when only the customer's complaint is known.+ */+export function ResolveClaimDialog({+ claim,+ onClose,+ onSubmit,+}: {+ claim: Claim+ onClose: () => void+ onSubmit: (params: {+ resolution: 'refund' | 'replacement' | 'refund_and_replacement'+ refundMethod: 'original_payment' | 'store_credit'+ amount?: string+ replacementLineItemIds: string[]+ }) => void+}) {+ const { t } = useTranslation()+ const lines = claim.claim_line_items ?? []++ const [resolution, setResolution] = useState<'refund' | 'replacement' | 'refund_and_replacement'>(+ 'refund',+ )+ const [refundMethod, setRefundMethod] = useState<'original_payment' | 'store_credit'>(+ 'store_credit',+ )+ const [amount, setAmount] = useState(claim.refund_total)+ const [replacing, setReplacing] = useState<Record<string, boolean>>(() =>+ Object.fromEntries(lines.map((line) => [line.id, line.send_replacement])),+ )++ const refunding = resolution.includes('refund')+ const sendingReplacement = resolution.includes('replacement')+ const chosenReplacements = Object.entries(replacing)+ .filter(([, on]) => on)+ .map(([id]) => id)++ const resolutionOptions = (['refund', 'replacement', 'refund_and_replacement'] as const).map(+ (value) => ({+ value,+ label: t(`admin.pages.orders.detail.claims.resolutions.${value}`),+ }),+ )++ const methodOptions = [+ {+ value: 'store_credit',+ label: t('admin.pages.orders.detail.returns.refund_methods.store_credit'),+ },+ {+ value: 'original_payment',+ label: t('admin.pages.orders.detail.returns.refund_methods.original_payment'),+ },+ ]++ // Refunding nothing, or replacing nothing, is what the server rejects —+ // say so here instead of letting the request fail.+ const ready =+ (!refunding || Number(amount) > 0) && (!sendingReplacement || chosenReplacements.length > 0)++ return (+ <Dialog open onOpenChange={(open) => !open && onClose()}>+ <DialogContent>+ <DialogHeader>+ <DialogTitle>{t('admin.pages.orders.detail.claims.resolve_title')}</DialogTitle>+ </DialogHeader>+ <DialogBody className="flex flex-col gap-4">+ <Field>+ <FieldLabel htmlFor="claim-resolution">+ {t('admin.pages.orders.detail.claims.resolution')}+ </FieldLabel>+ <Select+ items={resolutionOptions}+ value={resolution}+ onValueChange={(value) => setResolution(value as typeof resolution)}+ >+ <SelectTrigger id="claim-resolution">+ <SelectValue />+ </SelectTrigger>+ <SelectContent>+ {resolutionOptions.map((option) => (+ <SelectItem key={option.value} value={option.value}>+ {option.label}+ </SelectItem>+ ))}+ </SelectContent>+ </Select>+ </Field>++ {refunding && (+ <>+ <Field>+ <FieldLabel htmlFor="claim-resolve-amount">+ {t('admin.pages.orders.detail.claims.refund_amount')}+ </FieldLabel>+ <Input+ id="claim-resolve-amount"+ value={amount}+ onChange={(event) => setAmount(event.target.value)}+ />+ </Field>+ <Field>+ <FieldLabel htmlFor="claim-refund-method">+ {t('admin.pages.orders.detail.returns.refund_method')}+ </FieldLabel>+ <Select+ items={methodOptions}+ value={refundMethod}+ onValueChange={(value) => setRefundMethod(value as typeof refundMethod)}+ >+ <SelectTrigger id="claim-refund-method">+ <SelectValue />+ </SelectTrigger>+ <SelectContent>+ {methodOptions.map((option) => (+ <SelectItem key={option.value} value={option.value}>+ {option.label}+ </SelectItem>+ ))}+ </SelectContent>+ </Select>+ </Field>+ </>+ )}++ {sendingReplacement && (+ <div className="flex flex-col gap-2">+ <span className="text-sm font-medium">+ {t('admin.pages.orders.detail.claims.replacement_items')}+ </span>+ {lines.map((line) => (+ <div+ key={line.id}+ className="flex items-center justify-between gap-4 rounded-lg border p-3"+ >+ <span className="text-sm truncate">+ {line.variant?.product_name ?? line.variant_id}+ <span className="text-muted-foreground"> ×{line.quantity}</span>+ </span>+ <Switch+ checked={replacing[line.id] ?? false}+ onCheckedChange={(checked) =>+ setReplacing({ ...replacing, [line.id]: checked })+ }+ />+ </div>+ ))}+ </div>+ )}+ </DialogBody>+ <DialogFooter>+ <Button variant="outline" onClick={onClose}>+ {t('admin.actions.cancel')}+ </Button>+ <Button+ disabled={!ready}+ onClick={() =>+ onSubmit({+ resolution,+ refundMethod,+ amount: refunding ? amount : undefined,+ replacementLineItemIds: chosenReplacements,+ })+ }+ >+ {t('admin.pages.orders.detail.claims.actions.resolve')}+ </Button>+ </DialogFooter>+ </DialogContent>+ </Dialog>+ )+}diff --git a/packages/dashboard/src/hooks/use-post-sale.ts b/packages/dashboard/src/hooks/use-post-sale.tsindex 79392ac29c..0840728d01 100644--- a/packages/dashboard/src/hooks/use-post-sale.ts+++ b/packages/dashboard/src/hooks/use-post-sale.ts@@ -1,5 +1,6 @@import { adminClient, useResourceKey, useResourceKeyBuilder } from '@spree/dashboard-core'import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'+import { toast } from 'sonner'/*** Exchanges and claims on an order. Fetched separately from the order for the@@ -49,6 +50,11 @@ function usePostSaleMutation<TParams>(queryClient.invalidateQueries({ queryKey: buildKey(resourceKey, orderId) })queryClient.invalidateQueries({ queryKey: buildKey('orders', orderId) })},+ onError: (error) => {+ // Without this a rejected workflow — a claim with nothing to refund, a+ // return that cannot be cancelled — looked like a dead button.+ toast.error(error instanceof Error ? error.message : String(error))+ },})}@@ -129,16 +135,19 @@ export function useClaimActions(orderId: string) {resolution,refundMethod,amount,+ replacementLineItemIds,}: {claimId: stringresolution: 'refund' | 'replacement' | 'refund_and_replacement'refundMethod?: 'original_payment' | 'store_credit'amount?: string+ replacementLineItemIds?: string[]}) =>adminClient.orders.claims.resolve(orderId, claimId, {resolution,refund_method: refundMethod,amount,+ replacement_line_item_ids: replacementLineItemIds,}),)diff --git a/packages/dashboard/src/hooks/use-returns.ts b/packages/dashboard/src/hooks/use-returns.tsindex f574c2338f..352657083a 100644--- a/packages/dashboard/src/hooks/use-returns.ts+++ b/packages/dashboard/src/hooks/use-returns.ts@@ -1,5 +1,6 @@import { adminClient, useResourceKey, useResourceKeyBuilder } from '@spree/dashboard-core'import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'+import { toast } from 'sonner'/*** Returns on an order. Fetched separately from the order itself so the order@@ -33,6 +34,11 @@ function useReturnMutation<TParams>(queryClient.invalidateQueries({ queryKey: buildKey('order-returns', orderId) })queryClient.invalidateQueries({ queryKey: buildKey('orders', orderId) })},+ onError: (error) => {+ // Without this a rejected workflow — a claim with nothing to refund, a+ // return that cannot be cancelled — looked like a dead button.+ toast.error(error instanceof Error ? error.message : String(error))+ },})}diff --git a/packages/dashboard/src/locales/ar.json b/packages/dashboard/src/locales/ar.jsonindex 8dd9104c9b..db56027012 100644--- a/packages/dashboard/src/locales/ar.json+++ b/packages/dashboard/src/locales/ar.json@@ -1708,7 +1708,8 @@"resolve_refund": "الحل بالاسترداد","resolve_replacement": "الحل بالاستبدال","deny": "رفض",- "create": "مطالبة جديدة"+ "create": "مطالبة جديدة",+ "resolve": "حل"},"types": {"damaged": "تالف",@@ -1719,7 +1720,15 @@"empty": "لا توجد مطالبات لهذا الطلب.","create_title": "مطالبة جديدة","claim_type": "المشكلة",- "refund_amount": "مبلغ الاسترداد"+ "refund_amount": "مبلغ الاسترداد",+ "resolve_title": "حل المطالبة",+ "resolution": "طريقة الحل",+ "replacement_items": "إرسال بديل لـ",+ "resolutions": {+ "refund": "استرداد",+ "replacement": "استبدال",+ "refund_and_replacement": "استرداد واستبدال"+ }},"dialogs": {"approve_title": "الموافقة على الطلب؟",diff --git a/packages/dashboard/src/locales/de.json b/packages/dashboard/src/locales/de.jsonindex e9b4e4b5a3..378d4c257c 100644--- a/packages/dashboard/src/locales/de.json+++ b/packages/dashboard/src/locales/de.json@@ -1708,7 +1708,8 @@"resolve_refund": "Mit Erstattung lösen","resolve_replacement": "Mit Ersatz lösen","deny": "Ablehnen",- "create": "Neue Reklamation"+ "create": "Neue Reklamation",+ "resolve": "Lösen"},"types": {"damaged": "Beschädigt",@@ -1719,7 +1720,15 @@"empty": "Keine Reklamationen für diese Bestellung.","create_title": "Neue Reklamation","claim_type": "Problem",- "refund_amount": "Erstattungsbetrag"+ "refund_amount": "Erstattungsbetrag",+ "resolve_title": "Reklamation lösen",+ "resolution": "Lösungsweg",+ "replacement_items": "Ersatz senden für",+ "resolutions": {+ "refund": "Erstattung",+ "replacement": "Ersatz",+ "refund_and_replacement": "Erstattung und Ersatz"+ }},"dialogs": {"approve_title": "Bestellung genehmigen?",diff --git a/packages/dashboard/src/locales/en.json b/packages/dashboard/src/locales/en.jsonindex 71bb8e05d4..aa8fbe7c4e 100644--- a/packages/dashboard/src/locales/en.json+++ b/packages/dashboard/src/locales/en.json@@ -1708,7 +1708,8 @@"resolve_refund": "Resolve with refund","resolve_replacement": "Resolve with replacement","deny": "Deny",- "create": "New claim"+ "create": "New claim",+ "resolve": "Resolve"},"types": {"damaged": "Damaged",@@ -1719,7 +1720,15 @@"empty": "No claims for this order.","create_title": "New claim","claim_type": "Problem",- "refund_amount": "Refund amount"+ "refund_amount": "Refund amount",+ "resolve_title": "Resolve claim",+ "resolution": "How to resolve",+ "replacement_items": "Send a replacement for",+ "resolutions": {+ "refund": "Refund",+ "replacement": "Replacement",+ "refund_and_replacement": "Refund and replacement"+ }},"dialogs": {"approve_title": "Approve order?",diff --git a/packages/dashboard/src/locales/fr.json b/packages/dashboard/src/locales/fr.jsonindex 58be35d542..5cd92b3ab8 100644--- a/packages/dashboard/src/locales/fr.json+++ b/packages/dashboard/src/locales/fr.json@@ -1708,7 +1708,8 @@"resolve_refund": "Résoudre par remboursement","resolve_replacement": "Résoudre par remplacement","deny": "Refuser",- "create": "Nouvelle réclamation"+ "create": "Nouvelle réclamation",+ "resolve": "Résoudre"},"types": {"damaged": "Endommagé",@@ -1719,7 +1720,15 @@"empty": "Aucune réclamation pour cette commande.","create_title": "Nouvelle réclamation","claim_type": "Problème",- "refund_amount": "Montant du remboursement"+ "refund_amount": "Montant du remboursement",+ "resolve_title": "Résoudre la réclamation",+ "resolution": "Mode de résolution",+ "replacement_items": "Envoyer un remplacement pour",+ "resolutions": {+ "refund": "Remboursement",+ "replacement": "Remplacement",+ "refund_and_replacement": "Remboursement et remplacement"+ }},"dialogs": {"approve_title": "Approuver la commande ?",diff --git a/packages/dashboard/src/locales/pl.json b/packages/dashboard/src/locales/pl.jsonindex 9e9830e738..22220e8bf2 100644--- a/packages/dashboard/src/locales/pl.json+++ b/packages/dashboard/src/locales/pl.json@@ -1716,7 +1716,8 @@"resolve_refund": "Rozwiąż zwrotem płatności","resolve_replacement": "Rozwiąż zamiennikiem","deny": "Odrzuć",- "create": "Nowa reklamacja"+ "create": "Nowa reklamacja",+ "resolve": "Rozwiąż"},"types": {"damaged": "Uszkodzony",@@ -1727,7 +1728,15 @@"empty": "Brak reklamacji dla tego zamówienia.","create_title": "Nowa reklamacja","claim_type": "Problem",- "refund_amount": "Kwota zwrotu"+ "refund_amount": "Kwota zwrotu",+ "resolve_title": "Rozwiąż reklamację",+ "resolution": "Sposób rozwiązania",+ "replacement_items": "Wyślij zamiennik dla",+ "resolutions": {+ "refund": "Zwrot płatności",+ "replacement": "Zamiennik",+ "refund_and_replacement": "Zwrot i zamiennik"+ }},"dialogs": {"approve_title": "Zatwierdzić zamówienie?",diff --git a/packages/dashboard/src/locales/zh-CN.json b/packages/dashboard/src/locales/zh-CN.jsonindex 92d101286c..f5dc9e2052 100644--- a/packages/dashboard/src/locales/zh-CN.json+++ b/packages/dashboard/src/locales/zh-CN.json@@ -1708,7 +1708,8 @@"resolve_refund": "以退款解决","resolve_replacement": "以换货解决","deny": "拒绝",- "create": "新建索赔"+ "create": "新建索赔",+ "resolve": "解决"},"types": {"damaged": "已损坏",@@ -1719,7 +1720,15 @@"empty": "此订单暂无索赔。","create_title": "新建索赔","claim_type": "问题",- "refund_amount": "退款金额"+ "refund_amount": "退款金额",+ "resolve_title": "解决索赔",+ "resolution": "解决方式",+ "replacement_items": "为以下商品发送替换",+ "resolutions": {+ "refund": "退款",+ "replacement": "换货",+ "refund_and_replacement": "退款并换货"+ }},"dialogs": {"approve_title": "批准订单?",diff --git a/spree/api/app/controllers/spree/api/v3/admin/orders/claims_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/orders/claims_controller.rbindex 1fdec6e789..6adf4cd033 100644--- a/spree/api/app/controllers/spree/api/v3/admin/orders/claims_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/admin/orders/claims_controller.rb@@ -53,6 +53,7 @@ module Spreeresolution: params[:resolution],refund_method: params[:refund_method] || 'store_credit',amount: params[:amount],+ replacement_line_item_ids: replacement_line_item_ids,resolver: try_spree_current_user)end@@ -98,6 +99,16 @@ module Spreeprivate+ # Which lines to replace, decided at resolution time. Absent means+ # "leave whatever the claim was opened with".+ def replacement_line_item_ids+ return nil unless params.key?(:replacement_line_item_ids)++ Array(params[:replacement_line_item_ids]).map do |id|+ @resource.claim_line_items.find_by_prefix_id!(id).id+ end+ end+def run_workflow(workflow, **arguments)result = workflow.call(claim: @resource, **arguments)diff --git a/spree/api/spec/controllers/spree/api/v3/admin/orders/claims_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/orders/claims_controller_spec.rbindex ba027f9fcb..f14ad48b10 100644--- a/spree/api/spec/controllers/spree/api/v3/admin/orders/claims_controller_spec.rb+++ b/spree/api/spec/controllers/spree/api/v3/admin/orders/claims_controller_spec.rb@@ -80,6 +80,25 @@ RSpec.describe Spree::Api::V3::Admin::Orders::ClaimsController, type: :controlleexpect(response).to have_http_status(:unprocessable_content)end+ # The merchant decides what to send when resolving, so a claim opened+ # without replacement flags can still be resolved with one.+ it 'sends a replacement for the lines chosen at resolve time' do+ line = claim.claim_line_items.first+ line.update!(send_replacement: false)+ line.variant.stock_items.first&.set_count_on_hand(10)++ patch :resolve, params: {+ order_id: order.prefixed_id,+ id: claim.prefixed_id,+ resolution: 'replacement',+ replacement_line_item_ids: [line.prefixed_id]+ }, as: :json++ expect(response).to have_http_status(:ok)+ expect(json_response['status']).to eq('resolved')+ expect(line.reload.send_replacement).to be(true)+ end+it 'rejects an unknown resolution' dopatch :resolve, params: {order_id: order.prefixed_id,diff --git a/spree/core/app/workflows/spree/claims/resolve.rb b/spree/core/app/workflows/spree/claims/resolve.rbindex c98f41070a..3acea2223f 100644--- a/spree/core/app/workflows/spree/claims/resolve.rb+++ b/spree/core/app/workflows/spree/claims/resolve.rb@@ -14,13 +14,19 @@ module Spree# @param resolution [String] one of Spree::Claim::RESOLUTIONS# @param refund_method [String] 'store_credit' or 'original_payment'# @param amount [BigDecimal, Numeric, nil] defaults to the claim total+ # @param replacement_line_item_ids [Array<Integer>, nil] which lines to+ # replace. Nil keeps whatever was flagged when the claim was opened —+ # the merchant usually decides what to send at resolution time, not+ # when the customer first reported the problem.# @param resolver [Object, nil]- def perform(claim:, resolution:, refund_method: 'store_credit', amount: nil, resolver: nil)+ def perform(claim:, resolution:, refund_method: 'store_credit', amount: nil,+ replacement_line_item_ids: nil, resolver: nil)super@refunds = []@fulfillments = []step :ensure_resolvable+ step :apply_replacement_selection unless replacement_line_item_ids.nil?step :resolve_amount if refunding?run_hooks :validate@@ -68,6 +74,17 @@ module Spreefailure(claim, :refund_exceeds_paid) if @amount_to_refund > ceilingend+ # Flags exactly the chosen lines, so resolving twice with different+ # choices cannot leave stale flags behind.+ def apply_replacement_selection+ chosen = Array(replacement_line_item_ids).map(&:to_s)++ claim.claim_line_items.each do |line|+ line.update!(send_replacement: chosen.include?(line.id.to_s))+ end+ claim.claim_line_items.reload+ end+def build_replacement_fulfillmentsunits = claim.replacement_line_items.map do |line|claim.order.fulfillment_items.new(