@porulle/plugin-channel-connector 0.75.0 → 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/schema.d.ts

@@ -2354,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/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;
@@ -4416,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]));
@@ -4436,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,
@@ -4453,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.75.0",
+  "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.75.0"
+    "@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/schema.ts

@@ -328,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";
 
@@ -5582,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]));
@@ -5600,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,
@@ -5616,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)));