@porulle/plugin-channel-connector 0.74.5 → 0.76.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, ConnectedStore, StoreHealth, } from "./schema.js";
 export declare function channelConnectorPlugin(options?: ChannelConnectorPluginOptions): import("@porulle/core").CommercePlugin;

package/dist/index.js

@@ -732,6 +732,18 @@ 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")
+                .handler(async ({ params, orgId, actor, raw }) => unwrap(await service.approveReturn(orgId, params.id, { orgId, actor, raw })));
+            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

@@ -73,6 +73,7 @@ export declare function mockChannelConnector(options?: MockChannelConnectorOptio
                 externalVariantId: string;
                 quantity: number;
             }[];
+            amount?: 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() })) }),
+    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("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

@@ -2106,6 +2106,31 @@ export declare const channelRefundRequests: import("drizzle-orm/pg-core/table").
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        lines: import("@porulle/core/drizzle").PgColumn<{
+            name: "lines";
+            tableName: "channel_refund_requests";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: {
+                lineItemId: string;
+                quantity: number;
+            }[];
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: {
+                lineItemId: string;
+                quantity: number;
+            }[];
+        }>;
         state: import("@porulle/core/drizzle").PgColumn<{
             name: "state";
             tableName: "channel_refund_requests";
@@ -2329,4 +2354,5 @@ 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;
 export type ChannelRefundEvent = typeof channelRefundEvents.$inferSelect;

package/dist/schema.js

@@ -199,6 +199,8 @@ export const channelRefundRequests = pgTable("channel_refund_requests", {
     orderId: uuid("order_id").notNull(),
     remoteRefundId: text("remote_refund_id").notNull(),
     amount: integer("amount").notNull(),
+    /** 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"),
     approvedBy: text("approved_by"),
     createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),

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 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> {
@@ -752,6 +754,17 @@ 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<ChannelReturn[]>>;
+    /**
+     * 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.
+     */
+    approveReturn(orgId: string, id: string, context?: StoreReadContext): 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

@@ -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;
@@ -4185,17 +4187,21 @@ export class ChannelConnectorService {
             else
                 refundLines.push({ lineItemId: orderLine.id, quantity });
         }
-        const amount = refundLines.reduce((sum, line) => {
+        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 max = this.options.refundAutoMax ?? order.amountCaptured ?? order.grandTotal;
         const ageOk = Date.now() - store.createdAt.getTime() >= (this.options.newStoreDays ?? 7) * 86_400_000;
-        const auto = clean && amount > 0 && ageOk && amount <= max;
-        const rows = await this.db.insert(channelRefundRequests).values({ organizationId: orgId, storeId: store.id, orderId, remoteRefundId, amount, state: auto ? "approved" : "requested", approvedBy: auto ? requireUserId(actor) : null }).returning();
+        // 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();
         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) {
@@ -4211,7 +4217,8 @@ export class ChannelConnectorService {
     }
     async executeRefund(request, lines, actor) {
         const ordersService = this.services.orders;
-        const result = await ordersService.refundLines(request.orderId, { lines, reason: `Channel refund ${request.remoteRefundId}` }, actor);
+        // 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);
         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();
@@ -4225,7 +4232,7 @@ export class ChannelConnectorService {
         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();
         if (!request)
             return PluginErr("Refund request not found or already handled.", "NOT_FOUND");
-        const lines = await this.refundLinesForRequest(request);
+        const lines = request.lines ?? await this.refundLinesForRequest(request);
         const executed = await this.executeRefund(request, lines, createSystemActor(orgId));
         if (!executed.ok) {
             // Nothing moved: back to `requested`, so the operator can approve again once the cause is fixed.
@@ -4411,7 +4418,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]));
@@ -4431,14 +4440,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,
@@ -4448,6 +4461,86 @@ 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));
+        return Ok(rows);
+    }
+    /**
+     * 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.
+     */
+    async approveReturn(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");
+        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);
+        if (held.status === "requested") {
+            const ordersService = this.services.orders;
+            const refunded = await ordersService.refundLines(held.orderId, { lines: priced.map(({ lineItemId, quantity }) => ({ lineItemId, quantity })), reason: `Return ${held.id}` }, 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)));
+        }
+        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);
+        const booked = await connector.recordRefund(store, exported.remoteOrderId, { lines: storeLines, amount, 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() } });
+        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)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/plugin-channel-connector",
-  "version": "0.74.5",
+  "version": "0.76.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -22,7 +22,7 @@
   "dependencies": {
     "@hono/zod-openapi": "^1.2.2",
     "hono": "^4.12.5",
-    "@porulle/core": "0.74.5"
+    "@porulle/core": "0.76.0"
   },
   "devDependencies": {
     "@types/node": "^24.5.2",

package/src/index.ts

@@ -259,6 +259,7 @@ export type {
   ChannelOrderExport,
   ChannelRefundEvent,
   ChannelRefundRequest,
+  ChannelReturn,
   ConnectedStore,
   StoreHealth,
 } from "./schema.js";
@@ -909,6 +910,21 @@ 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")
+        .handler(async ({ params, orgId, actor, raw }: ChannelRouteContext) => unwrap(await service.approveReturn(orgId, params.id!, { orgId, actor, raw })));
+
+      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() })) }),
+  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("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

@@ -287,6 +287,8 @@ export const channelRefundRequests = pgTable(
     orderId: uuid("order_id").notNull(),
     remoteRefundId: text("remote_refund_id").notNull(),
     amount: integer("amount").notNull(),
+    /** 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"),
     approvedBy: text("approved_by"),
     createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
@@ -326,4 +328,5 @@ 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;
 export type ChannelRefundEvent = typeof channelRefundEvents.$inferSelect;

package/src/service.ts

@@ -94,6 +94,7 @@ import {
   type ChannelCatalogConflict,
   type ChannelOrderExport,
   type ChannelRefundRequest,
+  type ChannelReturn,
   type ConnectedStore,
 } from "./schema.js";
 import type { StoreHealth } from "./schema.js";
@@ -142,6 +143,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";
 
@@ -5327,16 +5330,20 @@ export class ChannelConnectorService {
       if (!orderLine || !Number.isInteger(quantity) || quantity < 1 || quantity > orderLine.quantity - orderLine.refundedQuantity) clean = false;
       else refundLines.push({ lineItemId: orderLine.id, quantity });
     }
-    const amount = refundLines.reduce((sum, line) => {
+    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 max = this.options.refundAutoMax ?? order.amountCaptured ?? order.grandTotal;
     const ageOk = Date.now() - store.createdAt.getTime() >= (this.options.newStoreDays ?? 7) * 86_400_000;
-    const auto = clean && amount > 0 && ageOk && amount <= max;
-    const rows = await this.db.insert(channelRefundRequests).values({ organizationId: orgId, storeId: store.id, orderId, remoteRefundId, amount, state: auto ? "approved" : "requested", approvedBy: auto ? requireUserId(actor) : null }).returning();
+    // 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();
     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) {
@@ -5352,8 +5359,9 @@ 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 }, actor: Actor): Promise<{ ok: boolean; error?: { message: string } }> };
-    const result = await ordersService.refundLines(request.orderId, { lines, reason: `Channel refund ${request.remoteRefundId}` }, actor);
+    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);
     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) });
@@ -5367,7 +5375,7 @@ export class ChannelConnectorService {
   async approveRefund(orgId: string, id: string, actor: { userId: string }): Promise<PluginResult<ChannelRefundRequest>> {
     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();
     if (!request) return PluginErr("Refund request not found or already handled.", "NOT_FOUND");
-    const lines = await this.refundLinesForRequest(request as ChannelRefundRequest);
+    const lines = request.lines ?? await this.refundLinesForRequest(request as ChannelRefundRequest);
     const executed = await this.executeRefund(request as ChannelRefundRequest, lines, createSystemActor(orgId));
     if (!executed.ok) {
       // Nothing moved: back to `requested`, so the operator can approve again once the cause is fixed.
@@ -5577,7 +5585,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]));
@@ -5595,13 +5605,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,
@@ -5611,6 +5625,84 @@ 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<ChannelReturn[]>> {
+    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));
+    return Ok(rows);
+  }
+
+  /**
+   * 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.
+   */
+  async approveReturn(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");
+    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);
+    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 (!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)));
+    }
+
+    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);
+    const booked = await connector.recordRefund(store as ChannelStore, exported.remoteOrderId, { lines: storeLines, amount, 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() } });
+    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)));