platform-types 1.10.727 → 1.10.728

package/dist/return.d.ts

@@ -9,7 +9,14 @@ declare global {
     type ReturnRefundMethod = 'account' | 'cash';
     /** Return planning refusals: invalid selected lines, too many return summaries, or more than 100 transaction items. */
     type ReturnPlanFailureCode = 'RETURN_INVALID_SUBSET' | 'RETURN_LIMIT_REACHED' | 'RETURN_TRANSACTION_TOO_LARGE' | 'UNIT_QUANTITY_NOT_WHOLE' | 'UNIT_QUANTITY_UNREPRESENTABLE';
-    /** Cash handed back in the return transaction, linked to its drawer and compensating account debit. */
+    /**
+     * Cash handed back in the return transaction, linked to its drawer and, for a
+     * named customer, its compensating account debit. On a walk-in return (the
+     * system customer) no `ACCOUNT#` row is written, so `accountId` is only the
+     * payout id the drawer `refund` event carries — it names no ledger row.
+     * `amount` is the full return total for a named customer; on a walk-in return
+     * it is only the part the order had actually been paid (see `owedReduction`).
+     */
     interface ReturnCashRefund {
         amount: number;
         currency: string;
@@ -150,8 +157,20 @@ declare global {
         fiscalAllocation?: ReturnFiscalAllocation;
         /** Absent on legacy rows: account. Cash never retains a customer balance credit. */
         refundMethod?: ReturnRefundMethod;
-        /** Present only when the return paid its full total in cash. */
+        /**
+         * Present only when cash left the drawer: the full total for a named
+         * customer's cash return, the paid part of a walk-in return. A walk-in
+         * return of goods never paid for carries none.
+         */
         cashRefund?: ReturnCashRefund;
+        /**
+         * Walk-in returns only (the system customer). The part of `total` the
+         * order had never been paid: it moved no money and lowered what the order
+         * still owes, so the till collects that much less. `total` equals
+         * `cashRefund.amount` (or 0) plus this. Absent when zero, and on every
+         * named-customer return.
+         */
+        owedReduction?: number;
         reason: ReturnReason;
         notes?: string;
         userId: string;
@@ -591,6 +610,8 @@ declare global {
         refundMethod?: ReturnRefundMethod;
         /** Mirrors the committed cash payout on Return.cashRefund. */
         cashRefund?: ReturnCashRefund;
+        /** Mirrors Return.owedReduction: the unpaid part of a walk-in return, which lowered what the order owes. */
+        owedReduction?: number;
         reason: ReturnReason;
         ncStatus?: ReturnCreditNoteStatus;
         creditNoteId?: string;
@@ -713,7 +734,7 @@ declare global {
      */
     interface CreateReturnRequest {
         mode: 'return';
-        /** Omission credits the customer account. Cash pays the full server-calculated return total; no provider refund. */
+        /** Omission credits the customer account. Cash pays the full server-calculated return total; no provider refund. A walk-in order (the system customer) is always refunded in cash, whatever is sent, but only up to what the order was paid; the unpaid rest lowers what the order still owes. */
         refundMethod?: ReturnRefundMethod;
         /** Client-minted UUID; the idempotency key. A replay returns the original outcome. */
         requestId: string;
@@ -728,7 +749,7 @@ declare global {
         /**
          * Required when the order has a non-empty `linkedPayments` map: the
          * operator acknowledges SINFACTURA does NOT refund or unlink the provider
-         * payment. The return pays by refundMethod (account by default).
+         * payment. The return pays by refundMethod (account by default; always cash on a walk-in order).
          */
         acknowledgeNoProviderRefund?: boolean;
         /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "platform-types",
-	"version": "1.10.727",
+	"version": "1.10.728",
 	"description": "Shared wire and entity contracts for the platform.",
 	"type": "module",
 	"main": "dist/index.js",