@porulle/plugin-channel-connector 0.75.0 → 0.77.0

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, 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

@@ -732,6 +732,22 @@ export function channelConnectorPlugin(options = {}) {
                 .summary("Reject a channel refund request")
                 .permission("channels:manage")
                 .handler(async ({ params, orgId, actor }) => unwrap(await service.rejectRefund(orgId, params.id, { userId: requireUserId(actor) })));
+            channels.get("/returns")
+                .summary("List the returns held on the platform that wait for their merchant")
+                .permission("channels:connect")
+                .handler(async ({ orgId, actor, raw }) => unwrap(await service.listReturns(orgId, { orgId, actor, raw })));
+            channels.post("/returns/{id}/approve")
+                .summary("Approve a held return: pay the shopper back and book the refund at the store")
+                .permission("channels:connect")
+                .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")
+                .handler(async ({ params, orgId, actor, raw }) => unwrap(await service.declineReturn(orgId, params.id, { orgId, actor, raw })));
             channels.post("/exports/{id}/retry")
                 .summary("Retry a failed channel order export")
                 .permission("channels:manage")

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";
@@ -2354,4 +2405,16 @@ export type ChannelCatalogPushEvent = typeof channelCatalogPushEvents.$inferSele
 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 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"];
@@ -31,6 +31,8 @@ export declare const CHANNEL_INVENTORY_MAX_ITEMS_PER_INVOCATION = 20;
 export declare const REMOTE_ORDER_REFRESH_MS: number;
 /** How often a merchant's visit may make the plugin call a store to check its health. */
 export declare const STORE_HEALTH_INTERVAL_MS: number;
+/** The `remote_return_id` of a return held on the platform, for a store with no returns of its own. */
+export declare const PLATFORM_RETURN_PREFIX = "platform:";
 export declare const CHANNEL_ORDER_CANCELLED_REASON = "channel_order_cancelled";
 export declare function catalogPushRetryDelayMs(attempts: number): number;
 export interface CatalogPushJobResult extends Record<string, unknown> {
@@ -710,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>>;
@@ -752,6 +757,20 @@ export declare class ChannelConnectorService {
         remoteReturnId: string;
         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<ChannelReturnView[]>>;
+    /**
+     * 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, 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. */
     isOrderClosed(orgId: string, orderId: string): Promise<boolean>;
     exportOrder(orgId: string, storeId: string, slice: ChannelOrderSlice, actor: Actor): Promise<PluginResult<ChannelOrderExport>>;

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";
@@ -37,6 +37,8 @@ export const CHANNEL_INVENTORY_MAX_ITEMS_PER_INVOCATION = 20;
 export const REMOTE_ORDER_REFRESH_MS = 5 * 60 * 1000;
 /** How often a merchant's visit may make the plugin call a store to check its health. */
 export const STORE_HEALTH_INTERVAL_MS = 10 * 60 * 1000;
+/** The `remote_return_id` of a return held on the platform, for a store with no returns of its own. */
+export const PLATFORM_RETURN_PREFIX = "platform:";
 export const CHANNEL_ORDER_CANCELLED_REASON = "channel_order_cancelled";
 const CATALOG_PUSH_RETRY_BASE_MS = 60_000;
 const CATALOG_PUSH_RETRY_MAX_MS = 60 * 60 * 1000;
@@ -4174,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 });
         }
