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.

Rebuild the seller order page around the dashboard's

Damian Legawiec6efc5e52e01a
diff --git a/packages/seller-dashboard/src/components/orders/fulfillment-fulfill-form.tsx b/packages/seller-dashboard/src/components/orders/fulfillment-fulfill-form.tsx
new file mode 100644
index 0000000000..a8c9f3b499
--- /dev/null
+++ b/packages/seller-dashboard/src/components/orders/fulfillment-fulfill-form.tsx
@@ -0,0 +1,194 @@
+import {
+ Alert,
+ AlertDescription,
+ Button,
+ Checkbox,
+ Field,
+ FieldLabel,
+ Input,
+ Select,
+ SelectContent,
+ SelectItem,
+ SelectTrigger,
+ SelectValue,
+} from '@spree/dashboard-ui'
+import type { Fulfillment } from '@spree/seller-sdk'
+import { useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { useFulfillmentActions } from '../../hooks/use-fulfillments'
+import { useTrackingCarriers } from '../../hooks/use-reasons'
+
+type Row = { itemId: string; label: string; available: number; quantity: number }
+
+function initialRows(fulfillment: Fulfillment): Row[] {
+ return (fulfillment.fulfillment_items ?? []).map((item) => ({
+ // The server addresses what to ship by line item, not by fulfillment item.
+ itemId: item.line_item_id ?? item.id,
+ label: [item.name, item.options_text].filter(Boolean).join(' — ') || item.id,
+ available: item.quantity,
+ quantity: item.quantity,
+ }))
+}
+
+/**
+ * Marking a parcel sent.
+ *
+ * Replaces the card's body rather than opening a dialog: the seller has the
+ * parcel and the tracking number in hand, and shipping part of it is a
+ * normal thing to do — what is left splits onto a parcel of its own.
+ */
+export function FulfillmentFulfillForm({
+ orderId,
+ fulfillment,
+ onDone,
+}: {
+ orderId: string
+ fulfillment: Fulfillment
+ onDone: () => void
+}) {
+ const { t } = useTranslation()
+ const { fulfill } = useFulfillmentActions(orderId)
+ const { data: carriersData } = useTrackingCarriers()
+
+ const [rows, setRows] = useState<Row[]>(() => initialRows(fulfillment))
+ const [tracking, setTracking] = useState('')
+ const [carrier, setCarrier] = useState('')
+ const [notifyCustomer, setNotifyCustomer] = useState(true)
+
+ const carrierOptions = [
+ { value: '', label: t('orders.fulfillments.carrier_auto') },
+ ...(carriersData?.data ?? []).map((option) => ({ value: option.id, label: option.name })),
+ ]
+
+ const selectedUnits = rows.reduce((total, row) => total + row.quantity, 0)
+ const totalUnits = rows.reduce((total, row) => total + row.available, 0)
+ const partial = selectedUnits > 0 && selectedUnits < totalUnits
+
+ function setQuantity(itemId: string, quantity: number) {
+ setRows((current) =>
+ current.map((row) =>
+ row.itemId === itemId
+ ? { ...row, quantity: Math.max(0, Math.min(row.available, quantity)) }
+ : row,
+ ),
+ )
+ }
+
+ async function handleShip() {
+ await fulfill
+ .mutateAsync({
+ fulfillmentId: fulfillment.id,
+ tracking: tracking.trim() || undefined,
+ tracking_carrier: carrier || undefined,
+ notify_customer: notifyCustomer,
+ // Omitted entirely when everything is going, so the server ships the
+ // parcel as it stands rather than splitting it against itself.
+ items: partial
+ ? rows
+ .filter((row) => row.quantity > 0)
+ .map((row) => ({ item_id: row.itemId, quantity: row.quantity }))
+ : undefined,
+ })
+ .then(onDone)
+ .catch(() => undefined)
+ }
+
+ return (
+ <div className="flex flex-col gap-4">
+ <div className="flex flex-col gap-2">
+ {rows.map((row) => (
+ <div key={row.itemId} className="flex items-center justify-between gap-3">
+ <label
+ className="flex min-w-0 items-center gap-2 text-sm"
+ htmlFor={`ship-${row.itemId}`}
+ >
+ <Checkbox
+ id={`ship-${row.itemId}`}
+ checked={row.quantity > 0}
+ onCheckedChange={(checked) => setQuantity(row.itemId, checked ? row.available : 0)}
+ />
+ <span className="truncate">{row.label}</span>
+ </label>
+ <Input
+ type="number"
+ min={0}
+ max={row.available}
+ value={row.quantity}
+ className="w-20"
+ aria-label={t('orders.fulfillments.quantity_for', { name: row.label })}
+ onChange={(event) => setQuantity(row.itemId, Number(event.target.value))}
+ />
+ </div>
+ ))}
+ </div>
+
+ <p className="text-muted-foreground text-xs">
+ {t('orders.fulfillments.units_selected', { selected: selectedUnits, total: totalUnits })}
+ </p>
+
+ {partial && (
+ <Alert>
+ <AlertDescription>{t('orders.fulfillments.partial_warning')}</AlertDescription>
+ </Alert>
+ )}
+
+ <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
+ <Field>
+ <FieldLabel htmlFor={`fulfill-tracking-${fulfillment.id}`}>
+ {t('orders.tracking_label')}
+ </FieldLabel>
+ <Input
+ id={`fulfill-tracking-${fulfillment.id}`}
+ value={tracking}
+ placeholder={t('orders.tracking_placeholder')}
+ onChange={(event) => setTracking(event.target.value)}
+ />
+ </Field>
+
+ <Field>
+ <FieldLabel htmlFor={`fulfill-carrier-${fulfillment.id}`}>
+ {t('orders.fulfillments.carrier_label')}
+ </FieldLabel>
+ <Select
+ items={carrierOptions}
+ value={carrier}
+ onValueChange={(value) => setCarrier((value as string) ?? '')}
+ >
+ <SelectTrigger id={`fulfill-carrier-${fulfillment.id}`}>
+ <SelectValue />
+ </SelectTrigger>
+ <SelectContent>
+ {carrierOptions.map((option) => (
+ <SelectItem key={option.value} value={option.value}>
+ {option.label}
+ </SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
+ </Field>
+ </div>
+
+ <label className="flex items-center gap-2 text-sm" htmlFor={`notify-${fulfillment.id}`}>
+ <Checkbox
+ id={`notify-${fulfillment.id}`}
+ checked={notifyCustomer}
+ onCheckedChange={(checked) => setNotifyCustomer(!!checked)}
+ />
+ {t('orders.fulfillments.notify_customer')}
+ </label>
+
+ <div className="flex justify-end gap-2">
+ <Button type="button" variant="outline" onClick={onDone}>
+ {t('common.cancel')}
+ </Button>
+ <Button
+ type="button"
+ disabled={fulfill.isPending || selectedUnits === 0}
+ onClick={handleShip}
+ >
+ {fulfill.isPending ? t('orders.fulfilling') : t('orders.fulfill')}
+ </Button>
+ </div>
+ </div>
+ )
+}
diff --git a/packages/seller-dashboard/src/components/orders/fulfillment-split-dialog.tsx b/packages/seller-dashboard/src/components/orders/fulfillment-split-dialog.tsx
new file mode 100644
index 0000000000..3bed0be09f
--- /dev/null
+++ b/packages/seller-dashboard/src/components/orders/fulfillment-split-dialog.tsx
@@ -0,0 +1,135 @@
+import {
+ Button,
+ Dialog,
+ DialogBody,
+ DialogContent,
+ DialogDescription,
+ DialogFooter,
+ DialogHeader,
+ DialogTitle,
+ Field,
+ FieldError,
+ FieldLabel,
+ Input,
+ Select,
+ SelectContent,
+ SelectItem,
+ SelectTrigger,
+ SelectValue,
+ useConfirm,
+} from '@spree/dashboard-ui'
+import type { Fulfillment } from '@spree/seller-sdk'
+import { useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { useFulfillmentActions } from '../../hooks/use-fulfillments'
+
+/**
+ * Moves part of a parcel onto one of its own, for goods leaving separately.
+ *
+ * One variant at a time, which is the granularity the transfer works at —
+ * splitting several apart is several splits.
+ */
+export function FulfillmentSplitDialog({
+ orderId,
+ fulfillment,
+ open,
+ onOpenChange,
+}: {
+ orderId: string
+ fulfillment: Fulfillment
+ open: boolean
+ onOpenChange: (open: boolean) => void
+}) {
+ const { t } = useTranslation()
+ const confirm = useConfirm()
+ const { split } = useFulfillmentActions(orderId)
+
+ const units = (fulfillment.fulfillment_items ?? []).map((item) => ({
+ value: item.variant_id ?? item.id,
+ label: [item.name, item.options_text].filter(Boolean).join(' — ') || item.id,
+ quantity: item.quantity,
+ }))
+
+ const [variantId, setVariantId] = useState(units[0]?.value ?? '')
+ const [quantity, setQuantity] = useState(1)
+
+ const selected = units.find((unit) => unit.value === variantId)
+ const totalUnits = units.reduce((total, unit) => total + unit.quantity, 0)
+ // Moving everything is not a split — it empties the parcel and leaves an
+ // orphan behind, which is never what was meant.
+ const wouldEmpty = quantity >= totalUnits
+ const invalid = !variantId || quantity < 1 || wouldEmpty || quantity > (selected?.quantity ?? 0)
+
+ async function handleSplit() {
+ const ok = await confirm({
+ title: t('orders.fulfillments.split_title'),
+ message: t('orders.fulfillments.confirm_split'),
+ confirmLabel: t('orders.fulfillments.split'),
+ })
+ if (!ok) return
+
+ await split
+ .mutateAsync({ fulfillmentId: fulfillment.id, variant_id: variantId, quantity })
+ .then(() => onOpenChange(false))
+ .catch(() => undefined)
+ }
+
+ return (
+ <Dialog open={open} onOpenChange={onOpenChange}>
+ <DialogContent>
+ <DialogHeader>
+ <DialogTitle>{t('orders.fulfillments.split_title')}</DialogTitle>
+ <DialogDescription>{t('orders.fulfillments.split_description')}</DialogDescription>
+ </DialogHeader>
+
+ <DialogBody>
+ <div className="flex flex-col gap-4">
+ <Field>
+ <FieldLabel htmlFor="split-variant">{t('orders.fulfillments.split_item')}</FieldLabel>
+ <Select
+ items={units}
+ value={variantId}
+ onValueChange={(value) => setVariantId((value as string) ?? '')}
+ >
+ <SelectTrigger id="split-variant">
+ <SelectValue />
+ </SelectTrigger>
+ <SelectContent>
+ {units.map((unit) => (
+ <SelectItem key={unit.value} value={unit.value}>
+ {unit.label}
+ </SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
+ </Field>
+
+ <Field>
+ <FieldLabel htmlFor="split-quantity">
+ {t('orders.fulfillments.split_quantity')}
+ </FieldLabel>
+ <Input
+ id="split-quantity"
+ type="number"
+ min={1}
+ max={selected?.quantity ?? 1}
+ value={quantity}
+ onChange={(event) => setQuantity(Number(event.target.value))}
+ />
+ {wouldEmpty && <FieldError>{t('orders.fulfillments.split_would_empty')}</FieldError>}
+ </Field>
+ </div>
+ </DialogBody>
+
+ <DialogFooter>
+ <Button type="button" variant="outline" onClick={() => onOpenChange(false)}>
+ {t('common.cancel')}
+ </Button>
+ <Button type="button" disabled={invalid || split.isPending} onClick={handleSplit}>
+ {split.isPending ? t('orders.fulfillments.splitting') : t('orders.fulfillments.split')}
+ </Button>
+ </DialogFooter>
+ </DialogContent>
+ </Dialog>
+ )
+}
diff --git a/packages/seller-dashboard/src/components/orders/fulfillment-tracking-dialog.tsx b/packages/seller-dashboard/src/components/orders/fulfillment-tracking-dialog.tsx
new file mode 100644
index 0000000000..0acbff10f9
--- /dev/null
+++ b/packages/seller-dashboard/src/components/orders/fulfillment-tracking-dialog.tsx
@@ -0,0 +1,127 @@
+import {
+ Button,
+ Dialog,
+ DialogBody,
+ DialogContent,
+ DialogDescription,
+ DialogFooter,
+ DialogHeader,
+ DialogTitle,
+ Field,
+ FieldLabel,
+ Input,
+ Select,
+ SelectContent,
+ SelectItem,
+ SelectTrigger,
+ SelectValue,
+} from '@spree/dashboard-ui'
+import type { Fulfillment } from '@spree/seller-sdk'
+import { useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { useFulfillmentActions } from '../../hooks/use-fulfillments'
+import { useTrackingCarriers } from '../../hooks/use-reasons'
+
+/**
+ * Adds or corrects a parcel's tracking number after it has gone out.
+ *
+ * Separate from marking it shipped: a seller who mistyped a number, or who
+ * only got it from the post office afterwards, is not shipping the parcel
+ * again.
+ */
+export function FulfillmentTrackingDialog({
+ orderId,
+ fulfillment,
+ open,
+ onOpenChange,
+}: {
+ orderId: string
+ fulfillment: Fulfillment
+ open: boolean
+ onOpenChange: (open: boolean) => void
+}) {
+ const { t } = useTranslation()
+ const { update } = useFulfillmentActions(orderId)
+ const { data: carriersData } = useTrackingCarriers(open)
+
+ const [tracking, setTracking] = useState(fulfillment.tracking ?? '')
+ // '' means "work it out from the number" — the server pins the carrier
+ // itself when the format is recognisable.
+ const [carrier, setCarrier] = useState(fulfillment.tracking_carrier ?? '')
+
+ const carrierOptions = [
+ { value: '', label: t('orders.fulfillments.carrier_auto') },
+ ...(carriersData?.data ?? []).map((option) => ({ value: option.id, label: option.name })),
+ ]
+
+ async function handleSave() {
+ await update
+ .mutateAsync({
+ fulfillmentId: fulfillment.id,
+ tracking: tracking.trim(),
+ tracking_carrier: carrier,
+ })
+ .then(() => onOpenChange(false))
+ .catch(() => undefined)
+ }
+
+ return (
+ <Dialog open={open} onOpenChange={onOpenChange}>
+ <DialogContent>
+ <DialogHeader>
+ <DialogTitle>
+ {fulfillment.tracking
+ ? t('orders.fulfillments.edit_tracking_title')
+ : t('orders.fulfillments.add_tracking_title')}
+ </DialogTitle>
+ <DialogDescription>{t('orders.fulfillments.tracking_description')}</DialogDescription>
+ </DialogHeader>
+
+ <DialogBody>
+ <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
+ <Field>
+ <FieldLabel htmlFor="tracking-number">{t('orders.tracking_label')}</FieldLabel>
+ <Input
+ id="tracking-number"
+ value={tracking}
+ placeholder={t('orders.tracking_placeholder')}
+ onChange={(event) => setTracking(event.target.value)}
+ />
+ </Field>
+
+ <Field>
+ <FieldLabel htmlFor="tracking-carrier">
+ {t('orders.fulfillments.carrier_label')}
+ </FieldLabel>
+ <Select
+ items={carrierOptions}
+ value={carrier}
+ onValueChange={(value) => setCarrier((value as string) ?? '')}
+ >
+ <SelectTrigger id="tracking-carrier">
+ <SelectValue />
+ </SelectTrigger>
+ <SelectContent>
+ {carrierOptions.map((option) => (
+ <SelectItem key={option.value} value={option.value}>
+ {option.label}
+ </SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
+ </Field>
+ </div>
+ </DialogBody>
+
+ <DialogFooter>
+ <Button type="button" variant="outline" onClick={() => onOpenChange(false)}>
+ {t('common.cancel')}
+ </Button>
+ <Button type="button" disabled={update.isPending} onClick={handleSave}>
+ {update.isPending ? t('common.saving') : t('common.save')}
+ </Button>
+ </DialogFooter>
+ </DialogContent>
+ </Dialog>
+ )
+}
diff --git a/packages/seller-dashboard/src/components/orders/fulfillments-card.tsx b/packages/seller-dashboard/src/components/orders/fulfillments-card.tsx
new file mode 100644
index 0000000000..a8190daa7e
--- /dev/null
+++ b/packages/seller-dashboard/src/components/orders/fulfillments-card.tsx
@@ -0,0 +1,229 @@
+import {
+ Button,
+ Card,
+ CardAction,
+ CardContent,
+ CardHeader,
+ CardTitle,
+ DropdownMenu,
+ DropdownMenuContent,
+ DropdownMenuItem,
+ DropdownMenuSeparator,
+ DropdownMenuTrigger,
+ StatusBadge,
+ useConfirm,
+} from '@spree/dashboard-ui'
+import { EllipsisVerticalIcon, MapPinIcon, TruckIcon } from '@spree/dashboard-ui/icons'
+import type { Fulfillment, Order } from '@spree/seller-sdk'
+import { useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { useFulfillmentActions } from '../../hooks/use-fulfillments'
+import { FulfillmentFulfillForm } from './fulfillment-fulfill-form'
+import { FulfillmentSplitDialog } from './fulfillment-split-dialog'
+import { FulfillmentTrackingDialog } from './fulfillment-tracking-dialog'
+
+// A parcel that has not gone out is the only one still to ship or cancel;
+// one that has is the only one that can be confirmed delivered. Reading
+// these off "not unfulfilled" once badged a canceled parcel as a success.
+const CAN_SHIP = ['unfulfilled']
+const CAN_CANCEL = ['unfulfilled']
+const CAN_MARK_DELIVERED = ['fulfilled']
+
+/** Every parcel owed on this order, and what the seller can do with each. */
+export function FulfillmentsCard({ order }: { order: Order }) {
+ const { t } = useTranslation()
+ const fulfillments = order.fulfillments ?? []
+
+ return (
+ <Card>
+ <CardHeader>
+ <CardTitle className="flex items-center gap-2">
+ <TruckIcon className="size-4" />
+ {t('orders.fulfillments.title')}
+ </CardTitle>
+ {order.fulfillment_status && (
+ <CardAction>
+ <StatusBadge
+ status={order.fulfillment_status}
+ label={t(`orders.fulfillment_statuses.${order.fulfillment_status}`)}
+ />
+ </CardAction>
+ )}
+ </CardHeader>
+
+ <CardContent className="flex flex-col gap-3">
+ {fulfillments.length === 0 ? (
+ <p className="text-muted-foreground text-sm">{t('orders.fulfillments.empty')}</p>
+ ) : (
+ fulfillments.map((fulfillment) => (
+ <FulfillmentRow key={fulfillment.id} orderId={order.id} fulfillment={fulfillment} />
+ ))
+ )}
+ </CardContent>
+ </Card>
+ )
+}
+
+function FulfillmentRow({ orderId, fulfillment }: { orderId: string; fulfillment: Fulfillment }) {
+ const { t } = useTranslation()
+ const confirm = useConfirm()
+ const { cancel, resume, markDelivered } = useFulfillmentActions(orderId)
+
+ const [shipping, setShipping] = useState(false)
+ const [trackingOpen, setTrackingOpen] = useState(false)
+ const [splitOpen, setSplitOpen] = useState(false)
+
+ const status = fulfillment.status ?? ''
+ const shippable = CAN_SHIP.includes(status)
+ const cancelable = CAN_CANCEL.includes(status)
+ const deliverable = CAN_MARK_DELIVERED.includes(status)
+ const splittable = shippable && (fulfillment.fulfillment_items?.length ?? 0) > 0
+
+ async function handleCancel() {
+ const ok = await confirm({
+ title: t('orders.fulfillments.cancel_title'),
+ message: t('orders.fulfillments.cancel_message'),
+ variant: 'destructive',
+ confirmLabel: t('orders.fulfillments.cancel'),
+ })
+ if (!ok) return
+ cancel.mutate(fulfillment.id)
+ }
+
+ return (
+ <Card variant="nested">
+ <CardHeader>
+ <CardTitle className="text-sm">{fulfillment.number}</CardTitle>
+ <CardAction className="flex items-center gap-2">
+ <StatusBadge
+ status={status}
+ label={t(`orders.fulfillment_statuses.${status}`, { defaultValue: status })}
+ />
+ <DropdownMenu>
+ <DropdownMenuTrigger
+ render={
+ <Button variant="ghost" size="icon" aria-label={t('common.actions')}>
+ <EllipsisVerticalIcon className="size-4" />
+ </Button>
+ }
+ />
+ <DropdownMenuContent align="end">
+ <DropdownMenuItem onClick={() => setTrackingOpen(true)}>
+ {fulfillment.tracking
+ ? t('orders.fulfillments.edit_tracking')
+ : t('orders.fulfillments.add_tracking')}
+ </DropdownMenuItem>
+ {splittable && (
+ <DropdownMenuItem onClick={() => setSplitOpen(true)}>
+ {t('orders.fulfillments.split')}
+ </DropdownMenuItem>
+ )}
+ {deliverable && (
+ <DropdownMenuItem
+ disabled={markDelivered.isPending}
+ onClick={() => markDelivered.mutate(fulfillment.id)}
+ >
+ {t('orders.fulfillments.mark_delivered')}
+ </DropdownMenuItem>
+ )}
+ {status === 'canceled' && (
+ <DropdownMenuItem
+ disabled={resume.isPending}
+ onClick={() => resume.mutate(fulfillment.id)}
+ >
+ {t('orders.fulfillments.resume')}
+ </DropdownMenuItem>
+ )}
+ {cancelable && (
+ <>
+ <DropdownMenuSeparator />
+ <DropdownMenuItem
+ variant="destructive"
+ disabled={cancel.isPending}
+ onClick={handleCancel}
+ >
+ {t('orders.fulfillments.cancel')}
+ </DropdownMenuItem>
+ </>
+ )}
+ </DropdownMenuContent>
+ </DropdownMenu>
+ </CardAction>
+ </CardHeader>
+
+ <CardContent className="flex flex-col gap-3">
+ {fulfillment.stock_location_name && (
+ <p className="flex items-center gap-1.5 text-muted-foreground text-sm">
+ <MapPinIcon className="size-3.5 shrink-0" />
+ {t('orders.ships_from', { name: fulfillment.stock_location_name })}
+ </p>
+ )}
+
+ {fulfillment.delivery_method_name && (
+ <p className="text-muted-foreground text-sm">{fulfillment.delivery_method_name}</p>
+ )}
+
+ {shipping ? (
+ <FulfillmentFulfillForm
+ orderId={orderId}
+ fulfillment={fulfillment}
+ onDone={() => setShipping(false)}
+ />
+ ) : (
+ <>
+ {fulfillment.fulfillment_items?.map((item) => (
+ <div key={item.id} className="flex items-center justify-between gap-3 text-sm">
+ <span className="truncate">
+ {[item.name, item.options_text].filter(Boolean).join(' — ')}
+ </span>
+ <span className="shrink-0 text-muted-foreground">× {item.quantity}</span>
+ </div>
+ ))}
+
+ {fulfillment.tracking && (
+ <p className="text-sm">
+ {t('orders.tracking', { number: fulfillment.tracking })}
+ {fulfillment.tracking_url && (
+ <>
+ {' · '}
+ <a
+ href={fulfillment.tracking_url}
+ target="_blank"
+ rel="noreferrer"
+ className="underline"
+ >
+ {t('orders.fulfillments.track_parcel')}
+ </a>
+ </>
+ )}
+ </p>
+ )}
+
+ {shippable && (
+ <div className="flex justify-end">
+ <Button type="button" onClick={() => setShipping(true)}>
+ {t('orders.fulfill')}
+ </Button>
+ </div>
+ )}
+ </>
+ )}
+ </CardContent>
+
+ <FulfillmentTrackingDialog
+ orderId={orderId}
+ fulfillment={fulfillment}
+ open={trackingOpen}
+ onOpenChange={setTrackingOpen}
+ />
+ {splittable && (
+ <FulfillmentSplitDialog
+ orderId={orderId}
+ fulfillment={fulfillment}
+ open={splitOpen}
+ onOpenChange={setSplitOpen}
+ />
+ )}
+ </Card>
+ )
+}
diff --git a/packages/seller-dashboard/src/components/orders/order-cards.tsx b/packages/seller-dashboard/src/components/orders/order-cards.tsx
new file mode 100644
index 0000000000..3a81430444
--- /dev/null
+++ b/packages/seller-dashboard/src/components/orders/order-cards.tsx
@@ -0,0 +1,130 @@
+import {
+ AddressBlock,
+ Card,
+ CardContent,
+ CardHeader,
+ CardTitle,
+ Thumbnail,
+} from '@spree/dashboard-ui'
+import type { Order } from '@spree/seller-sdk'
+import { useTranslation } from 'react-i18next'
+
+/** What was bought. */
+export function OrderItemsCard({ order }: { order: Order }) {
+ const { t } = useTranslation()
+
+ return (
+ <Card>
+ <CardHeader>
+ <CardTitle>{t('orders.items')}</CardTitle>
+ </CardHeader>
+ <CardContent className="flex flex-col gap-3">
+ {(order.items ?? []).map((item) => (
+ <div key={item.id} className="flex items-center justify-between gap-3">
+ <div className="flex min-w-0 items-center gap-3">
+ {item.thumbnail_url && <Thumbnail src={item.thumbnail_url} alt={item.name ?? ''} />}
+ <div className="min-w-0">
+ <div className="truncate text-sm font-medium">{item.name}</div>
+ <div className="truncate text-muted-foreground text-xs">
+ {[item.sku, item.options_text].filter(Boolean).join(' · ')}
+ </div>
+ </div>
+ </div>
+ <div className="flex shrink-0 items-center gap-4 text-sm">
+ <span className="text-muted-foreground">× {item.quantity}</span>
+ <span>{item.display_total}</span>
+ </div>
+ </div>
+ ))}
+ </CardContent>
+ </Card>
+ )
+}
+
+/**
+ * What the sale came to.
+ *
+ * The seller's own figures — what the goods were worth, the tax on them and
+ * the total. How the customer paid the marketplace is not shown here: that is
+ * the group's payment, and what the seller is owed is the commission ledger.
+ */
+export function OrderSummaryCard({ order }: { order: Order }) {
+ const { t } = useTranslation()
+
+ const rows = [
+ { label: t('orders.summary.item_total'), value: order.display_item_total },
+ { label: t('orders.summary.tax_total'), value: order.display_tax_total },
+ ].filter((row) => !!row.value)
+
+ return (
+ <Card>
+ <CardHeader>
+ <CardTitle>{t('orders.summary.title')}</CardTitle>
+ </CardHeader>
+ <CardContent className="flex flex-col gap-2 text-sm">
+ {rows.map((row) => (
+ <div key={row.label} className="flex items-center justify-between gap-3">
+ <span className="text-muted-foreground">{row.label}</span>
+ <span>{row.value}</span>
+ </div>
+ ))}
+ <div className="flex items-center justify-between gap-3 border-t pt-2 font-medium">
+ <span>{t('orders.summary.total')}</span>
+ <span>{order.display_total}</span>
+ </div>
+ </CardContent>
+ </Card>
+ )
+}
+
+/**
+ * Where the parcel goes and who the invoice is for.
+ *
+ * No email address: a seller reaching the customer about a delivery has the
+ * phone on the shipping address, and an email is the one contact detail that
+ * would let a marketplace's customer be taken off it.
+ */
+export function OrderCustomerCard({ order }: { order: Order }) {
+ const { t } = useTranslation()
+
+ return (
+ <Card>
+ <CardHeader>
+ <CardTitle>{t('orders.customer.title')}</CardTitle>
+ </CardHeader>
+ <CardContent className="flex flex-col gap-4">
+ {order.shipping_address && (
+ <div className="flex flex-col gap-1">
+ <p className="text-muted-foreground text-xs uppercase">
+ {t('orders.shipping_address')}
+ </p>
+ <AddressBlock address={order.shipping_address} />
+ </div>
+ )}
+ {order.billing_address && (
+ <div className="flex flex-col gap-1">
+ <p className="text-muted-foreground text-xs uppercase">{t('orders.billing_address')}</p>
+ <AddressBlock address={order.billing_address} />
+ </div>
+ )}
+ </CardContent>
+ </Card>
+ )
+}
+
+/** What the customer asked for when they placed the order. */
+export function OrderNoteCard({ order }: { order: Order }) {
+ const { t } = useTranslation()
+ if (!order.customer_note) return null
+
+ return (
+ <Card>
+ <CardHeader>
+ <CardTitle>{t('orders.customer_note')}</CardTitle>
+ </CardHeader>
+ <CardContent>
+ <p className="text-sm whitespace-pre-wrap">{order.customer_note}</p>
+ </CardContent>
+ </Card>
+ )
+}
diff --git a/packages/seller-dashboard/src/components/orders/post-sale-cards.tsx b/packages/seller-dashboard/src/components/orders/post-sale-cards.tsx
new file mode 100644
index 0000000000..da97b854a3
--- /dev/null
+++ b/packages/seller-dashboard/src/components/orders/post-sale-cards.tsx
@@ -0,0 +1,437 @@
+import {
+ Button,
+ Card,
+ CardAction,
+ CardContent,
+ CardHeader,
+ CardTitle,
+ Dialog,
+ DialogBody,
+ DialogContent,
+ DialogFooter,
+ DialogHeader,
+ DialogTitle,
+ DropdownMenu,
+ DropdownMenuContent,
+ DropdownMenuItem,
+ DropdownMenuSeparator,
+ DropdownMenuTrigger,
+ Field,
+ FieldLabel,
+ Input,
+ Select,
+ SelectContent,
+ SelectItem,
+ SelectTrigger,
+ SelectValue,
+ StatusBadge,
+ useConfirm,
+} from '@spree/dashboard-ui'
+import {
+ ArrowLeftRightIcon,
+ BanIcon,
+ EllipsisVerticalIcon,
+ PlusIcon,
+ ShieldAlertIcon,
+} from '@spree/dashboard-ui/icons'
+import type { Claim, Order } from '@spree/seller-sdk'
+import { useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import {
+ useClaimActions,
+ useExchangeActions,
+ useOrderClaims,
+ useOrderExchanges,
+} from '../../hooks/use-post-sale'
+import { CreateClaimDialog } from './post-sale-create-dialogs'
+
+/**
+ * How a variant reads on a post-sale line. A seller's variant serializer
+ * carries the SKU and its option values, never a name — the name lives on the
+ * product — so the label is built from what is actually there.
+ */
+function variantLabel(
+ variant: { sku?: string | null; options_text?: string | null } | undefined,
+ fallback: string | null | undefined,
+): string {
+ const parts = [variant?.sku, variant?.options_text].filter(Boolean)
+ return parts.length > 0 ? parts.join(' · ') : (fallback ?? '')
+}
+
+const EXCHANGE_ACTIONABLE = ['requested', 'approved', 'received']
+const CLAIM_ACTIONABLE = ['open', 'approved']
+
+/**
+ * Goods swapped for different ones.
+ *
+ * Read plus the status moves; opening one needs a replacement variant picker,
+ * which the seller's own catalogue search will bring — until then an exchange
+ * is opened by the operator or the customer and worked here.
+ */
+export function ExchangesCard({ order }: { order: Order }) {
+ const { t } = useTranslation()
+ const confirm = useConfirm()
+ const { data } = useOrderExchanges(order.id)
+ const { approve, receive, fulfill, cancel } = useExchangeActions(order.id)
+
+ const exchanges = data?.data ?? []
+ if (exchanges.length === 0) return null
+
+ async function handleCancel(id: string) {
+ const ok = await confirm({
+ title: t('orders.post_sale.exchanges.cancel_title'),
+ message: t('orders.post_sale.exchanges.cancel_message'),
+ variant: 'destructive',
+ confirmLabel: t('orders.post_sale.cancel'),
+ })
+ if (!ok) return
+ cancel.mutate(id)
+ }
+
+ return (
+ <Card>
+ <CardHeader>
+ <CardTitle className="flex items-center gap-2">
+ <ArrowLeftRightIcon className="size-4" />
+ {t('orders.post_sale.exchanges.title')}
+ </CardTitle>
+ </CardHeader>
+
+ <CardContent className="flex flex-col gap-3">
+ {exchanges.map((exchange) => (
+ <Card key={exchange.id} variant="nested">
+ <CardHeader>
+ <CardTitle className="text-sm">{exchange.number}</CardTitle>
+ <CardAction className="flex items-center gap-2">
+ <StatusBadge
+ status={exchange.status}
+ label={t(`orders.post_sale.statuses.${exchange.status}`, {
+ defaultValue: exchange.status,
+ })}
+ />
+ {EXCHANGE_ACTIONABLE.includes(exchange.status) && (
+ <DropdownMenu>
+ <DropdownMenuTrigger
+ render={
+ <Button variant="ghost" size="icon" aria-label={t('common.actions')}>
+ <EllipsisVerticalIcon className="size-4" />
+ </Button>
+ }
+ />
+ <DropdownMenuContent align="end">
+ {exchange.status === 'requested' && (
+ <DropdownMenuItem onClick={() => approve.mutate(exchange.id)}>
+ {t('orders.post_sale.approve')}
+ </DropdownMenuItem>
+ )}
+ {exchange.status === 'approved' && (
+ <DropdownMenuItem
+ onClick={() => receive.mutate({ exchangeId: exchange.id })}
+ >
+ {t('orders.post_sale.exchanges.receive')}
+ </DropdownMenuItem>
+ )}
+ {exchange.status === 'received' && (
+ <DropdownMenuItem
+ onClick={() => fulfill.mutate({ exchangeId: exchange.id })}
+ >
+ {t('orders.post_sale.exchanges.fulfill')}
+ </DropdownMenuItem>
+ )}
+ <DropdownMenuSeparator />
+ <DropdownMenuItem
+ variant="destructive"
+ onClick={() => handleCancel(exchange.id)}
+ >
+ {t('orders.post_sale.cancel')}
+ </DropdownMenuItem>
+ </DropdownMenuContent>
+ </DropdownMenu>
+ )}
+ </CardAction>
+ </CardHeader>
+
+ <CardContent className="flex flex-col gap-2">
+ {exchange.exchange_line_items?.map((line) => (
+ <div key={line.id} className="flex items-center justify-between gap-3 text-sm">
+ <span className="truncate">
+ {variantLabel(line.original_variant, line.original_variant_id)} →{' '}
+ {variantLabel(line.new_variant, line.new_variant_id)}
+ </span>
+ <span className="shrink-0 text-muted-foreground">× {line.quantity}</span>
+ </div>
+ ))}
+ <p className="text-muted-foreground text-sm">
+ {t('orders.post_sale.exchanges.price_difference', {
+ amount: exchange.display_price_difference,
+ })}
+ </p>
+ </CardContent>
+ </Card>
+ ))}
+ </CardContent>
+ </Card>
+ )
+}
+
+/** Something went wrong with a delivery, and the seller puts it right. */
+export function ClaimsCard({ order }: { order: Order }) {
+ const { t } = useTranslation()
+ const confirm = useConfirm()
+ const { data } = useOrderClaims(order.id)
+ const { approve, deny, cancel } = useClaimActions(order.id)
+
+ const [createOpen, setCreateOpen] = useState(false)
+ const [resolving, setResolving] = useState<Claim | null>(null)
+
+ const claims = data?.data ?? []
+ const canCreate = (order.items ?? []).length > 0
+
+ async function handleDeny(id: string) {
+ const ok = await confirm({
+ title: t('orders.post_sale.claims.deny_title'),
+ message: t('orders.post_sale.claims.deny_message'),
+ variant: 'destructive',
+ confirmLabel: t('orders.post_sale.claims.deny'),
+ })
+ if (!ok) return
+ deny.mutate(id)
+ }
+
+ return (
+ <Card>
+ <CardHeader>
+ <CardTitle className="flex items-center gap-2">
+ <ShieldAlertIcon className="size-4" />
+ {t('orders.post_sale.claims.title')}
+ </CardTitle>
+ {canCreate && (
+ <CardAction>
+ <Button variant="outline" size="sm" onClick={() => setCreateOpen(true)}>
+ <PlusIcon className="size-4" />
+ {t('orders.post_sale.claims.create')}
+ </Button>
+ </CardAction>
+ )}
+ </CardHeader>
+
+ <CardContent className="flex flex-col gap-3">
+ {claims.length === 0 ? (
+ <p className="text-muted-foreground text-sm">{t('orders.post_sale.claims.empty')}</p>
+ ) : (
+ claims.map((claim) => (
+ <Card key={claim.id} variant="nested">
+ <CardHeader>
+ <CardTitle className="text-sm">{claim.number}</CardTitle>
+ <CardAction className="flex items-center gap-2">
+ <StatusBadge
+ status={claim.status}
+ label={t(`orders.post_sale.statuses.${claim.status}`, {
+ defaultValue: claim.status,
+ })}
+ />
+ {CLAIM_ACTIONABLE.includes(claim.status) && (
+ <DropdownMenu>
+ <DropdownMenuTrigger
+ render={
+ <Button variant="ghost" size="icon" aria-label={t('common.actions')}>
+ <EllipsisVerticalIcon className="size-4" />
+ </Button>
+ }
+ />
+ <DropdownMenuContent align="end">
+ {claim.status === 'open' && (
+ <DropdownMenuItem onClick={() => approve.mutate(claim.id)}>
+ {t('orders.post_sale.approve')}
+ </DropdownMenuItem>
+ )}
+ {claim.status === 'approved' && (
+ <DropdownMenuItem onClick={() => setResolving(claim)}>
+ {t('orders.post_sale.claims.resolve')}
+ </DropdownMenuItem>
+ )}
+ <DropdownMenuItem onClick={() => handleDeny(claim.id)}>
+ <BanIcon className="size-4" />
+ {t('orders.post_sale.claims.deny')}
+ </DropdownMenuItem>
+ <DropdownMenuSeparator />
+ <DropdownMenuItem
+ variant="destructive"
+ onClick={() => cancel.mutate(claim.id)}
+ >
+ {t('orders.post_sale.cancel')}
+ </DropdownMenuItem>
+ </DropdownMenuContent>
+ </DropdownMenu>
+ )}
+ </CardAction>
+ </CardHeader>
+
+ <CardContent className="flex flex-col gap-2">
+ {claim.claim_line_items?.map((line) => (
+ <div key={line.id} className="flex items-center justify-between gap-3 text-sm">
+ <span className="min-w-0 truncate">
+ {variantLabel(line.variant, line.variant_id)}
+ {line.description && (
+ <span className="text-muted-foreground"> — {line.description}</span>
+ )}
+ </span>
+ <span className="shrink-0 text-muted-foreground">× {line.quantity}</span>
+ </div>
+ ))}
+ </CardContent>
+ </Card>
+ ))
+ )}
+ </CardContent>
+
+ <CreateClaimDialog order={order} open={createOpen} onOpenChange={setCreateOpen} />
+ {resolving && (
+ <ResolveClaimDialog
+ orderId={order.id}
+ claim={resolving}
+ open
+ onOpenChange={() => setResolving(null)}
+ />
+ )}
+ </Card>
+ )
+}
+
+/** Money back, a replacement, or both. */
+function ResolveClaimDialog({
+ orderId,
+ claim,
+ open,
+ onOpenChange,
+}: {
+ orderId: string
+ claim: Claim
+ open: boolean
+ onOpenChange: (open: boolean) => void
+}) {
+ const { t } = useTranslation()
+ const { resolve } = useClaimActions(orderId)
+
+ const [resolution, setResolution] = useState<'refund' | 'replacement' | 'refund_and_replacement'>(
+ 'refund',
+ )
+ const [amount, setAmount] = useState('')
+ const [method, setMethod] = useState<'original_payment' | 'store_credit'>('store_credit')
+
+ const resolutionOptions = [
+ { value: 'refund', label: t('orders.post_sale.claims.resolutions.refund') },
+ { value: 'replacement', label: t('orders.post_sale.claims.resolutions.replacement') },
+ {
+ value: 'refund_and_replacement',
+ label: t('orders.post_sale.claims.resolutions.refund_and_replacement'),
+ },
+ ]
+ const methodOptions = [
+ { value: 'store_credit', label: t('orders.post_sale.returns.store_credit') },
+ { value: 'original_payment', label: t('orders.post_sale.returns.original_payment') },
+ ]
+
+ const refunding = resolution.includes('refund')
+
+ async function handleResolve() {
+ await resolve
+ .mutateAsync({
+ claimId: claim.id,
+ resolution,
+ refundMethod: refunding ? method : undefined,
+ amount: refunding && amount ? amount : undefined,
+ })
+ .then(() => onOpenChange(false))
+ .catch(() => undefined)
+ }
+
+ return (
+ <Dialog open={open} onOpenChange={onOpenChange}>
+ <DialogContent>
+ <DialogHeader>
+ <DialogTitle>{t('orders.post_sale.claims.resolve_title')}</DialogTitle>
+ </DialogHeader>
+ <DialogBody>
+ <div className="flex flex-col gap-4">
+ <Field>
+ <FieldLabel htmlFor="claim-resolution">
+ {t('orders.post_sale.claims.resolution')}
+ </FieldLabel>
+ <Select
+ items={resolutionOptions}
+ value={resolution}
+ onValueChange={(value) =>
+ setResolution(
+ (value as 'refund' | 'replacement' | 'refund_and_replacement') ?? 'refund',
+ )
+ }
+ >
+ <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-amount">
+ {t('orders.post_sale.returns.amount')}
+ </FieldLabel>
+ <Input
+ id="claim-amount"
+ type="number"
+ step="0.01"
+ min={0}
+ value={amount}
+ onChange={(event) => setAmount(event.target.value)}
+ />
+ </Field>
+
+ <Field>
+ <FieldLabel htmlFor="claim-refund-method">
+ {t('orders.post_sale.returns.refund_method')}
+ </FieldLabel>
+ <Select
+ items={methodOptions}
+ value={method}
+ onValueChange={(value) =>
+ setMethod((value as 'original_payment' | 'store_credit') ?? 'store_credit')
+ }
+ >
+ <SelectTrigger id="claim-refund-method">
+ <SelectValue />
+ </SelectTrigger>
+ <SelectContent>
+ {methodOptions.map((option) => (
+ <SelectItem key={option.value} value={option.value}>
+ {option.label}
+ </SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
+ </Field>
+ </>
+ )}
+ </div>
+ </DialogBody>
+ <DialogFooter>
+ <Button type="button" variant="outline" onClick={() => onOpenChange(false)}>
+ {t('common.cancel')}
+ </Button>
+ <Button type="button" disabled={resolve.isPending} onClick={handleResolve}>
+ {t('orders.post_sale.claims.resolve')}
+ </Button>
+ </DialogFooter>
+ </DialogContent>
+ </Dialog>
+ )
+}
diff --git a/packages/seller-dashboard/src/components/orders/post-sale-create-dialogs.tsx b/packages/seller-dashboard/src/components/orders/post-sale-create-dialogs.tsx
new file mode 100644
index 0000000000..f29d12347e
--- /dev/null
+++ b/packages/seller-dashboard/src/components/orders/post-sale-create-dialogs.tsx
@@ -0,0 +1,275 @@
+import {
+ Button,
+ Dialog,
+ DialogBody,
+ DialogContent,
+ DialogFooter,
+ DialogHeader,
+ DialogTitle,
+ Field,
+ FieldLabel,
+ Input,
+ Select,
+ SelectContent,
+ SelectItem,
+ SelectTrigger,
+ SelectValue,
+ Textarea,
+} from '@spree/dashboard-ui'
+import type { Order } from '@spree/seller-sdk'
+import { useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { useClaimActions, useReturnActions } from '../../hooks/use-post-sale'
+import { type ReasonKind, useReasons } from '../../hooks/use-reasons'
+
+/** Units that actually went out, which is all that can come back. */
+export function fulfilledUnits(order: Order) {
+ return (order.fulfillments ?? []).flatMap((fulfillment) =>
+ (fulfillment.fulfillment_items ?? []).map((item) => ({
+ id: item.id,
+ label: [item.name, item.options_text].filter(Boolean).join(' — ') || item.id,
+ quantity: item.quantity,
+ })),
+ )
+}
+
+type Selection = Record<string, number>
+
+/** A quantity per unit; zero means "not included". */
+function QuantityPicker({
+ units,
+ selection,
+ onChange,
+}: {
+ units: Array<{ id: string; label: string; quantity: number }>
+ selection: Selection
+ onChange: (selection: Selection) => void
+}) {
+ return (
+ <div className="flex flex-col gap-2">
+ {units.map((unit) => (
+ <div key={unit.id} className="flex items-center justify-between gap-3">
+ <span className="min-w-0 truncate text-sm">{unit.label}</span>
+ <Input
+ type="number"
+ min={0}
+ max={unit.quantity}
+ value={selection[unit.id] ?? 0}
+ className="w-20"
+ aria-label={unit.label}
+ onChange={(event) =>
+ onChange({
+ ...selection,
+ [unit.id]: Math.max(0, Math.min(unit.quantity, Number(event.target.value))),
+ })
+ }
+ />
+ </div>
+ ))}
+ </div>
+ )
+}
+
+/**
+ * The reason picker. Optional by design — the API takes a record without one,
+ * so a marketplace that has not filled in its vocabulary yet is not blocked.
+ */
+function ReasonField({
+ kind,
+ value,
+ onChange,
+}: {
+ kind: ReasonKind
+ value: string
+ onChange: (value: string) => void
+}) {
+ const { t } = useTranslation()
+ const { data } = useReasons(kind)
+
+ const reasons = data?.data ?? []
+ if (reasons.length === 0) return null
+
+ const options = reasons.map((reason) => ({ value: reason.id, label: reason.name }))
+
+ return (
+ <Field>
+ <FieldLabel htmlFor={`reason-${kind}`}>{t('orders.post_sale.reason')}</FieldLabel>
+ <Select
+ items={options}
+ value={value}
+ onValueChange={(next) => onChange((next as string) ?? '')}
+ >
+ <SelectTrigger id={`reason-${kind}`}>
+ <SelectValue />
+ </SelectTrigger>
+ <SelectContent>
+ {options.map((option) => (
+ <SelectItem key={option.value} value={option.value}>
+ {option.label}
+ </SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
+ </Field>
+ )
+}
+
+function selectedItems(selection: Selection) {
+ return Object.entries(selection)
+ .filter(([, quantity]) => quantity > 0)
+ .map(([id, quantity]) => ({ id, quantity }))
+}
+
+export function CreateReturnDialog({
+ order,
+ open,
+ onOpenChange,
+}: {
+ order: Order
+ open: boolean
+ onOpenChange: (open: boolean) => void
+}) {
+ const { t } = useTranslation()
+ const { create } = useReturnActions(order.id)
+ const units = fulfilledUnits(order)
+
+ const [selection, setSelection] = useState<Selection>({})
+ const [reasonId, setReasonId] = useState('')
+ const [memo, setMemo] = useState('')
+
+ const chosen = selectedItems(selection)
+
+ async function handleCreate() {
+ await create
+ .mutateAsync({
+ items: chosen.map((item) => ({ fulfillment_item_id: item.id, quantity: item.quantity })),
+ reason_id: reasonId || undefined,
+ memo: memo.trim() || undefined,
+ })
+ .then(() => {
+ setSelection({})
+ setMemo('')
+ onOpenChange(false)
+ })
+ .catch(() => undefined)
+ }
+
+ return (
+ <Dialog open={open} onOpenChange={onOpenChange}>
+ <DialogContent>
+ <DialogHeader>
+ <DialogTitle>{t('orders.post_sale.returns.create_title')}</DialogTitle>
+ </DialogHeader>
+ <DialogBody>
+ <div className="flex flex-col gap-4">
+ <QuantityPicker units={units} selection={selection} onChange={setSelection} />
+ <ReasonField kind="return-reasons" value={reasonId} onChange={setReasonId} />
+ <Field>
+ <FieldLabel htmlFor="return-memo">{t('orders.post_sale.memo')}</FieldLabel>
+ <Textarea
+ id="return-memo"
+ value={memo}
+ onChange={(event) => setMemo(event.target.value)}
+ />
+ </Field>
+ </div>
+ </DialogBody>
+ <DialogFooter>
+ <Button type="button" variant="outline" onClick={() => onOpenChange(false)}>
+ {t('common.cancel')}
+ </Button>
+ <Button
+ type="button"
+ disabled={chosen.length === 0 || create.isPending}
+ onClick={handleCreate}
+ >
+ {t('orders.post_sale.returns.create')}
+ </Button>
+ </DialogFooter>
+ </DialogContent>
+ </Dialog>
+ )
+}
+
+export function CreateClaimDialog({
+ order,
+ open,
+ onOpenChange,
+}: {
+ order: Order
+ open: boolean
+ onOpenChange: (open: boolean) => void
+}) {
+ const { t } = useTranslation()
+ const { create } = useClaimActions(order.id)
+
+ // A claim is about what was bought, not about what shipped — goods that
+ // never arrived are exactly what one is for.
+ const units = (order.items ?? []).map((item) => ({
+ id: item.id,
+ label: [item.name, item.options_text].filter(Boolean).join(' — ') || item.id,
+ quantity: item.quantity,
+ }))
+
+ const [selection, setSelection] = useState<Selection>({})
+ const [reasonId, setReasonId] = useState('')
+ const [description, setDescription] = useState('')
+
+ const chosen = selectedItems(selection)
+
+ async function handleCreate() {
+ await create
+ .mutateAsync({
+ items: chosen.map((item) => ({
+ line_item_id: item.id,
+ quantity: item.quantity,
+ description: description.trim() || undefined,
+ })),
+ reason_id: reasonId || undefined,
+ })
+ .then(() => {
+ setSelection({})
+ setDescription('')
+ onOpenChange(false)
+ })
+ .catch(() => undefined)
+ }
+
+ return (
+ <Dialog open={open} onOpenChange={onOpenChange}>
+ <DialogContent>
+ <DialogHeader>
+ <DialogTitle>{t('orders.post_sale.claims.create_title')}</DialogTitle>
+ </DialogHeader>
+ <DialogBody>
+ <div className="flex flex-col gap-4">
+ <QuantityPicker units={units} selection={selection} onChange={setSelection} />
+ <ReasonField kind="claim-reasons" value={reasonId} onChange={setReasonId} />
+ <Field>
+ <FieldLabel htmlFor="claim-description">
+ {t('orders.post_sale.claims.description')}
+ </FieldLabel>
+ <Textarea
+ id="claim-description"
+ value={description}
+ onChange={(event) => setDescription(event.target.value)}
+ />
+ </Field>
+ </div>
+ </DialogBody>
+ <DialogFooter>
+ <Button type="button" variant="outline" onClick={() => onOpenChange(false)}>
+ {t('common.cancel')}
+ </Button>
+ <Button
+ type="button"
+ disabled={chosen.length === 0 || create.isPending}
+ onClick={handleCreate}
+ >
+ {t('orders.post_sale.claims.create')}
+ </Button>
+ </DialogFooter>
+ </DialogContent>
+ </Dialog>
+ )
+}
diff --git a/packages/seller-dashboard/src/components/orders/returns-card.tsx b/packages/seller-dashboard/src/components/orders/returns-card.tsx
new file mode 100644
index 0000000000..2a500f68bc
--- /dev/null
+++ b/packages/seller-dashboard/src/components/orders/returns-card.tsx
@@ -0,0 +1,407 @@
+import {
+ Badge,
+ Button,
+ Card,
+ CardAction,
+ CardContent,
+ CardHeader,
+ CardTitle,
+ Dialog,
+ DialogBody,
+ DialogContent,
+ DialogFooter,
+ DialogHeader,
+ DialogTitle,
+ DropdownMenu,
+ DropdownMenuContent,
+ DropdownMenuItem,
+ DropdownMenuSeparator,
+ DropdownMenuTrigger,
+ Field,
+ FieldLabel,
+ Input,
+ Select,
+ SelectContent,
+ SelectItem,
+ SelectTrigger,
+ SelectValue,
+ StatusBadge,
+ Switch,
+ useConfirm,
+} from '@spree/dashboard-ui'
+import { EllipsisVerticalIcon, PlusIcon, RotateCcwIcon } from '@spree/dashboard-ui/icons'
+import type { Order, Return, ReturnLineItem } from '@spree/seller-sdk'
+import { useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { useOrderReturns, useReturnActions } from '../../hooks/use-post-sale'
+import { CreateReturnDialog, fulfilledUnits } from './post-sale-create-dialogs'
+
+// Refunded and canceled returns are finished; offering a menu on them would
+// open onto nothing.
+const ACTIONABLE = ['requested', 'approved', 'received']
+
+/**
+ * Goods coming back on this order.
+ *
+ * Each status change is its own action rather than an editable field, because
+ * each carries different arguments — receiving records what actually arrived,
+ * refunding decides where the money goes.
+ */
+export function ReturnsCard({ order }: { order: Order }) {
+ const { t } = useTranslation()
+ const confirm = useConfirm()
+ const { data } = useOrderReturns(order.id)
+ const { approve, cancel } = useReturnActions(order.id)
+
+ const [createOpen, setCreateOpen] = useState(false)
+ const [receiving, setReceiving] = useState<Return | null>(null)
+ const [refunding, setRefunding] = useState<Return | null>(null)
+
+ const returns = data?.data ?? []
+ const canCreate = fulfilledUnits(order).length > 0
+
+ async function handleCancel(returnRecord: Return) {
+ const ok = await confirm({
+ title: t('orders.post_sale.returns.cancel_title'),
+ message: t('orders.post_sale.returns.cancel_message'),
+ variant: 'destructive',
+ confirmLabel: t('orders.post_sale.cancel'),
+ })
+ if (!ok) return
+ cancel.mutate(returnRecord.id)
+ }
+
+ return (
+ <Card>
+ <CardHeader>
+ <CardTitle className="flex items-center gap-2">
+ <RotateCcwIcon className="size-4" />
+ {t('orders.post_sale.returns.title')}
+ </CardTitle>
+ {canCreate && (
+ <CardAction>
+ <Button variant="outline" size="sm" onClick={() => setCreateOpen(true)}>
+ <PlusIcon className="size-4" />
+ {t('orders.post_sale.returns.create')}
+ </Button>
+ </CardAction>
+ )}
+ </CardHeader>
+
+ <CardContent className="flex flex-col gap-3">
+ {returns.length === 0 ? (
+ <p className="text-muted-foreground text-sm">{t('orders.post_sale.returns.empty')}</p>
+ ) : (
+ returns.map((returnRecord) => (
+ <Card key={returnRecord.id} variant="nested">
+ <CardHeader>
+ <CardTitle className="text-sm">{returnRecord.number}</CardTitle>
+ <CardAction className="flex items-center gap-2">
+ <StatusBadge
+ status={returnRecord.status}
+ label={t(`orders.post_sale.statuses.${returnRecord.status}`, {
+ defaultValue: returnRecord.status,
+ })}
+ />
+ {ACTIONABLE.includes(returnRecord.status) && (
+ <DropdownMenu>
+ <DropdownMenuTrigger
+ render={
+ <Button variant="ghost" size="icon" aria-label={t('common.actions')}>
+ <EllipsisVerticalIcon className="size-4" />
+ </Button>
+ }
+ />
+ <DropdownMenuContent align="end">
+ {returnRecord.status === 'requested' && (
+ <DropdownMenuItem onClick={() => approve.mutate(returnRecord.id)}>
+ {t('orders.post_sale.approve')}
+ </DropdownMenuItem>
+ )}
+ {returnRecord.status === 'approved' && (
+ <DropdownMenuItem onClick={() => setReceiving(returnRecord)}>
+ {t('orders.post_sale.returns.receive')}
+ </DropdownMenuItem>
+ )}
+ {returnRecord.status === 'received' && (
+ <DropdownMenuItem onClick={() => setRefunding(returnRecord)}>
+ {t('orders.post_sale.returns.refund')}
+ </DropdownMenuItem>
+ )}
+ <DropdownMenuSeparator />
+ <DropdownMenuItem
+ variant="destructive"
+ onClick={() => handleCancel(returnRecord)}
+ >
+ {t('orders.post_sale.cancel')}
+ </DropdownMenuItem>
+ </DropdownMenuContent>
+ </DropdownMenu>
+ )}
+ </CardAction>
+ </CardHeader>
+
+ <CardContent className="flex flex-col gap-2">
+ {returnRecord.return_line_items?.map((line) => (
+ <ReturnLineRow key={line.id} line={line} />
+ ))}
+ <p className="text-muted-foreground text-sm">
+ {t('orders.post_sale.returns.refund_total', {
+ amount: returnRecord.display_refund_total,
+ })}
+ </p>
+ </CardContent>
+ </Card>
+ ))
+ )}
+ </CardContent>
+
+ <CreateReturnDialog order={order} open={createOpen} onOpenChange={setCreateOpen} />
+ {receiving && (
+ <ReceiveDialog
+ orderId={order.id}
+ returnRecord={receiving}
+ open
+ onOpenChange={() => setReceiving(null)}
+ />
+ )}
+ {refunding && (
+ <RefundDialog
+ orderId={order.id}
+ returnRecord={refunding}
+ open
+ onOpenChange={() => setRefunding(null)}
+ />
+ )}
+ </Card>
+ )
+}
+
+function ReturnLineRow({ line }: { line: ReturnLineItem }) {
+ const { t } = useTranslation()
+ const label =
+ [line.variant?.sku, line.variant?.options_text].filter(Boolean).join(' · ') ||
+ line.variant_id ||
+ ''
+
+ return (
+ <div className="flex items-center justify-between gap-3 text-sm">
+ <span className="truncate">{label}</span>
+ <span className="flex shrink-0 items-center gap-2 text-muted-foreground">
+ {line.received_quantity > 0 && line.received_quantity < line.quantity && (
+ <Badge variant="outline">
+ {t('orders.post_sale.returns.partially_received', {
+ received: line.received_quantity,
+ quantity: line.quantity,
+ })}
+ </Badge>
+ )}
+ {!line.resellable && (
+ <Badge variant="outline">{t('orders.post_sale.returns.not_resellable')}</Badge>
+ )}
+ × {line.quantity}
+ </span>
+ </div>
+ )
+}
+
+/** What actually turned up, and whether it can go back on the shelf. */
+function ReceiveDialog({
+ orderId,
+ returnRecord,
+ open,
+ onOpenChange,
+}: {
+ orderId: string
+ returnRecord: Return
+ open: boolean
+ onOpenChange: (open: boolean) => void
+}) {
+ const { t } = useTranslation()
+ const { receive } = useReturnActions(orderId)
+
+ const lines = returnRecord.return_line_items ?? []
+ const [rows, setRows] = useState<Record<string, { quantity: number; resellable: boolean }>>(() =>
+ Object.fromEntries(
+ lines.map((line) => [line.id, { quantity: line.quantity, resellable: true }]),
+ ),
+ )
+
+ async function handleReceive() {
+ await receive
+ .mutateAsync({
+ returnId: returnRecord.id,
+ items: lines.map((line) => ({
+ return_line_item_id: line.id,
+ quantity: rows[line.id]?.quantity ?? 0,
+ resellable: rows[line.id]?.resellable ?? true,
+ })),
+ })
+ .then(() => onOpenChange(false))
+ .catch(() => undefined)
+ }
+
+ return (
+ <Dialog open={open} onOpenChange={onOpenChange}>
+ <DialogContent>
+ <DialogHeader>
+ <DialogTitle>{t('orders.post_sale.returns.receive_title')}</DialogTitle>
+ </DialogHeader>
+ <DialogBody>
+ <div className="flex flex-col gap-3">
+ {lines.map((line) => (
+ <div key={line.id} className="flex items-center justify-between gap-3">
+ <span className="min-w-0 truncate text-sm">
+ {[line.variant?.sku, line.variant?.options_text].filter(Boolean).join(' · ') ||
+ line.variant_id}
+ </span>
+ <div className="flex shrink-0 items-center gap-3">
+ <label className="flex items-center gap-2 text-xs" htmlFor={`resell-${line.id}`}>
+ {t('orders.post_sale.returns.resellable')}
+ <Switch
+ id={`resell-${line.id}`}
+ checked={rows[line.id]?.resellable ?? true}
+ onCheckedChange={(checked) =>
+ setRows((current) => ({
+ ...current,
+ [line.id]: {
+ quantity: current[line.id]?.quantity ?? 0,
+ resellable: !!checked,
+ },
+ }))
+ }
+ />
+ </label>
+ <Input
+ type="number"
+ min={0}
+ max={line.quantity}
+ className="w-20"
+ aria-label={t('orders.post_sale.returns.received_quantity')}
+ value={rows[line.id]?.quantity ?? 0}
+ onChange={(event) =>
+ setRows((current) => ({
+ ...current,
+ [line.id]: {
+ quantity: Math.max(
+ 0,
+ Math.min(line.quantity, Number(event.target.value)),
+ ),
+ resellable: current[line.id]?.resellable ?? true,
+ },
+ }))
+ }
+ />
+ </div>
+ </div>
+ ))}
+ </div>
+ </DialogBody>
+ <DialogFooter>
+ <Button type="button" variant="outline" onClick={() => onOpenChange(false)}>
+ {t('common.cancel')}
+ </Button>
+ <Button type="button" disabled={receive.isPending} onClick={handleReceive}>
+ {t('orders.post_sale.returns.receive')}
+ </Button>
+ </DialogFooter>
+ </DialogContent>
+ </Dialog>
+ )
+}
+
+/**
+ * Giving the money back.
+ *
+ * Opens on what the return is still owed, which is also the most that can be
+ * given back — the server refuses anything above it, and on a split checkout
+ * bounds it again by this order's share of the payment.
+ */
+function RefundDialog({
+ orderId,
+ returnRecord,
+ open,
+ onOpenChange,
+}: {
+ orderId: string
+ returnRecord: Return
+ open: boolean
+ onOpenChange: (open: boolean) => void
+}) {
+ const { t } = useTranslation()
+ const { refund } = useReturnActions(orderId)
+
+ const [amount, setAmount] = useState(returnRecord.refundable_total ?? '')
+ const [method, setMethod] = useState<'original_payment' | 'store_credit'>('original_payment')
+
+ const methodOptions = [
+ { value: 'original_payment', label: t('orders.post_sale.returns.original_payment') },
+ { value: 'store_credit', label: t('orders.post_sale.returns.store_credit') },
+ ]
+
+ async function handleRefund() {
+ await refund
+ .mutateAsync({ returnId: returnRecord.id, amount, refundMethod: method })
+ .then(() => onOpenChange(false))
+ .catch(() => undefined)
+ }
+
+ return (
+ <Dialog open={open} onOpenChange={onOpenChange}>
+ <DialogContent>
+ <DialogHeader>
+ <DialogTitle>{t('orders.post_sale.returns.refund_title')}</DialogTitle>
+ </DialogHeader>
+ <DialogBody>
+ <div className="flex flex-col gap-4">
+ <Field>
+ <FieldLabel htmlFor="refund-amount">
+ {t('orders.post_sale.returns.amount')}
+ </FieldLabel>
+ <Input
+ id="refund-amount"
+ type="number"
+ step="0.01"
+ min={0}
+ value={amount}
+ onChange={(event) => setAmount(event.target.value)}
+ />
+ </Field>
+
+ <Field>
+ <FieldLabel htmlFor="refund-method">
+ {t('orders.post_sale.returns.refund_method')}
+ </FieldLabel>
+ <Select
+ items={methodOptions}
+ value={method}
+ onValueChange={(value) =>
+ setMethod((value as 'original_payment' | 'store_credit') ?? 'original_payment')
+ }
+ >
+ <SelectTrigger id="refund-method">
+ <SelectValue />
+ </SelectTrigger>
+ <SelectContent>
+ {methodOptions.map((option) => (
+ <SelectItem key={option.value} value={option.value}>
+ {option.label}
+ </SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
+ </Field>
+ </div>
+ </DialogBody>
+ <DialogFooter>
+ <Button type="button" variant="outline" onClick={() => onOpenChange(false)}>
+ {t('common.cancel')}
+ </Button>
+ <Button type="button" disabled={refund.isPending} onClick={handleRefund}>
+ {t('orders.post_sale.returns.refund')}
+ </Button>
+ </DialogFooter>
+ </DialogContent>
+ </Dialog>
+ )
+}
diff --git a/packages/seller-dashboard/src/hooks/use-fulfillments.ts b/packages/seller-dashboard/src/hooks/use-fulfillments.ts
new file mode 100644
index 0000000000..bb415f7c33
--- /dev/null
+++ b/packages/seller-dashboard/src/hooks/use-fulfillments.ts
@@ -0,0 +1,84 @@
+import { useResourceKeyBuilder } from '@spree/dashboard-core'
+import { toastManager } from '@spree/dashboard-ui'
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+import { sellerClient } from '../api-client'
+
+/**
+ * Everything a seller does to a parcel.
+ *
+ * Each verb is its own endpoint because each carries different arguments —
+ * shipping takes a tracking number and which units went, splitting takes a
+ * variant and a quantity.
+ */
+export function useFulfillmentActions(orderId: string) {
+ const queryClient = useQueryClient()
+ const buildKey = useResourceKeyBuilder()
+
+ function useFulfillmentMutation<TParams>(mutationFn: (params: TParams) => Promise<unknown>) {
+ return useMutation({
+ mutationFn,
+ onSuccess: () => {
+ queryClient.invalidateQueries({ queryKey: buildKey('seller-order', orderId) })
+ queryClient.invalidateQueries({ queryKey: buildKey('seller-orders') })
+ },
+ onError: (error) => {
+ // A rejected workflow — a parcel that cannot be resumed, a split that
+ // would empty its source — otherwise looks like a dead button.
+ toastManager.add({
+ type: 'error',
+ title: error instanceof Error ? error.message : String(error),
+ })
+ },
+ })
+ }
+
+ const fulfill = useFulfillmentMutation(
+ ({
+ fulfillmentId,
+ ...params
+ }: {
+ fulfillmentId: string
+ tracking?: string
+ tracking_carrier?: string
+ notify_customer?: boolean
+ items?: Array<{ item_id: string; quantity: number }>
+ }) => sellerClient().orders.fulfillments.fulfill(orderId, fulfillmentId, params),
+ )
+
+ const update = useFulfillmentMutation(
+ ({
+ fulfillmentId,
+ ...params
+ }: {
+ fulfillmentId: string
+ tracking?: string
+ tracking_carrier?: string
+ }) => sellerClient().orders.fulfillments.update(orderId, fulfillmentId, params),
+ )
+
+ const cancel = useFulfillmentMutation((fulfillmentId: string) =>
+ sellerClient().orders.fulfillments.cancel(orderId, fulfillmentId),
+ )
+
+ const resume = useFulfillmentMutation((fulfillmentId: string) =>
+ sellerClient().orders.fulfillments.resume(orderId, fulfillmentId),
+ )
+
+ const markDelivered = useFulfillmentMutation((fulfillmentId: string) =>
+ sellerClient().orders.fulfillments.markDelivered(orderId, fulfillmentId),
+ )
+
+ const split = useFulfillmentMutation(
+ ({
+ fulfillmentId,
+ ...params
+ }: {
+ fulfillmentId: string
+ variant_id: string
+ quantity: number
+ stock_location_id?: string
+ }) => sellerClient().orders.fulfillments.split(orderId, fulfillmentId, params),
+ )
+
+ return { fulfill, update, cancel, resume, markDelivered, split }
+}
diff --git a/packages/seller-dashboard/src/hooks/use-order.ts b/packages/seller-dashboard/src/hooks/use-order.ts
new file mode 100644
index 0000000000..f167fccf81
--- /dev/null
+++ b/packages/seller-dashboard/src/hooks/use-order.ts
@@ -0,0 +1,45 @@
+import { useResourceKey, useResourceKeyBuilder } from '@spree/dashboard-core'
+import { toastManager } from '@spree/dashboard-ui'
+import type { Order } from '@spree/seller-sdk'
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import { sellerClient } from '../api-client'
+
+/** One order, with everything the page renders about it. */
+export function useOrder(orderId: string) {
+ return useQuery({
+ queryKey: useResourceKey('seller-order', orderId),
+ queryFn: () => sellerClient().orders.get(orderId),
+ enabled: !!orderId,
+ })
+}
+
+/** The key a mutation elsewhere invalidates to refresh this order. */
+export function useOrderKeyBuilder() {
+ return useResourceKeyBuilder()
+}
+
+/**
+ * A write against the order itself. Refreshes the order and the list behind
+ * it — a canceled order reads differently in both places.
+ */
+export function useOrderMutation<TParams, TResult = Order>(
+ orderId: string,
+ mutationFn: (params: TParams) => Promise<TResult>,
+) {
+ const queryClient = useQueryClient()
+ const buildKey = useResourceKeyBuilder()
+
+ return useMutation({
+ mutationFn,
+ onSuccess: () => {
+ queryClient.invalidateQueries({ queryKey: buildKey('seller-order', orderId) })
+ queryClient.invalidateQueries({ queryKey: buildKey('seller-orders') })
+ },
+ onError: (error) => {
+ toastManager.add({
+ type: 'error',
+ title: error instanceof Error ? error.message : String(error),
+ })
+ },
+ })
+}
diff --git a/packages/seller-dashboard/src/hooks/use-post-sale.ts b/packages/seller-dashboard/src/hooks/use-post-sale.ts
new file mode 100644
index 0000000000..358728336e
--- /dev/null
+++ b/packages/seller-dashboard/src/hooks/use-post-sale.ts
@@ -0,0 +1,193 @@
+import { useResourceKey, useResourceKeyBuilder } from '@spree/dashboard-core'
+import { toastManager } from '@spree/dashboard-ui'
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import { sellerClient } from '../api-client'
+
+/**
+ * What has come back, or gone wrong, on one order.
+ *
+ * Fetched separately from the order so its payload stays lean — most orders
+ * have none of these.
+ */
+export function useOrderReturns(orderId: string) {
+ return useQuery({
+ queryKey: useResourceKey('seller-order-returns', orderId),
+ queryFn: () => sellerClient().orders.returns.list(orderId),
+ enabled: !!orderId,
+ })
+}
+
+export function useOrderExchanges(orderId: string) {
+ return useQuery({
+ queryKey: useResourceKey('seller-order-exchanges', orderId),
+ queryFn: () => sellerClient().orders.exchanges.list(orderId),
+ enabled: !!orderId,
+ })
+}
+
+export function useOrderClaims(orderId: string) {
+ return useQuery({
+ queryKey: useResourceKey('seller-order-claims', orderId),
+ queryFn: () => sellerClient().orders.claims.list(orderId),
+ enabled: !!orderId,
+ })
+}
+
+/**
+ * Refreshes the list this write belongs to and the order itself — refunding
+ * changes what the order is owed.
+ */
+function usePostSaleMutation<TParams>(
+ orderId: string,
+ resourceKey: string,
+ mutationFn: (params: TParams) => Promise<unknown>,
+) {
+ const queryClient = useQueryClient()
+ const buildKey = useResourceKeyBuilder()
+
+ return useMutation({
+ mutationFn,
+ onSuccess: () => {
+ queryClient.invalidateQueries({ queryKey: buildKey(resourceKey, orderId) })
+ queryClient.invalidateQueries({ queryKey: buildKey('seller-order', orderId) })
+ },
+ onError: (error) => {
+ toastManager.add({
+ type: 'error',
+ title: error instanceof Error ? error.message : String(error),
+ })
+ },
+ })
+}
+
+export function useReturnActions(orderId: string) {
+ const key = 'seller-order-returns'
+ const returns = () => sellerClient().orders.returns
+
+ const create = usePostSaleMutation(
+ orderId,
+ key,
+ (params: {
+ items: Array<{ fulfillment_item_id: string; quantity: number }>
+ memo?: string
+ reason_id?: string
+ }) => returns().create(orderId, params),
+ )
+
+ const approve = usePostSaleMutation(orderId, key, (id: string) => returns().approve(orderId, id))
+
+ const receive = usePostSaleMutation(
+ orderId,
+ key,
+ ({
+ returnId,
+ items,
+ }: {
+ returnId: string
+ items?: Array<{ return_line_item_id: string; quantity: number; resellable?: boolean }>
+ }) => returns().receive(orderId, returnId, items ? { items } : undefined),
+ )
+
+ const refund = usePostSaleMutation(
+ orderId,
+ key,
+ ({
+ returnId,
+ refundMethod,
+ amount,
+ }: {
+ returnId: string
+ refundMethod?: 'original_payment' | 'store_credit'
+ amount?: string
+ }) => returns().refund(orderId, returnId, { refund_method: refundMethod, amount }),
+ )
+
+ const cancel = usePostSaleMutation(orderId, key, (id: string) => returns().cancel(orderId, id))
+
+ return { create, approve, receive, refund, cancel }
+}
+
+export function useExchangeActions(orderId: string) {
+ const key = 'seller-order-exchanges'
+ const exchanges = () => sellerClient().orders.exchanges
+
+ const create = usePostSaleMutation(
+ orderId,
+ key,
+ (params: {
+ items: Array<{ fulfillment_item_id: string; new_variant_id: string; quantity: number }>
+ memo?: string
+ reason_id?: string
+ }) => exchanges().create(orderId, params),
+ )
+
+ const approve = usePostSaleMutation(orderId, key, (id: string) =>
+ exchanges().approve(orderId, id),
+ )
+
+ const receive = usePostSaleMutation(
+ orderId,
+ key,
+ ({
+ exchangeId,
+ items,
+ }: {
+ exchangeId: string
+ items?: Array<{ exchange_line_item_id: string; quantity: number; resellable?: boolean }>
+ }) => exchanges().receive(orderId, exchangeId, items ? { items } : undefined),
+ )
+
+ const fulfill = usePostSaleMutation(
+ orderId,
+ key,
+ ({
+ exchangeId,
+ refundMethod,
+ }: {
+ exchangeId: string
+ refundMethod?: 'original_payment' | 'store_credit'
+ }) => exchanges().fulfill(orderId, exchangeId, { refund_method: refundMethod }),
+ )
+
+ const cancel = usePostSaleMutation(orderId, key, (id: string) => exchanges().cancel(orderId, id))
+
+ return { create, approve, receive, fulfill, cancel }
+}
+
+export function useClaimActions(orderId: string) {
+ const key = 'seller-order-claims'
+ const claims = () => sellerClient().orders.claims
+
+ const create = usePostSaleMutation(
+ orderId,
+ key,
+ (params: {
+ items: Array<{ line_item_id: string; quantity: number; description?: string }>
+ memo?: string
+ reason_id?: string
+ }) => claims().create(orderId, params),
+ )
+
+ const approve = usePostSaleMutation(orderId, key, (id: string) => claims().approve(orderId, id))
+
+ const resolve = usePostSaleMutation(
+ orderId,
+ key,
+ ({
+ claimId,
+ resolution,
+ refundMethod,
+ amount,
+ }: {
+ claimId: string
+ resolution: 'refund' | 'replacement' | 'refund_and_replacement'
+ refundMethod?: 'original_payment' | 'store_credit'
+ amount?: string
+ }) => claims().resolve(orderId, claimId, { resolution, refund_method: refundMethod, amount }),
+ )
+
+ const deny = usePostSaleMutation(orderId, key, (id: string) => claims().deny(orderId, id))
+ const cancel = usePostSaleMutation(orderId, key, (id: string) => claims().cancel(orderId, id))
+
+ return { create, approve, resolve, deny, cancel }
+}
diff --git a/packages/seller-dashboard/src/hooks/use-reasons.ts b/packages/seller-dashboard/src/hooks/use-reasons.ts
new file mode 100644
index 0000000000..0559949371
--- /dev/null
+++ b/packages/seller-dashboard/src/hooks/use-reasons.ts
@@ -0,0 +1,31 @@
+import { useResourceKey } from '@spree/dashboard-core'
+import { useQuery } from '@tanstack/react-query'
+import { sellerClient } from '../api-client'
+
+export type ReasonKind = 'return-reasons' | 'claim-reasons'
+
+/**
+ * The marketplace's vocabulary for why goods came back or what went wrong.
+ * Operator-owned and slow-moving, so one fetch serves every dialog.
+ */
+export function useReasons(kind: ReasonKind, enabled = true) {
+ return useQuery({
+ queryKey: useResourceKey(kind),
+ queryFn: () =>
+ kind === 'return-reasons'
+ ? sellerClient().returnReasons.list()
+ : sellerClient().claimReasons.list(),
+ staleTime: 5 * 60 * 1000,
+ enabled,
+ })
+}
+
+/** Registry data — it only changes on deploy. */
+export function useTrackingCarriers(enabled = true) {
+ return useQuery({
+ queryKey: useResourceKey('seller-tracking-carriers'),
+ queryFn: () => sellerClient().trackingCarriers.list(),
+ staleTime: Number.POSITIVE_INFINITY,
+ enabled,
+ })
+}
diff --git a/packages/seller-dashboard/src/locales/en.json b/packages/seller-dashboard/src/locales/en.json
index c5ac3d0dd6..1d56310fe9 100644
--- a/packages/seller-dashboard/src/locales/en.json
+++ b/packages/seller-dashboard/src/locales/en.json
@@ -98,7 +98,8 @@
"remove": "Remove",
"retry": "Try again",
"save": "Save",
- "saving": "Saving…"
+ "saving": "Saving…",
+ "actions": "Actions"
},
"delivery_methods": {
"add": "Add delivery method",
@@ -279,7 +280,111 @@
"title": "Orders",
"tracking": "Tracking {{number}}",
"tracking_label": "Tracking number",
- "tracking_placeholder": "Optional"
+ "tracking_placeholder": "Optional",
+ "billing_address": "Billing address",
+ "customer_note": "Customer note",
+ "fulfillments": {
+ "title": "Parcels",
+ "empty": "Nothing to send on this order.",
+ "carrier_label": "Carrier",
+ "carrier_auto": "Detect from number",
+ "add_tracking": "Add tracking",
+ "add_tracking_title": "Add tracking",
+ "edit_tracking": "Edit tracking",
+ "edit_tracking_title": "Edit tracking",
+ "tracking_description": "The number the customer follows the parcel with.",
+ "track_parcel": "Track parcel",
+ "notify_customer": "Email the customer",
+ "units_selected": "{{selected}} of {{total}} units selected",
+ "partial_warning": "Sending part of this parcel moves the rest onto a new one.",
+ "quantity_for": "Quantity for {{name}}",
+ "mark_delivered": "Mark as delivered",
+ "resume": "Resume",
+ "cancel": "Cancel parcel",
+ "cancel_title": "Cancel this parcel?",
+ "cancel_message": "The goods go back on the shelf and the carrier is stood down.",
+ "split": "Split",
+ "splitting": "Splitting…",
+ "split_title": "Split this parcel",
+ "split_description": "Move part of what this parcel holds onto one of its own.",
+ "split_item": "Item",
+ "split_quantity": "Quantity to move",
+ "split_would_empty": "Moving everything would leave this parcel empty.",
+ "confirm_split": "This takes effect immediately."
+ },
+ "summary": {
+ "title": "Summary",
+ "item_total": "Items",
+ "tax_total": "Tax",
+ "total": "Total"
+ },
+ "customer": {
+ "title": "Customer"
+ },
+ "post_sale": {
+ "reason": "Reason",
+ "memo": "Note",
+ "approve": "Approve",
+ "cancel": "Cancel",
+ "statuses": {
+ "requested": "Requested",
+ "approved": "Approved",
+ "received": "Received",
+ "refunded": "Refunded",
+ "fulfilled": "Fulfilled",
+ "open": "Open",
+ "resolved": "Resolved",
+ "denied": "Denied",
+ "canceled": "Canceled"
+ },
+ "returns": {
+ "title": "Returns",
+ "empty": "Nothing has come back from this order.",
+ "create": "New return",
+ "create_title": "Take goods back",
+ "receive": "Receive",
+ "receive_title": "What arrived?",
+ "received_quantity": "Quantity received",
+ "resellable": "Resellable",
+ "partially_received": "{{received}} of {{quantity}} received",
+ "not_resellable": "Not resellable",
+ "refund": "Refund",
+ "refund_title": "Give the money back",
+ "refund_method": "Refund to",
+ "refund_total": "Refund total: {{amount}}",
+ "amount": "Amount",
+ "original_payment": "Original payment",
+ "store_credit": "Store credit",
+ "cancel_title": "Cancel this return?",
+ "cancel_message": "The customer is told it will not go ahead."
+ },
+ "exchanges": {
+ "title": "Exchanges",
+ "receive": "Receive",
+ "fulfill": "Send replacement",
+ "price_difference": "Price difference: {{amount}}",
+ "cancel_title": "Cancel this exchange?",
+ "cancel_message": "The customer is told it will not go ahead."
+ },
+ "claims": {
+ "title": "Claims",
+ "empty": "Nothing has been reported on this order.",
+ "create": "New claim",
+ "create_title": "Report a problem",
+ "description": "What went wrong",
+ "resolve": "Resolve",
+ "resolve_title": "Put this right",
+ "resolution": "How to resolve",
+ "resolutions": {
+ "refund": "Refund",
+ "replacement": "Send a replacement",
+ "refund_and_replacement": "Refund and send a replacement"
+ },
+ "deny": "Deny",
+ "deny_title": "Deny this claim?",
+ "deny_message": "The customer is told the claim was not upheld."
+ }
+ }
},
"policies": {
"add": "Add policy",
diff --git a/packages/seller-dashboard/src/pages/order.tsx b/packages/seller-dashboard/src/pages/order.tsx
index a0e9ce6a4e..0319eda0fc 100644
--- a/packages/seller-dashboard/src/pages/order.tsx
+++ b/packages/seller-dashboard/src/pages/order.tsx
@@ -1,60 +1,43 @@
import { PageHeader } from '@spree/dashboard-core'
import {
- AddressBlock,
- Button,
- Card,
- CardAction,
- CardContent,
- CardHeader,
- CardTitle,
DropdownMenuItem,
- Field,
- FieldLabel,
- Input,
+ ResourceLayout,
StatusBadge,
toastManager,
useConfirm,
} from '@spree/dashboard-ui'
-import type { Fulfillment } from '@spree/seller-sdk'
-import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
import { useParams } from '@tanstack/react-router'
-import { useState } from 'react'
import { useTranslation } from 'react-i18next'
import { sellerClient } from '../api-client'
import { CenteredMessage } from '../components/centered-message'
+import { FulfillmentsCard } from '../components/orders/fulfillments-card'
+import {
+ OrderCustomerCard,
+ OrderItemsCard,
+ OrderNoteCard,
+ OrderSummaryCard,
+} from '../components/orders/order-cards'
+import { ClaimsCard, ExchangesCard } from '../components/orders/post-sale-cards'
+import { ReturnsCard } from '../components/orders/returns-card'
import { RetryableError } from '../components/retryable-error'
+import { useOrder, useOrderMutation } from '../hooks/use-order'
-/** One order, as the seller needs it to pack and post the parcel. */
+/**
+ * One order, as the seller needs it to pack, post, and put right.
+ *
+ * Laid out like the operator's order page — parcels and post-sale on the
+ * left, who and what on the right — minus the marketplace's own surfaces:
+ * the payment the customer made, the tax and discount breakdown, and the
+ * operator's bookkeeping all belong to whoever runs the marketplace.
+ */
export function OrderPage() {
const { t } = useTranslation()
- const { sellerId, orderId } = useParams({ from: '/_authenticated/$sellerId/orders/$orderId' })
- const queryClient = useQueryClient()
+ const { orderId } = useParams({ from: '/_authenticated/$sellerId/orders/$orderId' })
const confirm = useConfirm()
- const orderKey = ['seller', sellerId, 'order', orderId]
- const {
- data: order,
- isLoading,
- isError,
- refetch,
- } = useQuery({
- queryKey: orderKey,
- queryFn: () => sellerClient().orders.get(orderId),
- })
+ const { data: order, isLoading, isError, refetch } = useOrder(orderId)
- const cancel = useMutation({
- mutationFn: () => sellerClient().orders.cancel(orderId),
- onSuccess: (updated) => {
- queryClient.setQueryData(orderKey, updated)
- void queryClient.invalidateQueries({ queryKey: ['seller-orders'] })
- toastManager.add({ type: 'success', title: t('orders.canceled') })
- },
- onError: (err) =>
- toastManager.add({
- type: 'error',
- title: err instanceof Error ? err.message : t('common.error'),
- }),
- })
+ const cancel = useOrderMutation(orderId, () => sellerClient().orders.cancel(orderId))
if (isLoading) return <CenteredMessage>{t('common.loading')}</CenteredMessage>
if (isError) return <RetryableError onRetry={() => refetch()} />
@@ -68,165 +51,78 @@ export function OrderPage() {
confirmLabel: t('orders.cancel'),
})
if (!ok) return
- await cancel.mutateAsync().catch(() => undefined)
+
+ await cancel
+ .mutateAsync(undefined)
+ .then(() => toastManager.add({ type: 'success', title: t('orders.canceled') }))
+ .catch(() => undefined)
}
const cancelable = order.status !== 'canceled'
+ // Nothing can come back from an order that never went out, so the post-sale
+ // cards would only render empty with a disabled button.
+ const placed = !!order.completed_at
return (
- <div className="flex flex-col gap-4">
- {/* Cancel goes in the menu's destructive group rather than beside the
- title: a destructive action sitting next to the page's own heading is
- easy to hit by mistake, and this is where the operator dashboard puts
- the same action. */}
- <PageHeader
- title={order.number}
- backTo="orders"
- subtitle={order.completed_at ? new Date(order.completed_at).toLocaleString() : undefined}
- badges={
- order.fulfillment_status && (
- <StatusBadge
- status={order.fulfillment_status}
- label={t(`orders.fulfillment_statuses.${order.fulfillment_status}`)}
- />
- )
- }
- resource={{ id: order.id, number: order.number }}
- destructiveItems={
- cancelable ? (
- <DropdownMenuItem
- variant="destructive"
- disabled={cancel.isPending}
- onClick={handleCancel}
- >
- {t('orders.cancel')}
- </DropdownMenuItem>
- ) : undefined
- }
- />
-
- <Card>
- <CardHeader>
- <CardTitle>{t('orders.items')}</CardTitle>
- </CardHeader>
- <CardContent className="flex flex-col gap-3">
- {order.items.map((item) => (
- <div key={item.id} className="flex items-center justify-between gap-3">
- <div className="min-w-0">
- <div className="truncate text-sm font-medium">{item.name}</div>
- <div className="truncate text-muted-foreground text-xs">
- {[item.sku, item.options_text].filter(Boolean).join(' · ')}
- </div>
- </div>
- <div className="flex shrink-0 items-center gap-4 text-sm">
- <span className="text-muted-foreground">× {item.quantity}</span>
- <span>{item.display_total as string}</span>
- </div>
- </div>
- ))}
- </CardContent>
- </Card>
-
- {order.fulfillments.map((fulfillment) => (
- <FulfillmentCard key={fulfillment.id} orderId={orderId} fulfillment={fulfillment} />
- ))}
-
- {order.shipping_address && (
- <Card>
- <CardHeader>
- <CardTitle>{t('orders.shipping_address')}</CardTitle>
- </CardHeader>
- <CardContent>
- <AddressBlock address={order.shipping_address} />
- </CardContent>
- </Card>
- )}
- </div>
- )
-}
-
-/**
- * One parcel. Shipping it is the seller's own action, so the tracking number
- * is entered here rather than on a separate screen — it is the thing they
- * have in hand when they come to mark it sent.
- */
-function FulfillmentCard({ orderId, fulfillment }: { orderId: string; fulfillment: Fulfillment }) {
- const { t } = useTranslation()
- const { sellerId } = useParams({ from: '/_authenticated/$sellerId' })
- const queryClient = useQueryClient()
- const [tracking, setTracking] = useState('')
-
- const fulfill = useMutation({
- mutationFn: () =>
- sellerClient().orders.fulfillments.fulfill(orderId, fulfillment.id, {
- tracking: tracking.trim() || undefined,
- }),
- onSuccess: () => {
- void queryClient.invalidateQueries({ queryKey: ['seller', sellerId, 'order', orderId] })
- void queryClient.invalidateQueries({ queryKey: ['seller-orders'] })
- toastManager.add({ type: 'success', title: t('orders.fulfilled') })
- },
- onError: (err) =>
- toastManager.add({
- type: 'error',
- title: err instanceof Error ? err.message : t('common.error'),
- }),
- })
-
- // A canceled parcel never went out and never will, so it is neither
- // shipped nor still fulfillable. Reading that off "not unfulfilled"
- // badged it as a success and offered a tracking number for a parcel
- // nobody is going to send.
- const fulfillable = fulfillment.status === 'unfulfilled'
-
- return (
- <Card>
- <CardHeader>
- <CardTitle>{fulfillment.number}</CardTitle>
- <CardAction>
- <StatusBadge
- status={fulfillment.status}
- label={t(`orders.fulfillment_statuses.${fulfillment.status}`)}
- />
- </CardAction>
- </CardHeader>
- <CardContent className="flex flex-col gap-3">
- {fulfillment.stock_location_name && (
- <p className="text-muted-foreground text-sm">
- {t('orders.ships_from', { name: fulfillment.stock_location_name })}
- </p>
- )}
-
- {fulfillment.fulfillment_items?.map((item) => (
- <div key={item.id} className="flex items-center justify-between gap-3 text-sm">
- <span className="truncate">{item.name}</span>
- <span className="text-muted-foreground">× {item.quantity}</span>
- </div>
- ))}
-
- {!fulfillable ? (
- fulfillment.tracking && (
- <p className="text-sm">{t('orders.tracking', { number: fulfillment.tracking })}</p>
- )
- ) : (
- <div className="flex items-end gap-2">
- <Field className="flex-1">
- <FieldLabel htmlFor={`tracking-${fulfillment.id}`}>
- {t('orders.tracking_label')}
- </FieldLabel>
- <Input
- id={`tracking-${fulfillment.id}`}
- value={tracking}
- placeholder={t('orders.tracking_placeholder')}
- onChange={(event) => setTracking(event.target.value)}
- />
- </Field>
- <Button disabled={fulfill.isPending} onClick={() => fulfill.mutate()}>
- {fulfill.isPending ? t('orders.fulfilling') : t('orders.fulfill')}
- </Button>
- </div>
- )}
- </CardContent>
- </Card>
+ <ResourceLayout
+ header={
+ // Cancel sits in the menu's destructive group rather than beside the
+ // title: it is easy to hit by mistake there, and this is where the
+ // operator dashboard puts the same action.
+ <PageHeader
+ title={order.number}
+ backTo="orders"
+ subtitle={order.completed_at ? new Date(order.completed_at).toLocaleString() : undefined}
+ badges={
+ <>
+ {order.fulfillment_status && (
+ <StatusBadge
+ status={order.fulfillment_status}
+ label={t(`orders.fulfillment_statuses.${order.fulfillment_status}`)}
+ />
+ )}
+ {order.payment_status && (
+ <StatusBadge
+ status={order.payment_status}
+ label={t(`orders.payment_statuses.${order.payment_status}`)}
+ />
+ )}
+ </>
+ }
+ resource={{ id: order.id, number: order.number }}
+ destructiveItems={
+ cancelable ? (
+ <DropdownMenuItem
+ variant="destructive"
+ disabled={cancel.isPending}
+ onClick={handleCancel}
+ >
+ {t('orders.cancel')}
+ </DropdownMenuItem>
+ ) : undefined
+ }
+ />
+ }
+ main={
+ <>
+ <FulfillmentsCard order={order} />
+ {placed && (
+ <>
+ <ReturnsCard order={order} />
+ <ExchangesCard order={order} />
+ <ClaimsCard order={order} />
+ </>
+ )}
+ <OrderItemsCard order={order} />
+ <OrderSummaryCard order={order} />
+ </>
+ }
+ sidebar={
+ <>
+ <OrderCustomerCard order={order} />
+ <OrderNoteCard order={order} />
+ </>
+ }
+ />
)
}
diff --git a/packages/seller-sdk/src/types/generated/FulfillmentItem.ts b/packages/seller-sdk/src/types/generated/FulfillmentItem.ts
index a0894b80c6..eba79acead 100644
--- a/packages/seller-sdk/src/types/generated/FulfillmentItem.ts
+++ b/packages/seller-sdk/src/types/generated/FulfillmentItem.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 7988b9d8c443cf4ffa7d4451678da5d4
+// Typelizer digest faf9606458548f5a0af0c089fd7ff5f6
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
@@ -6,6 +6,7 @@ type FulfillmentItem = {
id: string;
quantity: number;
line_item_id: string | null;
+ variant_id: string | null;
name: string | null;
sku: string | null;
options_text: string | null;
diff --git a/spree/api/app/serializers/spree/api/v3/seller/fulfillment_item_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/fulfillment_item_serializer.rb
index 3100779aec..8e6c992f6e 100644
--- a/spree/api/app/serializers/spree/api/v3/seller/fulfillment_item_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/seller/fulfillment_item_serializer.rb
@@ -4,11 +4,13 @@ module Spree
module Seller
# One line inside a parcel: what to pick and how many.
#
- # `line_item_id` is what a partial dispatch names — the fulfill
- # endpoint takes line items, so this is the id a panel sends back.
+ # Two ids, because the two things a seller does with a parcel address
+ # its contents differently: a partial dispatch names line items, and
+ # splitting names the variant being moved.
class FulfillmentItemSerializer < V3::BaseSerializer
typelize quantity: :number,
line_item_id: [:string, nullable: true],
+ variant_id: [:string, nullable: true],
name: [:string, nullable: true],
sku: [:string, nullable: true],
options_text: [:string, nullable: true]
@@ -19,6 +21,10 @@ module Spree
item.line_item&.prefixed_id
end
+ attribute :variant_id do |item|
+ item.variant&.prefixed_id
+ end
+
attribute :name do |item|
item.line_item&.name
end