@porulle/plugin-channel-connector 0.76.0 → 0.77.1

package/dist/index.d.ts

@@ -27,5 +27,5 @@ export declare const CHANNEL_MAX_BATCHES_PER_SWEEP = 5000;
 export { signState, verifyState } from "./oauth-state.js";
 export type { BackfillCatalogOptions, BackfillCatalogReport, BuildCatalogPushItemsOptions, BuildCatalogPushItemsResult, CatalogPushAssemblyField, CatalogPushAssemblyImage, CatalogPushAssemblyItem, CatalogPushPreviewBefore, CatalogPushPreviewBeforeStatus, CatalogPushPreviewDiff, CatalogPushPreviewItem, CatalogPushPreviewResult, CatalogPushPreviewUnavailable, PushCatalogToStoreResult, CatalogPushJobResult, CatalogConvergenceFailure, CatalogFieldConflict, CatalogFieldSkip, CatalogPushFieldSkip, CatalogPushSkipReason, CatalogConflictState, CatalogWriteSettings, AfterStoreConnected, BindConnectedStore, ChannelComplianceData, ChannelConnectorPluginOptions, ConfineStores, ConnectClaims, OnStoreCatalogChanged, StoreConnectActor, StoreReadContext, ChannelStockLine, ExportState, PublicConnectedStore, ReconcileReport, } from "./service.js";
 export type { OAuthStatePayload, OAuthStateResult } from "./oauth-state.js";
-export type { ChannelCatalogPush, ChannelCatalogPushEvent, ChannelCatalogConflict, ChannelCatalogConflictEvent, ChannelEntityMapEntry, ChannelExportEvent, ChannelOrderExport, ChannelRefundEvent, ChannelRefundRequest, ChannelReturn, ConnectedStore, StoreHealth, } from "./schema.js";
+export type { ChannelCatalogPush, ChannelCatalogPushEvent, ChannelCatalogConflict, ChannelCatalogConflictEvent, ChannelEntityMapEntry, ChannelExportEvent, ChannelOrderExport, ChannelRefundEvent, ChannelRefundRequest, ChannelReturn, ChannelReturnView, ConnectedStore, StoreHealth, } from "./schema.js";
 export declare function channelConnectorPlugin(options?: ChannelConnectorPluginOptions): import("@porulle/core").CommercePlugin;

package/dist/index.js

@@ -739,7 +739,11 @@ export function channelConnectorPlugin(options = {}) {
             channels.post("/returns/{id}/approve")
                 .summary("Approve a held return: pay the shopper back and book the refund at the store")
                 .permission("channels:connect")
-                .handler(async ({ params, orgId, actor, raw }) => unwrap(await service.approveReturn(orgId, params.id, { orgId, actor, raw })));
+                .input(z.object({ refundShipping: z.boolean().optional() }))
+                .handler(async ({ params, orgId, actor, raw, input }) => {
+                const options = z.object({ refundShipping: z.boolean().optional() }).catch({}).parse(input ?? {});
+                return unwrap(await service.approveReturn(orgId, params.id, { orgId, actor, raw }, options.refundShipping === undefined ? {} : { refundShipping: options.refundShipping }));
+            });
             channels.post("/returns/{id}/decline")
                 .summary("Decline a held return")
                 .permission("channels:connect")

package/dist/mock-connector.d.ts

@@ -74,6 +74,7 @@ export declare function mockChannelConnector(options?: MockChannelConnectorOptio
                 quantity: number;
             }[];
             amount?: number;
+            shippingAmount?: number;
         } | {
             kind: "return.updated";
             remoteReturnId: string;

package/dist/mock-connector.js

@@ -65,7 +65,7 @@ const channelEventSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("inventory.changed"), levels: z.array(level) }),
     z.object({ kind: z.literal("order.cancelled"), remoteOrderId: z.string() }),
     z.object({ kind: z.literal("order.fulfilled"), remoteOrderId: z.string(), partial: z.boolean(), shipments: z.array(shipment) }),
-    z.object({ kind: z.literal("refund.created"), remoteOrderId: z.string(), remoteRefundId: z.string(), lines: z.array(z.object({ externalVariantId: z.string(), quantity: z.number().int() })), amount: z.number().int().exactOptional() }),
+    z.object({ kind: z.literal("refund.created"), remoteOrderId: z.string(), remoteRefundId: z.string(), lines: z.array(z.object({ externalVariantId: z.string(), quantity: z.number().int() })), amount: z.number().int().exactOptional(), shippingAmount: z.number().int().exactOptional() }),
     z.object({ kind: z.literal("return.updated"), remoteReturnId: z.string(), status: z.enum(["approved", "declined", "closed", "cancelled"]) }),
     z.object({ kind: z.literal("connection.revoked") }),
     z.object({ kind: z.literal("compliance.request"), request: z.enum(["customer_data", "customer_redact", "shop_redact"]), data: z.record(z.string(), z.unknown()) }),

package/dist/schema.d.ts

@@ -1929,6 +1929,23 @@ export declare const channelReturns: import("drizzle-orm/pg-core/table").PgTable
                 quantity: number;
             }[];
         }>;