@@ -4189,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) {
@@ -4215,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();
@@ -4416,7 +4447,9 @@ export class ChannelConnectorService {
         if (!store || store.status !== "connected")
             return PluginErr("The store this order went to is not connected.", "NOT_FOUND");
         const connector = this.connectors.get(store.provider);
-        if (!connector?.requestReturn)
+        // A store with no returns of its own (WooCommerce) has them held here, for its merchant to approve.
+        const hosted = connector?.requestReturn === undefined && connector?.recordRefund !== undefined;
+        if (!connector || (!connector.requestReturn && !hosted))
             return PluginErr(`Returns are not available for ${store.provider} stores.`, "NOT_IMPLEMENTED");
         const lines = await this.db.select({ id: orderLineItems.id, variantId: orderLineItems.variantId, quantity: orderLineItems.quantity }).from(orderLineItems).where(eq(orderLineItems.orderId, orderId));
         const variantIds = lines.flatMap((line) => (line.variantId === null ? [] : [line.variantId]));
@@ -4436,14 +4469,18 @@ export class ChannelConnectorService {
                 return PluginErr(`The store has no record of line ${wanted.orderLineItemId}, so it cannot take it back.`, "CHANNEL_MAPPING_MISSING");
             remote.push({ externalVariantId: externalId, quantity: wanted.quantity });
         }
-        const asked = await connector.requestReturn(store, exported.remoteOrderId, { lines: remote, reason: input.reason, ...(input.note ? { note: input.note } : {}) });
-        if (!asked.ok)
-            return PluginErr(asked.error.message, asked.error.code);
+        let remoteReturnId = `${PLATFORM_RETURN_PREFIX}${crypto.randomUUID()}`;
+        if (connector.requestReturn) {
+            const asked = await connector.requestReturn(store, exported.remoteOrderId, { lines: remote, reason: input.reason, ...(input.note ? { note: input.note } : {}) });
+            if (!asked.ok)
+                return PluginErr(asked.error.message, asked.error.code);
+            remoteReturnId = asked.value.remoteReturnId;
+        }
         const [row] = await this.db.insert(channelReturns).values({
             organizationId: orgId,
             storeId: store.id,
             orderId,
-            remoteReturnId: asked.value.remoteReturnId,
+            remoteReturnId,
             status: "requested",
             lines: input.lines,
             reason: input.reason,
@@ -4453,6 +4490,111 @@ export class ChannelConnectorService {
             return PluginErr("The return could not be recorded.");
         return Ok(row);
     }
+    /** Returns held on the platform (stores with none of their own) that wait for their merchant. */
+    async listReturns(orgId, context) {
+        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(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));
+        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 (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, 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");
+        const reached = await this.reachableStore(orgId, held.storeId, context);
+        if (!reached.ok)
+            return PluginErr("Return not found.", "NOT_FOUND");
+        if (held.status !== "requested" && held.status !== "approved")
+            return PluginErr(`This return is already ${held.status}.`, "CONFLICT");
+        const store = reached.value;
+        const connector = this.connectors.get(store.provider);
+        if (!connector?.recordRefund)
+            return PluginErr(`Returns are not available for ${store.provider} stores.`, "NOT_IMPLEMENTED");
+        const [exported] = await this.db.select({ remoteOrderId: channelOrderExports.remoteOrderId }).from(channelOrderExports)
+            .where(and(eq(channelOrderExports.organizationId, orgId), eq(channelOrderExports.orderId, held.orderId), eq(channelOrderExports.storeId, store.id)));
+        if (!exported?.remoteOrderId)
+            return PluginErr("This order never reached the store.", "NOT_FOUND");
+        const orderLines = await this.db.select().from(orderLineItems).where(eq(orderLineItems.orderId, held.orderId));
+        const priced = [];
+        for (const line of held.lines) {
+            const item = orderLines.find((candidate) => candidate.id === line.orderLineItemId);
+            if (!item)
+                return PluginErr(`Line ${line.orderLineItemId} is no longer on this order.`, "VALIDATION_FAILED");
+            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}`, ...(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", 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)
+            .where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, store.id), eq(channelEntityMap.kind, "variant"), inArray(channelEntityMap.variantId, variantIds)));
+        const storeLines = [];
+        for (const line of priced) {
+            const externalId = mapped.find((entry) => entry.variantId === line.variantId)?.externalId;
+            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) + 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, 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");
+    }
+    /** The merchant refuses a held return. Nothing moves. */
+    async declineReturn(orgId, id, context) {
+        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);
+        if (!reached.ok)
+            return PluginErr("Return not found.", "NOT_FOUND");
+        const [declined] = await this.db.update(channelReturns).set({ status: "declined", updatedAt: new Date() })
+            .where(and(eq(channelReturns.organizationId, orgId), eq(channelReturns.id, held.id), eq(channelReturns.status, "requested"))).returning();
+        return declined ? Ok(declined) : PluginErr(`This return is already ${held.status}.`, "CONFLICT");
+    }
     /** A cancelled or refunded order: nothing to push to a store, ever again. */
     async isOrderClosed(orgId, orderId) {
         const [order] = await this.db.select({ status: orders.status }).from(orders).where(and(eq(orders.organizationId, orgId), eq(orders.id, orderId)));
@@ -4526,7 +4668,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 = "";
@@ -4575,7 +4717,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.75.0",
+  "version": "0.77.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -22,7 +22,7 @@
   "dependencies": {
     "@hono/zod-openapi": "^1.2.2",
     "hono": "^4.12.5",
-    "@porulle/core": "0.75.0"
+    "@porulle/core": "0.77.0"
   },
   "devDependencies": {
     "@types/node": "^24.5.2",

package/src/index.ts

@@ -259,6 +259,8 @@ export type {
   ChannelOrderExport,
   ChannelRefundEvent,
   ChannelRefundRequest,
+  ChannelReturn,
+  ChannelReturnView,
   ConnectedStore,
   StoreHealth,
 } from "./schema.js";
@@ -909,6 +911,25 @@ export function channelConnectorPlugin(options: ChannelConnectorPluginOptions =
         .permission("channels:manage")
         .handler(async ({ params, orgId, actor }: ChannelRouteContext) => unwrap(await service.rejectRefund(orgId, params.id!, { userId: requireUserId(actor) })));
 
+      channels.get("/returns")
+        .summary("List the returns held on the platform that wait for their merchant")
+        .permission("channels:connect")
+        .handler(async ({ orgId, actor, raw }: ChannelRouteContext) => unwrap(await service.listReturns(orgId, { orgId, actor, raw })));
+
+      channels.post("/returns/{id}/approve")
+        .summary("Approve a held return: pay the shopper back and book the refund at the store")
+        .permission("channels:connect")
+        .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")
+        .permission("channels:connect")
+        .handler(async ({ params, orgId, actor, raw }: ChannelRouteContext) => unwrap(await service.declineReturn(orgId, params.id!, { orgId, actor, raw })));
+
       channels.post("/exports/{id}/retry")
         .summary("Retry a failed channel order export")
         .permission("channels:manage")

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"),
@@ -328,4 +335,12 @@ export type ChannelCatalogPushEvent = typeof channelCatalogPushEvents.$inferSele
 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,
@@ -94,6 +95,8 @@ import {
   type ChannelCatalogConflict,
   type ChannelOrderExport,
   type ChannelRefundRequest,
+  type ChannelReturn,
+  type ChannelReturnView,
   type ConnectedStore,
 } from "./schema.js";
 import type { StoreHealth } from "./schema.js";
@@ -142,6 +145,8 @@ export const REMOTE_ORDER_REFRESH_MS = 5 * 60 * 1000;
 
 /** How often a merchant's visit may make the plugin call a store to check its health. */
 export const STORE_HEALTH_INTERVAL_MS = 10 * 60 * 1000;
+/** The `remote_return_id` of a return held on the platform, for a store with no returns of its own. */
+export const PLATFORM_RETURN_PREFIX = "platform:";
 
 export const CHANNEL_ORDER_CANCELLED_REASON = "channel_order_cancelled";
 
@@ -5318,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) {
@@ -5356,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>> {
@@ -5582,7 +5615,9 @@ export class ChannelConnectorService {
     const store = await this.getStoreRecord(orgId, exported.storeId);
     if (!store || store.status !== "connected") return PluginErr("The store this order went to is not connected.", "NOT_FOUND");
     const connector = this.connectors.get(store.provider);
-    if (!connector?.requestReturn) return PluginErr(`Returns are not available for ${store.provider} stores.`, "NOT_IMPLEMENTED");
+    // A store with no returns of its own (WooCommerce) has them held here, for its merchant to approve.
+    const hosted = connector?.requestReturn === undefined && connector?.recordRefund !== undefined;
+    if (!connector || (!connector.requestReturn && !hosted)) return PluginErr(`Returns are not available for ${store.provider} stores.`, "NOT_IMPLEMENTED");
 
     const lines = await this.db.select({ id: orderLineItems.id, variantId: orderLineItems.variantId, quantity: orderLineItems.quantity }).from(orderLineItems).where(eq(orderLineItems.orderId, orderId));
     const variantIds = lines.flatMap((line) => (line.variantId === null ? [] : [line.variantId]));
@@ -5600,13 +5635,17 @@ export class ChannelConnectorService {
       remote.push({ externalVariantId: externalId, quantity: wanted.quantity });
     }
 
-    const asked = await connector.requestReturn(store as ChannelStore, exported.remoteOrderId, { lines: remote, reason: input.reason, ...(input.note ? { note: input.note } : {}) });
-    if (!asked.ok) return PluginErr(asked.error.message, asked.error.code);
+    let remoteReturnId = `${PLATFORM_RETURN_PREFIX}${crypto.randomUUID()}`;
+    if (connector.requestReturn) {
+      const asked = await connector.requestReturn(store as ChannelStore, exported.remoteOrderId, { lines: remote, reason: input.reason, ...(input.note ? { note: input.note } : {}) });
+      if (!asked.ok) return PluginErr(asked.error.message, asked.error.code);
+      remoteReturnId = asked.value.remoteReturnId;
+    }
     const [row] = await this.db.insert(channelReturns).values({
       organizationId: orgId,
       storeId: store.id,
       orderId,
-      remoteReturnId: asked.value.remoteReturnId,
+      remoteReturnId,
       status: "requested",
       lines: input.lines,
       reason: input.reason,
@@ -5616,6 +5655,108 @@ export class ChannelConnectorService {
     return Ok(row);
   }
 
+  /** Returns held on the platform (stores with none of their own) that wait for their merchant. */
+  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(
+      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));
+    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 (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, 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);
+    if (!reached.ok) return PluginErr("Return not found.", "NOT_FOUND");
+    if (held.status !== "requested" && held.status !== "approved") return PluginErr(`This return is already ${held.status}.`, "CONFLICT");
+    const store = reached.value;
+    const connector = this.connectors.get(store.provider);
+    if (!connector?.recordRefund) return PluginErr(`Returns are not available for ${store.provider} stores.`, "NOT_IMPLEMENTED");
+    const [exported] = await this.db.select({ remoteOrderId: channelOrderExports.remoteOrderId }).from(channelOrderExports)
+      .where(and(eq(channelOrderExports.organizationId, orgId), eq(channelOrderExports.orderId, held.orderId), eq(channelOrderExports.storeId, store.id)));
+    if (!exported?.remoteOrderId) return PluginErr("This order never reached the store.", "NOT_FOUND");
+
+    const orderLines = await this.db.select().from(orderLineItems).where(eq(orderLineItems.orderId, held.orderId));
+    const priced: Array<{ lineItemId: string; quantity: number; variantId: string | null; amount: number }> = [];
+    for (const line of held.lines) {
+      const item = orderLines.find((candidate) => candidate.id === line.orderLineItemId);
+      if (!item) return PluginErr(`Line ${line.orderLineItemId} is no longer on this order.`, "VALIDATION_FAILED");
+      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 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", 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)
+      .where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, store.id), eq(channelEntityMap.kind, "variant"), inArray(channelEntityMap.variantId, variantIds)));
+    const storeLines: Array<{ externalVariantId: string; quantity: number; amount: number }> = [];
+    for (const line of priced) {
+      const externalId = mapped.find((entry) => entry.variantId === line.variantId)?.externalId;
+      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) + 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, 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");
+  }
+
+  /** The merchant refuses a held return. Nothing moves. */
+  async declineReturn(orgId: string, id: string, context?: StoreReadContext): 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);
+    if (!reached.ok) return PluginErr("Return not found.", "NOT_FOUND");
+    const [declined] = await this.db.update(channelReturns).set({ status: "declined", updatedAt: new Date() })
+      .where(and(eq(channelReturns.organizationId, orgId), eq(channelReturns.id, held.id), eq(channelReturns.status, "requested"))).returning();
+    return declined ? Ok(declined) : PluginErr(`This return is already ${held.status}.`, "CONFLICT");
+  }
+
   /** A cancelled or refunded order: nothing to push to a store, ever again. */
   async isOrderClosed(orgId: string, orderId: string): Promise<boolean> {
     const [order] = await this.db.select({ status: orders.status }).from(orders).where(and(eq(orders.organizationId, orgId), eq(orders.id, orderId)));
@@ -5741,7 +5882,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;
@@ -5789,7 +5930,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[] }> {