+        shippingAmount: import("@porulle/core/drizzle").PgColumn<{
+            name: "shipping_amount";
+            tableName: "channel_returns";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         reason: import("@porulle/core/drizzle").PgColumn<{
             name: "reason";
             tableName: "channel_returns";
@@ -2106,6 +2123,40 @@ export declare const channelRefundRequests: import("drizzle-orm/pg-core/table").
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        shippingAmount: import("@porulle/core/drizzle").PgColumn<{
+            name: "shipping_amount";
+            tableName: "channel_refund_requests";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        adjustmentAmount: import("@porulle/core/drizzle").PgColumn<{
+            name: "adjustment_amount";
+            tableName: "channel_refund_requests";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         lines: import("@porulle/core/drizzle").PgColumn<{
             name: "lines";
             tableName: "channel_refund_requests";
@@ -2355,4 +2406,15 @@ export type ChannelOrderExport = typeof channelOrderExports.$inferSelect;
 export type ChannelExportEvent = typeof channelExportEvents.$inferSelect;
 export type ChannelRefundRequest = typeof channelRefundRequests.$inferSelect;
 export type ChannelReturn = typeof channelReturns.$inferSelect;
+/** A held return as its merchant decides it: which order, which items, and how much delivery is refundable. */
+export type ChannelReturnView = ChannelReturn & {
+    orderNumber: string | null;
+    items: Array<{
+        orderLineItemId: string;
+        title: string;
+        quantity: number;
+    }>;
+    /** Delivery not yet refunded on the order: what approving with delivery would pay back. */
+    shippingRefundable: number;
+};
 export type ChannelRefundEvent = typeof channelRefundEvents.$inferSelect;

package/dist/schema.js

@@ -184,6 +184,8 @@ export const channelReturns = pgTable("channel_returns", {
     remoteReturnId: text("remote_return_id").notNull(),
     status: text("status", { enum: ["requested", "approved", "declined", "closed", "cancelled"] }).notNull().default("requested"),
     lines: jsonb("lines").$type().notNull(),
+    /** Delivery the merchant refunded when approving a return held on the platform. */
+    shippingAmount: integer("shipping_amount").notNull().default(0),
     reason: text("reason").notNull(),
     note: text("note"),
     createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
@@ -198,7 +200,12 @@ export const channelRefundRequests = pgTable("channel_refund_requests", {
     storeId: uuid("store_id").references(() => connectedStores.id, { onDelete: "cascade" }).notNull(),
     orderId: uuid("order_id").notNull(),
     remoteRefundId: text("remote_refund_id").notNull(),
+    /** Everything the request pays back: its lines, `shippingAmount` and `adjustmentAmount`. */
     amount: integer("amount").notNull(),
+    /** Of `amount`, delivery the store refunded. */
+    shippingAmount: integer("shipping_amount").notNull().default(0),
+    /** Of `amount`, money the store refunded with no line behind it (goodwill). */
+    adjustmentAmount: integer("adjustment_amount").notNull().default(0),
     /** The order lines the store refunded. Null on requests made before it was kept. */
     lines: jsonb("lines").$type(),
     state: text("state", { enum: ["requested", "approved", "rejected", "executed"] }).notNull().default("requested"),

package/dist/service.d.ts

@@ -3,7 +3,7 @@ import type { Actor, ChannelCancelOrderInput, ChannelCatalogItem, ChannelConnect
 import type { ChannelCatalogImage } from "@porulle/core";
 import type { FieldOwner, FieldPath } from "@porulle/core";
 import type { JobsAdapter } from "@porulle/core";
-import { type ChannelCatalogPush, type ChannelCatalogConflict, type ChannelOrderExport, type ChannelRefundRequest, type ChannelReturn, type ConnectedStore } from "./schema.js";
+import { type ChannelCatalogPush, type ChannelCatalogConflict, type ChannelOrderExport, type ChannelRefundRequest, type ChannelReturn, type ChannelReturnView, type ConnectedStore } from "./schema.js";
 import type { StoreHealth } from "./schema.js";
 import { type CatalogFieldMapping, type CatalogFieldTarget } from "./catalog-field-mapping.js";
 export type ExportState = ChannelOrderExport["state"];
@@ -712,7 +712,10 @@ export declare class ChannelConnectorService {
     private setInventoryLevel;
     private createRefundRequest;
     private executeRefund;
-    listRefundRequests(orgId: string): Promise<PluginResult<ChannelRefundRequest[]>>;
+    /** Held refunds, each with the order number an approver knows the order by. */
+    listRefundRequests(orgId: string): Promise<PluginResult<Array<ChannelRefundRequest & {
+        orderNumber: string | null;
+    }>>>;
     approveRefund(orgId: string, id: string, actor: {
         userId: string;
     }): Promise<PluginResult<ChannelRefundRequest>>;
@@ -755,14 +758,17 @@ export declare class ChannelConnectorService {
         status: string;
     }>>;
     /** Returns held on the platform (stores with none of their own) that wait for their merchant. */
-    listReturns(orgId: string, context?: StoreReadContext): Promise<PluginResult<ChannelReturn[]>>;
+    listReturns(orgId: string, context?: StoreReadContext): Promise<PluginResult<ChannelReturnView[]>>;
     /**
-     * The merchant takes a held return back: the shopper is paid back those lines, then the refund is
-     * booked at the store with the stock put back, and kept as an executed refund request under the
-     * store's own refund id so the store's webhook for it pays nobody twice. If the store will not book
-     * it, the shopper has still been paid and the return stays `approved`; approving again only books it.
+     * The merchant takes a held return back: the shopper is paid back those lines (and the delivery, when
+     * the merchant refunds it), then the refund is booked at the store with the stock put back, and kept
+     * as an executed refund request under the store's own refund id so the store's webhook for it pays
+     * nobody twice. If the store will not book it, the shopper has still been paid and the return stays
+     * `approved`; approving again only books it, with the delivery decided the first time.
      */
-    approveReturn(orgId: string, id: string, context?: StoreReadContext): Promise<PluginResult<ChannelReturn>>;
+    approveReturn(orgId: string, id: string, context?: StoreReadContext, options?: {
+        refundShipping?: boolean;
+    }): Promise<PluginResult<ChannelReturn>>;
     /** The merchant refuses a held return. Nothing moves. */
     declineReturn(orgId: string, id: string, context?: StoreReadContext): Promise<PluginResult<ChannelReturn>>;
     /** A cancelled or refunded order: nothing to push to a store, ever again. */

package/dist/service.js

@@ -5,7 +5,7 @@ import { isValidFieldPath, requireUserId } from "@porulle/core";
 import { CHANNEL_CONVERGENCE_CTX } from "./catalog-push-trigger.js";
 import { resolveLiveCredentials, withLiveCredentials } from "./live-credentials.js";
 import { and, desc, eq, inArray, isNull, lte, or, sql } from "@porulle/core/drizzle";
-import { brands, categories, customerAddresses, customers, entityBrands, entityCategories, entityMedia, entityTags, inventoryLevels, mediaAssets, optionTypes, optionValues, fulfillmentLineItems, fulfillmentRecords, orderLineItems, orders, prices, sellableAttributes, sellableCustomFields, sellableEntities, sellableEntityRevisions, entityFieldDefinitions, tags, variants, variantOptionValues, } from "@porulle/core/schema";
+import { brands, categories, customerAddresses, customers, entityBrands, entityCategories, entityMedia, entityTags, inventoryLevels, mediaAssets, optionTypes, optionValues, fulfillmentLineItems, fulfillmentRecords, orderLineItems, orderRefunds, orders, prices, sellableAttributes, sellableCustomFields, sellableEntities, sellableEntityRevisions, entityFieldDefinitions, tags, variants, variantOptionValues, } from "@porulle/core/schema";
 import { planAbsentArchives } from "./deletion-policy.js";
 import { channelCatalogPushEvents, channelCatalogPushes, channelCatalogConflicts, channelCatalogConflictEvents, channelEntityLinks, channelEntityMap, channelExportEvents, channelOrderExports, connectedStores, channelRefundEvents, channelRefundRequests, channelReturns, } from "./schema.js";
 import { mergeCatalogFieldMapping, normalizeCatalogFieldMapping, selectCatalogFieldMapping, } from "./catalog-field-mapping.js";
@@ -4176,14 +4176,15 @@ export class ChannelConnectorService {
         const orderLines = await this.db.select().from(orderLineItems).where(eq(orderLineItems.orderId, orderId));
         const mappings = await this.db.select().from(channelEntityMap).where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, store.id)));
         const refundLines = [];
-        let clean = event.lines.length > 0;
+        // Every line the store named is one of ours, with that much still refundable.
+        let mapped = true;
         for (const line of event.lines) {
             const externalId = line.externalVariantId;
             const quantity = line.quantity;
             const mapping = mappings.find((item) => item.externalId === externalId);
             const orderLine = mapping ? orderLines.find((item) => item.variantId === mapping.variantId || item.entityId === mapping.entityId) : undefined;
             if (!orderLine || !Number.isInteger(quantity) || quantity < 1 || quantity > orderLine.quantity - orderLine.refundedQuantity)
-                clean = false;
+                mapped = false;
             else
                 refundLines.push({ lineItemId: orderLine.id, quantity });
         }
@@ -4191,17 +4192,33 @@ export class ChannelConnectorService {
             const item = orderLines.find((candidate) => candidate.id === line.lineItemId);
             return sum + Math.round((item.totalPrice + item.taxAmount - item.discountAmount) * line.quantity / item.quantity);
         }, 0);
-        // What the store refunded, when it says, and never more than the platform's own price for the lines:
-        // a store can refund part of a line, or a line it discounted, but cannot claim more than it sold.
-        const amount = event.amount === undefined ? priced : Math.min(Math.max(0, event.amount), priced);
         const [order] = await this.db.select().from(orders).where(and(eq(orders.organizationId, orgId), eq(orders.id, orderId)));
         if (!order)
             return PluginErr("Order not found.", "NOT_FOUND");
+        const completed = (await this.db.select({ amount: orderRefunds.amount, shippingAmount: orderRefunds.shippingAmount }).from(orderRefunds)
+            .where(and(eq(orderRefunds.orderId, orderId), eq(orderRefunds.status, "completed"))));
+        const shippingLeft = Math.max(0, order.shippingTotal - completed.reduce((sum, refund) => sum + refund.shippingAmount, 0));
+        const orderLeft = Math.max(0, order.grandTotal - completed.reduce((sum, refund) => sum + refund.amount, 0));
+        // What the store refunded, and never more than the shopper paid for what it names: the lines at most
+        // at the platform's own price (part of a line, or a line the store discounted, is less), the delivery
+        // at most what of it is not refunded yet, money with no line behind it (goodwill) only when the refund
+        // names no line, and the whole at most what the order has left.
+        const storeShipping = Math.max(0, event.shippingAmount ?? 0);
+        const shippingAmount = Math.min(storeShipping, shippingLeft);
+        const rest = event.amount === undefined ? priced : Math.max(0, event.amount - storeShipping);
+        const linesAmount = Math.min(rest, priced);
+        const goodwill = event.lines.length === 0 ? rest : 0;
+        const adjustmentAmount = Math.max(0, Math.min(goodwill, orderLeft - linesAmount - shippingAmount));
+        const amount = Math.min(linesAmount + shippingAmount + adjustmentAmount, orderLeft);
+        // A refund that pays nothing (a restock, or nothing left to pay) asks nobody for money.
+        if (amount === 0)
+            return Ok(null);
         const max = this.options.refundAutoMax ?? order.amountCaptured ?? order.grandTotal;
         const ageOk = Date.now() - store.createdAt.getTime() >= (this.options.newStoreDays ?? 7) * 86_400_000;
-        // Only a whole-line refund is automatic; any other amount is a person's call.
-        const auto = clean && amount > 0 && amount === priced && ageOk && amount <= max;
-        const rows = await this.db.insert(channelRefundRequests).values({ organizationId: orgId, storeId: store.id, orderId, remoteRefundId, amount, lines: clean ? refundLines : null, state: auto ? "approved" : "requested", approvedBy: auto ? requireUserId(actor) : null }).returning();
+        // Only whole lines, at exactly the platform's price with exactly their delivery, are automatic; any
+        // other amount is a person's call.
+        const auto = mapped && refundLines.length > 0 && adjustmentAmount === 0 && linesAmount === priced && shippingAmount === storeShipping && ageOk && amount <= max;
+        const rows = await this.db.insert(channelRefundRequests).values({ organizationId: orgId, storeId: store.id, orderId, remoteRefundId, amount, shippingAmount, adjustmentAmount, lines: mapped ? refundLines : null, state: auto ? "approved" : "requested", approvedBy: auto ? requireUserId(actor) : null }).returning();
         const request = rows[0];
         await this.db.insert(channelRefundEvents).values({ organizationId: orgId, requestId: request.id, fromState: null, toState: request.state, reason: auto ? "Automatic guarded refund" : "Operator approval required", changedBy: requireUserId(actor) });
         if (auto) {
@@ -4217,16 +4234,28 @@ export class ChannelConnectorService {
     }
     async executeRefund(request, lines, actor) {
         const ordersService = this.services.orders;
-        // A request that kept its lines pays back its own amount; an older one is priced from the lines rebuilt for it.
-        const result = await ordersService.refundLines(request.orderId, { lines, reason: `Channel refund ${request.remoteRefundId}`, ...(request.lines ? { amount: request.amount } : {}) }, actor);
+        // A request that kept its lines pays back its own amount for them; an older one is priced from the
+        // lines rebuilt for it. Delivery and goodwill ride beside the lines.
+        const linesAmount = request.amount - request.shippingAmount - request.adjustmentAmount;
+        const result = await ordersService.refundLines(request.orderId, {
+            lines,
+            reason: `Channel refund ${request.remoteRefundId}`,
+            ...(request.lines && lines.length > 0 ? { amount: linesAmount } : {}),
+            ...(request.shippingAmount > 0 ? { shippingAmount: request.shippingAmount } : {}),
+            ...(request.adjustmentAmount > 0 ? { adjustmentAmount: request.adjustmentAmount } : {}),
+        }, actor);
         if (!result.ok)
             return PluginErr(result.error?.message ?? "Refund execution failed.");
         const [updated] = await this.db.update(channelRefundRequests).set({ state: "executed", updatedAt: new Date() }).where(and(eq(channelRefundRequests.organizationId, request.organizationId), eq(channelRefundRequests.id, request.id), eq(channelRefundRequests.state, "approved"))).returning();
         await this.db.insert(channelRefundEvents).values({ organizationId: request.organizationId, requestId: request.id, fromState: "approved", toState: "executed", reason: "Platform refund executed", changedBy: requireUserId(actor) });
         return Ok(updated);
     }
+    /** Held refunds, each with the order number an approver knows the order by. */
     async listRefundRequests(orgId) {
-        return Ok(await this.db.select().from(channelRefundRequests).where(and(eq(channelRefundRequests.organizationId, orgId), eq(channelRefundRequests.state, "requested"))));
+        const rows = await this.db.select({ request: channelRefundRequests, orderNumber: orders.orderNumber }).from(channelRefundRequests)
+            .leftJoin(orders, eq(orders.id, channelRefundRequests.orderId))
+            .where(and(eq(channelRefundRequests.organizationId, orgId), eq(channelRefundRequests.state, "requested")));
+        return Ok(rows.map((row) => ({ ...row.request, orderNumber: row.orderNumber })));
     }
     async approveRefund(orgId, id, actor) {
         const [request] = await this.db.update(channelRefundRequests).set({ state: "approved", approvedBy: actor.userId, updatedAt: new Date() }).where(and(eq(channelRefundRequests.organizationId, orgId), eq(channelRefundRequests.id, id), eq(channelRefundRequests.state, "requested"))).returning();
@@ -4467,15 +4496,33 @@ export class ChannelConnectorService {
         if (allowed !== null && allowed.length === 0)
             return Ok([]);
         const rows = await this.db.select().from(channelReturns).where(and(eq(channelReturns.organizationId, orgId), eq(channelReturns.status, "requested"), sql `${channelReturns.remoteReturnId} like ${`${PLATFORM_RETURN_PREFIX}%`}`, ...(allowed === null ? [] : [inArray(channelReturns.storeId, [...allowed])]))).orderBy(desc(channelReturns.createdAt));
-        return Ok(rows);
+        if (rows.length === 0)
+            return Ok([]);
+        const orderIds = [...new Set(rows.map((row) => row.orderId))];
+        const orderRows = await this.db.select({ id: orders.id, orderNumber: orders.orderNumber, shippingTotal: orders.shippingTotal }).from(orders)
+            .where(and(eq(orders.organizationId, orgId), inArray(orders.id, orderIds)));
+        const lineRows = await this.db.select({ id: orderLineItems.id, title: orderLineItems.title }).from(orderLineItems).where(inArray(orderLineItems.orderId, orderIds));
+        const refunded = await this.db.select({ orderId: orderRefunds.orderId, shippingAmount: orderRefunds.shippingAmount }).from(orderRefunds)
+            .where(and(inArray(orderRefunds.orderId, orderIds), eq(orderRefunds.status, "completed")));
+        return Ok(rows.map((row) => {
+            const order = orderRows.find((candidate) => candidate.id === row.orderId);
+            const shippingRefunded = refunded.filter((refund) => refund.orderId === row.orderId).reduce((sum, refund) => sum + refund.shippingAmount, 0);
+            return {
+                ...row,
+                orderNumber: order?.orderNumber ?? null,
+                items: row.lines.map((line) => ({ orderLineItemId: line.orderLineItemId, title: lineRows.find((candidate) => candidate.id === line.orderLineItemId)?.title ?? "Item", quantity: line.quantity })),
+                shippingRefundable: Math.max(0, (order?.shippingTotal ?? 0) - shippingRefunded),
+            };
+        }));
     }
     /**
-     * The merchant takes a held return back: the shopper is paid back those lines, then the refund is
-     * booked at the store with the stock put back, and kept as an executed refund request under the
-     * store's own refund id so the store's webhook for it pays nobody twice. If the store will not book
-     * it, the shopper has still been paid and the return stays `approved`; approving again only books it.
+     * The merchant takes a held return back: the shopper is paid back those lines (and the delivery, when
+     * the merchant refunds it), then the refund is booked at the store with the stock put back, and kept
+     * as an executed refund request under the store's own refund id so the store's webhook for it pays
+     * nobody twice. If the store will not book it, the shopper has still been paid and the return stays
+     * `approved`; approving again only books it, with the delivery decided the first time.
      */
-    async approveReturn(orgId, id, context) {
+    async approveReturn(orgId, id, context, options = {}) {
         const [held] = await this.db.select().from(channelReturns).where(and(eq(channelReturns.organizationId, orgId), eq(channelReturns.id, id)));
         if (!held || !held.remoteReturnId.startsWith(PLATFORM_RETURN_PREFIX))
             return PluginErr("Return not found.", "NOT_FOUND");
@@ -4501,12 +4548,19 @@ export class ChannelConnectorService {
             priced.push({ lineItemId: item.id, quantity: line.quantity, variantId: item.variantId, amount: Math.round((item.totalPrice + item.taxAmount - item.discountAmount) * line.quantity / item.quantity) });
         }
         const actor = createSystemActor(orgId);
+        let shippingAmount = held.shippingAmount;
         if (held.status === "requested") {
+            if (options.refundShipping === true) {
+                const [order] = await this.db.select({ shippingTotal: orders.shippingTotal }).from(orders).where(and(eq(orders.organizationId, orgId), eq(orders.id, held.orderId)));
+                const refunded = await this.db.select({ shippingAmount: orderRefunds.shippingAmount }).from(orderRefunds)
+                    .where(and(eq(orderRefunds.orderId, held.orderId), eq(orderRefunds.status, "completed")));
+                shippingAmount = Math.max(0, (order?.shippingTotal ?? 0) - refunded.reduce((sum, refund) => sum + refund.shippingAmount, 0));
+            }
             const ordersService = this.services.orders;
-            const refunded = await ordersService.refundLines(held.orderId, { lines: priced.map(({ lineItemId, quantity }) => ({ lineItemId, quantity })), reason: `Return ${held.id}` }, actor);
+            const refunded = await ordersService.refundLines(held.orderId, { lines: priced.map(({ lineItemId, quantity }) => ({ lineItemId, quantity })), reason: `Return ${held.id}`, ...(shippingAmount > 0 ? { shippingAmount } : {}) }, actor);
             if (!refunded.ok)
                 return PluginErr(refunded.error?.message ?? "The shopper could not be paid back.", "REFUND_FAILED");
-            await this.db.update(channelReturns).set({ status: "approved", updatedAt: new Date() }).where(and(eq(channelReturns.organizationId, orgId), eq(channelReturns.id, held.id)));
+            await this.db.update(channelReturns).set({ status: "approved", shippingAmount, updatedAt: new Date() }).where(and(eq(channelReturns.organizationId, orgId), eq(channelReturns.id, held.id)));
         }
         const variantIds = priced.flatMap((line) => (line.variantId === null ? [] : [line.variantId]));
         const mapped = variantIds.length === 0 ? [] : await this.db.select({ variantId: channelEntityMap.variantId, externalId: channelEntityMap.externalId }).from(channelEntityMap)
@@ -4518,14 +4572,14 @@ export class ChannelConnectorService {
                 return PluginErr("The shopper was paid back, but the store has no record of a returned line, so it was not booked there.", "CHANNEL_MAPPING_MISSING");
             storeLines.push({ externalVariantId: externalId, quantity: line.quantity, amount: line.amount });
         }
-        const amount = storeLines.reduce((sum, line) => sum + line.amount, 0);
-        const booked = await connector.recordRefund(store, exported.remoteOrderId, { lines: storeLines, amount, reason: `Return: ${held.reason}`, restock: true });
+        const amount = storeLines.reduce((sum, line) => sum + line.amount, 0) + shippingAmount;
+        const booked = await connector.recordRefund(store, exported.remoteOrderId, { lines: storeLines, amount, ...(shippingAmount > 0 ? { shippingAmount } : {}), reason: `Return: ${held.reason}`, restock: true });
         if (!booked.ok)
             return PluginErr(`The shopper was paid back, but the store did not record the refund (${booked.error.message}). Approve again to retry.`, "CHANNEL_REFUND_NOT_RECORDED");
         const lines = priced.map(({ lineItemId, quantity }) => ({ lineItemId, quantity }));
         await this.db.insert(channelRefundRequests)
-            .values({ organizationId: orgId, storeId: store.id, orderId: held.orderId, remoteRefundId: booked.value.remoteRefundId, amount, lines, state: "executed", approvedBy: requireUserId(actor) })
-            .onConflictDoUpdate({ target: [channelRefundRequests.storeId, channelRefundRequests.remoteRefundId], set: { amount, lines, state: "executed", updatedAt: new Date() } });
+            .values({ organizationId: orgId, storeId: store.id, orderId: held.orderId, remoteRefundId: booked.value.remoteRefundId, amount, shippingAmount, lines, state: "executed", approvedBy: requireUserId(actor) })
+            .onConflictDoUpdate({ target: [channelRefundRequests.storeId, channelRefundRequests.remoteRefundId], set: { amount, shippingAmount, adjustmentAmount: 0, lines, state: "executed", updatedAt: new Date() } });
         const [closed] = await this.db.update(channelReturns).set({ status: "closed", updatedAt: new Date() }).where(and(eq(channelReturns.organizationId, orgId), eq(channelReturns.id, held.id))).returning();
         return closed ? Ok(closed) : PluginErr("Return not found.", "NOT_FOUND");
     }
@@ -4591,8 +4645,10 @@ export class ChannelConnectorService {
         if (!remoteStatus.ok) {
             return this.transitionExport(orgId, created.value.id, "failed", requireUserId(actor), remoteStatus.error.message, remoteStatus.error.retriable === true ? "transient" : "definitive");
         }
-        if (remoteStatus.value.status === "confirmed") {
-            return this.transitionExport(orgId, created.value.id, "confirmed", requireUserId(actor), "Remote order confirmed.");
+        // `fulfilled` is a received order too: WooCommerce completes virtual and downloadable orders on
+        // arrival, and an export waiting for `confirmed` would wait forever.
+        if (remoteStatus.value.status === "confirmed" || remoteStatus.value.status === "fulfilled") {
+            return this.transitionExport(orgId, created.value.id, "confirmed", requireUserId(actor), remoteStatus.value.status === "fulfilled" ? "Remote order received and completed by the store." : "Remote order confirmed.");
         }
         if (remoteStatus.value.status === "failed" || remoteStatus.value.status === "cancelled") {
             return this.transitionExport(orgId, created.value.id, "failed", requireUserId(actor), `Remote order status: ${remoteStatus.value.status}.`);
@@ -4614,7 +4670,7 @@ export class ChannelConnectorService {
             const mapping = (line.variantId && mappings.find((item) => item.kind === "variant" && item.variantId === line.variantId)) ?? mappings.find((item) => item.kind === "entity" && item.entityId === line.entityId);
             if (!mapping)
                 return PluginErr(`External mapping is missing for order line ${line.id}.`, "MAPPING_MISSING");
-            lines.push({ externalVariantId: mapping.externalId, ...(line.sku ? { sku: line.sku } : {}), title: line.title, quantity: line.quantity, unitPrice: line.unitPrice, totalPrice: line.totalPrice });
+            lines.push({ externalVariantId: mapping.externalId, ...(line.sku ? { sku: line.sku } : {}), title: line.title, quantity: line.quantity, unitPrice: line.unitPrice, totalPrice: line.totalPrice, ...(line.discountAmount > 0 ? { discountAmount: line.discountAmount } : {}) });
         }
         let email = null;
         let name = "";
@@ -4663,7 +4719,9 @@ export class ChannelConnectorService {
         // ponytail: like delivery, a discount is sent only with the whole order; apportion it when multi-store orders exist.
         const discountCode = typeof metadata.promotionCode === "string" && metadata.promotionCode.trim() !== "" ? metadata.promotionCode.trim() : "DISCOUNT";
         const discount = selected.length === lineItems.length && order.discountTotal > 0 ? { code: discountCode, amount: order.discountTotal } : null;
-        return Ok({ orderId, currency: order.currency, grandTotal: linesTotal + (shipping?.amount ?? 0) - (discount?.amount ?? 0), lines, ...(shipping ? { shipping } : {}), ...(discount ? { discount } : {}), customer: { name, email, shippingAddress } });
+        // A line's discount travels with the order discount it is a share of, never without it.
+        const slicedLines = discount ? lines : lines.map(({ discountAmount: _share, ...line }) => line);
+        return Ok({ orderId, currency: order.currency, grandTotal: linesTotal + (shipping?.amount ?? 0) - (discount?.amount ?? 0), lines: slicedLines, ...(shipping ? { shipping } : {}), ...(discount ? { discount } : {}), customer: { name, email, shippingAddress } });
     }
     async reapExports(input) {
         const now = Date.now();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/plugin-channel-connector",
-  "version": "0.76.0",
+  "version": "0.77.1",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -22,15 +22,15 @@
   "dependencies": {
     "@hono/zod-openapi": "^1.2.2",
     "hono": "^4.12.5",
-    "@porulle/core": "0.76.0"
+    "@porulle/core": "0.77.1"
   },
   "devDependencies": {
     "@types/node": "^24.5.2",
     "eslint": "^9.39.1",
     "typescript": "5.9.2",
     "vitest": "^3.2.4",
-    "@porulle/eslint-config": "0.1.0",
-    "@porulle/typescript-config": "0.1.0"
+    "@porulle/typescript-config": "0.1.0",
+    "@porulle/eslint-config": "0.1.0"
   },
   "publishConfig": {
     "access": "public"

package/src/index.ts

@@ -260,6 +260,7 @@ export type {
   ChannelRefundEvent,
   ChannelRefundRequest,
   ChannelReturn,
+  ChannelReturnView,
   ConnectedStore,
   StoreHealth,
 } from "./schema.js";
@@ -918,7 +919,11 @@ export function channelConnectorPlugin(options: ChannelConnectorPluginOptions =
       channels.post("/returns/{id}/approve")
         .summary("Approve a held return: pay the shopper back and book the refund at the store")
         .permission("channels:connect")
-        .handler(async ({ params, orgId, actor, raw }: ChannelRouteContext) => unwrap(await service.approveReturn(orgId, params.id!, { orgId, actor, raw })));
+        .input(z.object({ refundShipping: z.boolean().optional() }))
+        .handler(async ({ params, orgId, actor, raw, input }: ChannelRouteContext) => {
+          const options = z.object({ refundShipping: z.boolean().optional() }).catch({}).parse(input ?? {});
+          return unwrap(await service.approveReturn(orgId, params.id!, { orgId, actor, raw }, options.refundShipping === undefined ? {} : { refundShipping: options.refundShipping }));
+        });
 
       channels.post("/returns/{id}/decline")
         .summary("Decline a held return")

package/src/mock-connector.ts

@@ -94,7 +94,7 @@ const channelEventSchema = z.discriminatedUnion("kind", [
   z.object({ kind: z.literal("inventory.changed"), levels: z.array(level) }),
   z.object({ kind: z.literal("order.cancelled"), remoteOrderId: z.string() }),
   z.object({ kind: z.literal("order.fulfilled"), remoteOrderId: z.string(), partial: z.boolean(), shipments: z.array(shipment) }),
-  z.object({ kind: z.literal("refund.created"), remoteOrderId: z.string(), remoteRefundId: z.string(), lines: z.array(z.object({ externalVariantId: z.string(), quantity: z.number().int() })), amount: z.number().int().exactOptional() }),
+  z.object({ kind: z.literal("refund.created"), remoteOrderId: z.string(), remoteRefundId: z.string(), lines: z.array(z.object({ externalVariantId: z.string(), quantity: z.number().int() })), amount: z.number().int().exactOptional(), shippingAmount: z.number().int().exactOptional() }),
   z.object({ kind: z.literal("return.updated"), remoteReturnId: z.string(), status: z.enum(["approved", "declined", "closed", "cancelled"]) }),
   z.object({ kind: z.literal("connection.revoked") }),
   z.object({ kind: z.literal("compliance.request"), request: z.enum(["customer_data", "customer_redact", "shop_redact"]), data: z.record(z.string(), z.unknown()) }),

package/src/schema.ts

@@ -267,6 +267,8 @@ export const channelReturns = pgTable(
     remoteReturnId: text("remote_return_id").notNull(),
     status: text("status", { enum: ["requested", "approved", "declined", "closed", "cancelled"] }).notNull().default("requested"),
     lines: jsonb("lines").$type<Array<{ orderLineItemId: string; quantity: number }>>().notNull(),
+    /** Delivery the merchant refunded when approving a return held on the platform. */
+    shippingAmount: integer("shipping_amount").notNull().default(0),
     reason: text("reason").notNull(),
     note: text("note"),
     createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
@@ -286,7 +288,12 @@ export const channelRefundRequests = pgTable(
     storeId: uuid("store_id").references(() => connectedStores.id, { onDelete: "cascade" }).notNull(),
     orderId: uuid("order_id").notNull(),
     remoteRefundId: text("remote_refund_id").notNull(),
+    /** Everything the request pays back: its lines, `shippingAmount` and `adjustmentAmount`. */
     amount: integer("amount").notNull(),
+    /** Of `amount`, delivery the store refunded. */
+    shippingAmount: integer("shipping_amount").notNull().default(0),
+    /** Of `amount`, money the store refunded with no line behind it (goodwill). */
+    adjustmentAmount: integer("adjustment_amount").notNull().default(0),
     /** The order lines the store refunded. Null on requests made before it was kept. */
     lines: jsonb("lines").$type<Array<{ lineItemId: string; quantity: number }>>(),
     state: text("state", { enum: ["requested", "approved", "rejected", "executed"] }).notNull().default("requested"),
@@ -329,4 +336,11 @@ export type ChannelOrderExport = typeof channelOrderExports.$inferSelect;
 export type ChannelExportEvent = typeof channelExportEvents.$inferSelect;
 export type ChannelRefundRequest = typeof channelRefundRequests.$inferSelect;
 export type ChannelReturn = typeof channelReturns.$inferSelect;
+/** A held return as its merchant decides it: which order, which items, and how much delivery is refundable. */
+export type ChannelReturnView = ChannelReturn & {
+  orderNumber: string | null;
+  items: Array<{ orderLineItemId: string; title: string; quantity: number }>;
+  /** Delivery not yet refunded on the order: what approving with delivery would pay back. */
+  shippingRefundable: number;
+};
 export type ChannelRefundEvent = typeof channelRefundEvents.$inferSelect;

package/src/service.ts

@@ -64,6 +64,7 @@ import {
   fulfillmentLineItems,
   fulfillmentRecords,
   orderLineItems,
+  orderRefunds,
   orders,
   prices,
   sellableAttributes,
@@ -95,6 +96,7 @@ import {
   type ChannelOrderExport,
   type ChannelRefundRequest,
   type ChannelReturn,
+  type ChannelReturnView,
   type ConnectedStore,
 } from "./schema.js";
 import type { StoreHealth } from "./schema.js";
@@ -5321,29 +5323,45 @@ export class ChannelConnectorService {
     const orderLines = await this.db.select().from(orderLineItems).where(eq(orderLineItems.orderId, orderId));
     const mappings = await this.db.select().from(channelEntityMap).where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, store.id)));
     const refundLines: Array<{ lineItemId: string; quantity: number }> = [];
-    let clean = event.lines.length > 0;
+    // Every line the store named is one of ours, with that much still refundable.
+    let mapped = true;
     for (const line of event.lines) {
       const externalId = line.externalVariantId;
       const quantity = line.quantity;
       const mapping = mappings.find((item) => item.externalId === externalId);
       const orderLine = mapping ? orderLines.find((item) => item.variantId === mapping.variantId || item.entityId === mapping.entityId) : undefined;
-      if (!orderLine || !Number.isInteger(quantity) || quantity < 1 || quantity > orderLine.quantity - orderLine.refundedQuantity) clean = false;
+      if (!orderLine || !Number.isInteger(quantity) || quantity < 1 || quantity > orderLine.quantity - orderLine.refundedQuantity) mapped = false;
       else refundLines.push({ lineItemId: orderLine.id, quantity });
     }
     const priced = refundLines.reduce((sum, line) => {
       const item = orderLines.find((candidate) => candidate.id === line.lineItemId)!;
       return sum + Math.round((item.totalPrice + item.taxAmount - item.discountAmount) * line.quantity / item.quantity);
     }, 0);
-    // What the store refunded, when it says, and never more than the platform's own price for the lines:
-    // a store can refund part of a line, or a line it discounted, but cannot claim more than it sold.
-    const amount = event.amount === undefined ? priced : Math.min(Math.max(0, event.amount), priced);
     const [order] = await this.db.select().from(orders).where(and(eq(orders.organizationId, orgId), eq(orders.id, orderId)));
     if (!order) return PluginErr("Order not found.", "NOT_FOUND");
+    const completed = (await this.db.select({ amount: orderRefunds.amount, shippingAmount: orderRefunds.shippingAmount }).from(orderRefunds)
+      .where(and(eq(orderRefunds.orderId, orderId), eq(orderRefunds.status, "completed"))));
+    const shippingLeft = Math.max(0, order.shippingTotal - completed.reduce((sum, refund) => sum + refund.shippingAmount, 0));
+    const orderLeft = Math.max(0, order.grandTotal - completed.reduce((sum, refund) => sum + refund.amount, 0));
+    // What the store refunded, and never more than the shopper paid for what it names: the lines at most
+    // at the platform's own price (part of a line, or a line the store discounted, is less), the delivery
+    // at most what of it is not refunded yet, money with no line behind it (goodwill) only when the refund
+    // names no line, and the whole at most what the order has left.
+    const storeShipping = Math.max(0, event.shippingAmount ?? 0);
+    const shippingAmount = Math.min(storeShipping, shippingLeft);
+    const rest = event.amount === undefined ? priced : Math.max(0, event.amount - storeShipping);
+    const linesAmount = Math.min(rest, priced);
+    const goodwill = event.lines.length === 0 ? rest : 0;
+    const adjustmentAmount = Math.max(0, Math.min(goodwill, orderLeft - linesAmount - shippingAmount));
+    const amount = Math.min(linesAmount + shippingAmount + adjustmentAmount, orderLeft);
+    // A refund that pays nothing (a restock, or nothing left to pay) asks nobody for money.
+    if (amount === 0) return Ok(null);
     const max = this.options.refundAutoMax ?? order.amountCaptured ?? order.grandTotal;
     const ageOk = Date.now() - store.createdAt.getTime() >= (this.options.newStoreDays ?? 7) * 86_400_000;
-    // Only a whole-line refund is automatic; any other amount is a person's call.
-    const auto = clean && amount > 0 && amount === priced && ageOk && amount <= max;
-    const rows = await this.db.insert(channelRefundRequests).values({ organizationId: orgId, storeId: store.id, orderId, remoteRefundId, amount, lines: clean ? refundLines : null, state: auto ? "approved" : "requested", approvedBy: auto ? requireUserId(actor) : null }).returning();
+    // Only whole lines, at exactly the platform's price with exactly their delivery, are automatic; any
+    // other amount is a person's call.
+    const auto = mapped && refundLines.length > 0 && adjustmentAmount === 0 && linesAmount === priced && shippingAmount === storeShipping && ageOk && amount <= max;
+    const rows = await this.db.insert(channelRefundRequests).values({ organizationId: orgId, storeId: store.id, orderId, remoteRefundId, amount, shippingAmount, adjustmentAmount, lines: mapped ? refundLines : null, state: auto ? "approved" : "requested", approvedBy: auto ? requireUserId(actor) : null }).returning();
     const request = rows[0] as ChannelRefundRequest;
     await this.db.insert(channelRefundEvents).values({ organizationId: orgId, requestId: request.id, fromState: null, toState: request.state, reason: auto ? "Automatic guarded refund" : "Operator approval required", changedBy: requireUserId(actor) });
     if (auto) {
@@ -5359,17 +5377,29 @@ export class ChannelConnectorService {
   }
 
   private async executeRefund(request: ChannelRefundRequest, lines: Array<{ lineItemId: string; quantity: number }>, actor: Actor): Promise<PluginResult<ChannelRefundRequest>> {
-    const ordersService = this.services.orders as { refundLines(orderId: string, input: { lines: Array<{ lineItemId: string; quantity: number }>; reason?: string; amount?: number }, actor: Actor): Promise<{ ok: boolean; error?: { message: string } }> };
-    // A request that kept its lines pays back its own amount; an older one is priced from the lines rebuilt for it.
-    const result = await ordersService.refundLines(request.orderId, { lines, reason: `Channel refund ${request.remoteRefundId}`, ...(request.lines ? { amount: request.amount } : {}) }, actor);
+    const ordersService = this.services.orders as { refundLines(orderId: string, input: { lines: Array<{ lineItemId: string; quantity: number }>; reason?: string; amount?: number; shippingAmount?: number; adjustmentAmount?: number }, actor: Actor): Promise<{ ok: boolean; error?: { message: string } }> };
+    // A request that kept its lines pays back its own amount for them; an older one is priced from the
+    // lines rebuilt for it. Delivery and goodwill ride beside the lines.
+    const linesAmount = request.amount - request.shippingAmount - request.adjustmentAmount;
+    const result = await ordersService.refundLines(request.orderId, {
+      lines,
+      reason: `Channel refund ${request.remoteRefundId}`,
+      ...(request.lines && lines.length > 0 ? { amount: linesAmount } : {}),
+      ...(request.shippingAmount > 0 ? { shippingAmount: request.shippingAmount } : {}),
+      ...(request.adjustmentAmount > 0 ? { adjustmentAmount: request.adjustmentAmount } : {}),
+    }, actor);
     if (!result.ok) return PluginErr(result.error?.message ?? "Refund execution failed.");
     const [updated] = await this.db.update(channelRefundRequests).set({ state: "executed", updatedAt: new Date() }).where(and(eq(channelRefundRequests.organizationId, request.organizationId), eq(channelRefundRequests.id, request.id), eq(channelRefundRequests.state, "approved"))).returning();
     await this.db.insert(channelRefundEvents).values({ organizationId: request.organizationId, requestId: request.id, fromState: "approved", toState: "executed", reason: "Platform refund executed", changedBy: requireUserId(actor) });
     return Ok(updated as ChannelRefundRequest);
   }
 
-  async listRefundRequests(orgId: string): Promise<PluginResult<ChannelRefundRequest[]>> {
-    return Ok(await this.db.select().from(channelRefundRequests).where(and(eq(channelRefundRequests.organizationId, orgId), eq(channelRefundRequests.state, "requested"))) as ChannelRefundRequest[]);
+  /** Held refunds, each with the order number an approver knows the order by. */
+  async listRefundRequests(orgId: string): Promise<PluginResult<Array<ChannelRefundRequest & { orderNumber: string | null }>>> {
+    const rows = await this.db.select({ request: channelRefundRequests, orderNumber: orders.orderNumber }).from(channelRefundRequests)
+      .leftJoin(orders, eq(orders.id, channelRefundRequests.orderId))
+      .where(and(eq(channelRefundRequests.organizationId, orgId), eq(channelRefundRequests.state, "requested")));
+    return Ok(rows.map((row) => ({ ...(row.request as ChannelRefundRequest), orderNumber: row.orderNumber })));
   }
 
   async approveRefund(orgId: string, id: string, actor: { userId: string }): Promise<PluginResult<ChannelRefundRequest>> {
@@ -5626,7 +5656,7 @@ export class ChannelConnectorService {
   }
 
   /** Returns held on the platform (stores with none of their own) that wait for their merchant. */
-  async listReturns(orgId: string, context?: StoreReadContext): Promise<PluginResult<ChannelReturn[]>> {
+  async listReturns(orgId: string, context?: StoreReadContext): Promise<PluginResult<ChannelReturnView[]>> {
     const allowed = await this.allowedStores(orgId, context);
     if (allowed !== null && allowed.length === 0) return Ok([]);
     const rows = await this.db.select().from(channelReturns).where(and(
@@ -5635,16 +5665,33 @@ export class ChannelConnectorService {
       sql`${channelReturns.remoteReturnId} like ${`${PLATFORM_RETURN_PREFIX}%`}`,
       ...(allowed === null ? [] : [inArray(channelReturns.storeId, [...allowed])]),
     )).orderBy(desc(channelReturns.createdAt));
-    return Ok(rows);
+    if (rows.length === 0) return Ok([]);
+    const orderIds = [...new Set(rows.map((row) => row.orderId))];
+    const orderRows = await this.db.select({ id: orders.id, orderNumber: orders.orderNumber, shippingTotal: orders.shippingTotal }).from(orders)
+      .where(and(eq(orders.organizationId, orgId), inArray(orders.id, orderIds)));
+    const lineRows = await this.db.select({ id: orderLineItems.id, title: orderLineItems.title }).from(orderLineItems).where(inArray(orderLineItems.orderId, orderIds));
+    const refunded = await this.db.select({ orderId: orderRefunds.orderId, shippingAmount: orderRefunds.shippingAmount }).from(orderRefunds)
+      .where(and(inArray(orderRefunds.orderId, orderIds), eq(orderRefunds.status, "completed")));
+    return Ok(rows.map((row) => {
+      const order = orderRows.find((candidate) => candidate.id === row.orderId);
+      const shippingRefunded = refunded.filter((refund) => refund.orderId === row.orderId).reduce((sum, refund) => sum + refund.shippingAmount, 0);
+      return {
+        ...row,
+        orderNumber: order?.orderNumber ?? null,
+        items: row.lines.map((line) => ({ orderLineItemId: line.orderLineItemId, title: lineRows.find((candidate) => candidate.id === line.orderLineItemId)?.title ?? "Item", quantity: line.quantity })),
+        shippingRefundable: Math.max(0, (order?.shippingTotal ?? 0) - shippingRefunded),
+      };
+    }));
   }
 
   /**
-   * The merchant takes a held return back: the shopper is paid back those lines, then the refund is
-   * booked at the store with the stock put back, and kept as an executed refund request under the
-   * store's own refund id so the store's webhook for it pays nobody twice. If the store will not book
-   * it, the shopper has still been paid and the return stays `approved`; approving again only books it.
+   * The merchant takes a held return back: the shopper is paid back those lines (and the delivery, when
+   * the merchant refunds it), then the refund is booked at the store with the stock put back, and kept
+   * as an executed refund request under the store's own refund id so the store's webhook for it pays
+   * nobody twice. If the store will not book it, the shopper has still been paid and the return stays
+   * `approved`; approving again only books it, with the delivery decided the first time.
    */
-  async approveReturn(orgId: string, id: string, context?: StoreReadContext): Promise<PluginResult<ChannelReturn>> {
+  async approveReturn(orgId: string, id: string, context?: StoreReadContext, options: { refundShipping?: boolean } = {}): Promise<PluginResult<ChannelReturn>> {
     const [held] = await this.db.select().from(channelReturns).where(and(eq(channelReturns.organizationId, orgId), eq(channelReturns.id, id)));
     if (!held || !held.remoteReturnId.startsWith(PLATFORM_RETURN_PREFIX)) return PluginErr("Return not found.", "NOT_FOUND");
     const reached = await this.reachableStore(orgId, held.storeId, context);
@@ -5665,11 +5712,18 @@ export class ChannelConnectorService {
       priced.push({ lineItemId: item.id, quantity: line.quantity, variantId: item.variantId, amount: Math.round((item.totalPrice + item.taxAmount - item.discountAmount) * line.quantity / item.quantity) });
     }
     const actor = createSystemActor(orgId);
+    let shippingAmount = held.shippingAmount;
     if (held.status === "requested") {
-      const ordersService = this.services.orders as { refundLines(orderId: string, input: { lines: Array<{ lineItemId: string; quantity: number }>; reason?: string }, actor: Actor): Promise<{ ok: boolean; error?: { message: string } }> };
-      const refunded = await ordersService.refundLines(held.orderId, { lines: priced.map(({ lineItemId, quantity }) => ({ lineItemId, quantity })), reason: `Return ${held.id}` }, actor);
+      if (options.refundShipping === true) {
+        const [order] = await this.db.select({ shippingTotal: orders.shippingTotal }).from(orders).where(and(eq(orders.organizationId, orgId), eq(orders.id, held.orderId)));
+        const refunded = await this.db.select({ shippingAmount: orderRefunds.shippingAmount }).from(orderRefunds)
+          .where(and(eq(orderRefunds.orderId, held.orderId), eq(orderRefunds.status, "completed")));
+        shippingAmount = Math.max(0, (order?.shippingTotal ?? 0) - refunded.reduce((sum, refund) => sum + refund.shippingAmount, 0));
+      }
+      const ordersService = this.services.orders as { refundLines(orderId: string, input: { lines: Array<{ lineItemId: string; quantity: number }>; reason?: string; shippingAmount?: number }, actor: Actor): Promise<{ ok: boolean; error?: { message: string } }> };
+      const refunded = await ordersService.refundLines(held.orderId, { lines: priced.map(({ lineItemId, quantity }) => ({ lineItemId, quantity })), reason: `Return ${held.id}`, ...(shippingAmount > 0 ? { shippingAmount } : {}) }, actor);
       if (!refunded.ok) return PluginErr(refunded.error?.message ?? "The shopper could not be paid back.", "REFUND_FAILED");
-      await this.db.update(channelReturns).set({ status: "approved", updatedAt: new Date() }).where(and(eq(channelReturns.organizationId, orgId), eq(channelReturns.id, held.id)));
+      await this.db.update(channelReturns).set({ status: "approved", shippingAmount, updatedAt: new Date() }).where(and(eq(channelReturns.organizationId, orgId), eq(channelReturns.id, held.id)));
     }
 
     const variantIds = priced.flatMap((line) => (line.variantId === null ? [] : [line.variantId]));
@@ -5681,13 +5735,13 @@ export class ChannelConnectorService {
       if (!externalId) return PluginErr("The shopper was paid back, but the store has no record of a returned line, so it was not booked there.", "CHANNEL_MAPPING_MISSING");
       storeLines.push({ externalVariantId: externalId, quantity: line.quantity, amount: line.amount });
     }
-    const amount = storeLines.reduce((sum, line) => sum + line.amount, 0);
-    const booked = await connector.recordRefund(store as ChannelStore, exported.remoteOrderId, { lines: storeLines, amount, reason: `Return: ${held.reason}`, restock: true });
+    const amount = storeLines.reduce((sum, line) => sum + line.amount, 0) + shippingAmount;
+    const booked = await connector.recordRefund(store as ChannelStore, exported.remoteOrderId, { lines: storeLines, amount, ...(shippingAmount > 0 ? { shippingAmount } : {}), reason: `Return: ${held.reason}`, restock: true });
     if (!booked.ok) return PluginErr(`The shopper was paid back, but the store did not record the refund (${booked.error.message}). Approve again to retry.`, "CHANNEL_REFUND_NOT_RECORDED");
     const lines = priced.map(({ lineItemId, quantity }) => ({ lineItemId, quantity }));
     await this.db.insert(channelRefundRequests)
-      .values({ organizationId: orgId, storeId: store.id, orderId: held.orderId, remoteRefundId: booked.value.remoteRefundId, amount, lines, state: "executed", approvedBy: requireUserId(actor) })
-      .onConflictDoUpdate({ target: [channelRefundRequests.storeId, channelRefundRequests.remoteRefundId], set: { amount, lines, state: "executed", updatedAt: new Date() } });
+      .values({ organizationId: orgId, storeId: store.id, orderId: held.orderId, remoteRefundId: booked.value.remoteRefundId, amount, shippingAmount, lines, state: "executed", approvedBy: requireUserId(actor) })
+      .onConflictDoUpdate({ target: [channelRefundRequests.storeId, channelRefundRequests.remoteRefundId], set: { amount, shippingAmount, adjustmentAmount: 0, lines, state: "executed", updatedAt: new Date() } });
     const [closed] = await this.db.update(channelReturns).set({ status: "closed", updatedAt: new Date() }).where(and(eq(channelReturns.organizationId, orgId), eq(channelReturns.id, held.id))).returning();
     return closed ? Ok(closed) : PluginErr("Return not found.", "NOT_FOUND");
   }
@@ -5789,13 +5843,15 @@ export class ChannelConnectorService {
         remoteStatus.error.retriable === true ? "transient" : "definitive",
       );
     }
-    if (remoteStatus.value.status === "confirmed") {
+    // `fulfilled` is a received order too: WooCommerce completes virtual and downloadable orders on
+    // arrival, and an export waiting for `confirmed` would wait forever.
+    if (remoteStatus.value.status === "confirmed" || remoteStatus.value.status === "fulfilled") {
       return this.transitionExport(
         orgId,
         created.value.id,
         "confirmed",
         requireUserId(actor),
-        "Remote order confirmed.",
+        remoteStatus.value.status === "fulfilled" ? "Remote order received and completed by the store." : "Remote order confirmed.",
       );
     }
     if (remoteStatus.value.status === "failed" || remoteStatus.value.status === "cancelled") {
@@ -5828,7 +5884,7 @@ export class ChannelConnectorService {
     for (const line of selected) {
       const mapping = (line.variantId && mappings.find((item) => item.kind === "variant" && item.variantId === line.variantId)) ?? mappings.find((item) => item.kind === "entity" && item.entityId === line.entityId);
       if (!mapping) return PluginErr(`External mapping is missing for order line ${line.id}.`, "MAPPING_MISSING");
-      lines.push({ externalVariantId: mapping.externalId, ...(line.sku ? { sku: line.sku } : {}), title: line.title, quantity: line.quantity, unitPrice: line.unitPrice, totalPrice: line.totalPrice });
+      lines.push({ externalVariantId: mapping.externalId, ...(line.sku ? { sku: line.sku } : {}), title: line.title, quantity: line.quantity, unitPrice: line.unitPrice, totalPrice: line.totalPrice, ...(line.discountAmount > 0 ? { discountAmount: line.discountAmount } : {}) });
     }
 
     let email: string | null = null;
@@ -5876,7 +5932,9 @@ export class ChannelConnectorService {
     // ponytail: like delivery, a discount is sent only with the whole order; apportion it when multi-store orders exist.
     const discountCode = typeof metadata.promotionCode === "string" && metadata.promotionCode.trim() !== "" ? metadata.promotionCode.trim() : "DISCOUNT";
     const discount = selected.length === lineItems.length && order.discountTotal > 0 ? { code: discountCode, amount: order.discountTotal } : null;
-    return Ok({ orderId, currency: order.currency, grandTotal: linesTotal + (shipping?.amount ?? 0) - (discount?.amount ?? 0), lines, ...(shipping ? { shipping } : {}), ...(discount ? { discount } : {}), customer: { name, email, shippingAddress } });
+    // A line's discount travels with the order discount it is a share of, never without it.
+    const slicedLines = discount ? lines : lines.map(({ discountAmount: _share, ...line }) => line);
+    return Ok({ orderId, currency: order.currency, grandTotal: linesTotal + (shipping?.amount ?? 0) - (discount?.amount ?? 0), lines: slicedLines, ...(shipping ? { shipping } : {}), ...(discount ? { discount } : {}), customer: { name, email, shippingAddress } });
   }
 
   async reapExports(input: { definitiveMs: number; transientMs: number }): Promise<{ abandonedCount: number; refundedOrderIds: string[] }> {