@sixtyninecommerce/admin 0.9.0 → 0.11.0

package/dist/returns/index.d.ts

@@ -0,0 +1,818 @@
+/**
+ * `admin.returns`: the returns (RMA) plugin. The reads (one return, an order's
+ * returns, the list, the open count, what of an order can be returned) and the
+ * plan for settling one (headless W9-47); every non-money step of a return's life
+ * (create, approve, reject, cancel, record a receipt, add a note), the store's
+ * return policy and the RMA numbering (headless W10-27). Settling moves money and
+ * is its own keyed call (`settle`, headless W10-28). Money is in MINOR UNITS
+ * throughout, as everywhere in this SDK.
+ *
+ * Every value set below is the engine's own and grows over time, so each field
+ * that carries one also accepts a string this version does not name: treat an
+ * unknown value as "not available".
+ */
+import { type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/** A return's state: the latest row of its status log. */
+export declare const RETURN_STATES: readonly ["requested", "approved", "rejected", "cancelled", "items_received", "settlement_pending", "settlement_failed", "settled"];
+export type ReturnState = (typeof RETURN_STATES)[number];
+/**
+ * How a return is settled. `refund` gives money back to an original payment.
+ * `store_credit` issues a credit note: on a store with an accounts-receivable
+ * ledger it credits the customer's account, elsewhere it credits the order's
+ * invoice and moves no money. `account` puts the order's settled money on the
+ * customer's account as unapplied cash and makes no refund (an engine released
+ * before 2026-10-10 never answers it).
+ */
+export declare const RETURN_SETTLEMENT_METHODS: readonly ["refund", "store_credit", "account"];
+export type ReturnSettlementMethod = (typeof RETURN_SETTLEMENT_METHODS)[number];
+export interface OrderReturnLine {
+    id: string;
+    returnId: string;
+    orderLineId: string;
+    productVariantId: string;
+    productVariantName: string;
+    productVariantSku: string;
+    requestedQty: number;
+    /** Null until approval; 0 means the line was declined. */
+    approvedQty: number | null;
+    /** Units received back, across every receipt. */
+    receivedQty: number;
+    restockQty: number;
+    writeOffQty: number;
+    restockLocationId: string | null;
+    /** `damaged`, `defective`, `wrong_item`, `not_as_described`, `arrived_late`, `no_longer_needed`, `order_error`, `other`. */
+    reasonCode: string;
+    reasonNote: string | null;
+    /** The order line's prorated unit price incl. tax, rounded per unit. Display only. */
+    unitPriceWithTax: number;
+    /**
+     * The same price before per-unit rounding; null for returns requested before
+     * it was recorded. Multiply by a quantity and round ONCE to estimate a line.
+     */
+    unitPriceWithTaxUnrounded: number | null;
+    /** What the line refunds; null until approved. */
+    refundAmount: number | null;
+    /**
+     * This line's part of {@link OrderReturnDetail.refundEstimate}: its `refundAmount` once
+     * approved, else the default for its approved (or requested) units. Only `get` and `list`
+     * select it; absent from an engine released before 2026-10-11.
+     */
+    refundEstimate?: number;
+    createdAt: string;
+    updatedAt: string;
+}
+/** One row of a return's status log. */
+export interface OrderReturnStatusLogEntry {
+    state: ReturnState | (string & {});
+    /** `customer`, `admin` or `system`. */
+    actor: string;
+    actorUserId: string | null;
+    reason: string | null;
+    createdAt: string;
+}
+export interface OrderReturn {
+    id: string;
+    /** The human-facing RMA code, e.g. `RMA-000042`. */
+    code: string;
+    channelId: string;
+    orderId: string;
+    orderCode: string;
+    customerId: string;
+    currencyCode: string;
+    state: ReturnState | (string & {});
+    /** `customer` or `admin`. */
+    initiator: string;
+    customerNote: string | null;
+    adminNote: string | null;
+    preferredSettlementMethod: ReturnSettlementMethod | (string & {}) | null;
+    /** The method it was settled with; null until settled. */
+    settlementMethod: ReturnSettlementMethod | (string & {}) | null;
+    /** Shipping refunded on top of the lines. */
+    shippingRefundAmount: number;
+    /** What was settled; null until settled. */
+    settledAmount: number | null;
+    refundId: string | null;
+    creditNoteId: string | null;
+    creditNoteNumber: string | null;
+    requestedAt: string;
+    resolvedAt: string | null;
+    lines: OrderReturnLine[];
+    createdAt: string;
+    updatedAt: string;
+    /**
+     * The invoice correction credit notes that already credited this return's goods, when it was
+     * closed without money ({@link ReturnsModule.closeAlreadyCredited}); null for any other return.
+     * Such a return reads `settled`, `settledAmount` 0, with no `settlementMethod`, refund or credit
+     * note of its own. Absent from an engine released before it.
+     */
+    alreadyCreditedBy?: ReturnCoveringCreditNote[] | null;
+}
+/** An invoice correction credit note that already credited a return's goods. */
+export interface ReturnCoveringCreditNote {
+    creditNoteId: string;
+    /** The credit note's number, e.g. `CN-00053`. */
+    creditNoteNumber: string;
+    /** `RETAIL`: a credit note on the order's invoice. `AR`: one on the accounts-receivable ledger. */
+    ledger: 'RETAIL' | 'AR' | (string & {});
+}
+/**
+ * Why a return may not be closed as already credited: `NOT_SETTLEABLE` (it cannot be settled
+ * now, see `blockedBy`), `NOT_CREDITED` (no correction credit note names every approved line) or
+ * `MONEY_LEFT` (something is still left to settle the goods with: settle it).
+ */
+export type ReturnAlreadyCreditedUnavailableReason = 'NOT_SETTLEABLE' | 'NOT_CREDITED' | 'MONEY_LEFT';
+/**
+ * A step of a return's life, as `allowedActions` names it. `CLOSE_CREDITED` is
+ * {@link ReturnsModule.closeAlreadyCredited}: closing a return invoice corrections already
+ * credited in full, moving no money.
+ */
+export declare const RETURN_ACTIONS: readonly ["APPROVE", "REJECT", "RECORD_RECEIPT", "CANCEL", "SETTLE", "CLOSE_CREDITED"];
+export type ReturnAction = (typeof RETURN_ACTIONS)[number];
+/** Whether one step of a return is open now. */
+export interface ReturnActionAvailability {
+    /** Treat a step this version does not name as one to leave alone. */
+    action: ReturnAction | (string & {});
+    allowed: boolean;
+    /**
+     * Null exactly when `allowed`. `NOT_PERMITTED` (no `UpdateOrderReturn`), `STATE`,
+     * `RECEIPT_RECORDED` (cancel: goods already came back), `NOTHING_TO_RECEIVE` (receive: every
+     * approved unit is back), for `SETTLE` the settlement plan's `blockedBy`, for `CLOSE_CREDITED`
+     * the plan's `alreadyCredited.reasonCode`. The set grows:
+     * read an unknown value as "not offered".
+     */
+    reasonCode: string | null;
+}
+/** The customer a return is for, as the store holds them (core's `Customer`, a selection of it). */
+export interface OrderReturnCustomer {
+    id: string;
+    firstName: string;
+    lastName: string;
+    emailAddress: string;
+    /** Only what a display name reads: the company of the default addresses. */
+    addresses: Array<{
+        company: string | null;
+        defaultBillingAddress: boolean;
+        defaultShippingAddress: boolean;
+    }>;
+}
+/**
+ * What `get` and `list` add to a return. Each is absent from an engine released before
+ * 2026-10-11 (the calls then retry once without them, and keep doing so for this client).
+ */
+export interface OrderReturnReadFields {
+    /**
+     * What the return refunds by default: each line's approved `refundAmount`, or before approval
+     * its unit price times the requested units, rounded once per line; shipping excluded. An
+     * ESTIMATE: approval holds a line an invoice correction credited to what is left of it, and a
+     * settlement may state an override and a shipping refund (`settlementOptions.defaultAmount` is
+     * what it settles by default).
+     */
+    refundEstimate?: number;
+    /**
+     * The customer, from this store's own rows, read with the return (no second request). Null
+     * when the store no longer holds them, and for a caller holding neither `ReadCustomer` nor
+     * `ReadOrder`.
+     */
+    customer?: OrderReturnCustomer | null;
+}
+/** {@link OrderReturn} with its status log, newest first: what `get` answers. */
+export interface OrderReturnDetail extends OrderReturn, OrderReturnReadFields {
+    history: OrderReturnStatusLogEntry[];
+    /**
+     * Which steps the return offers now (one entry per step). The PLAN: every write judges again
+     * with the same rule, so a step offered here can still be refused when something changed in
+     * between (`RETURN_STATE_INVALID`). Absent from an engine released before 2026-10-11.
+     */
+    allowedActions?: ReturnActionAvailability[];
+}
+/** One row of `list`. */
+export interface OrderReturnListItem extends OrderReturn, OrderReturnReadFields {
+}
+/** A page of returns, newest first. */
+export interface OrderReturnList {
+    items: OrderReturnListItem[];
+    /** Every return the filter matches, not only this page. */
+    totalItems: number;
+}
+/** Which returns `list` answers. Every field narrows; none is required. */
+export interface ReturnListFilter {
+    /** At most 100; 25 when left out. */
+    take?: number;
+    skip?: number;
+    /** The CURRENT state. */
+    state?: ReturnState;
+    customerId?: string;
+    orderId?: string;
+    /** A case-insensitive part of the RMA code. */
+    code?: string;
+}
+/** `damaged`, `defective`, `wrong_item`, `not_as_described`, `arrived_late`, `no_longer_needed`, `order_error`, `other`. */
+export type ReturnReasonCode = 'damaged' | 'defective' | 'wrong_item' | 'not_as_described' | 'arrived_late' | 'no_longer_needed' | 'order_error' | 'other';
+export interface CreateReturnInput {
+    orderId: string;
+    lines: Array<{
+        orderLineId: string;
+        quantity: number;
+        reasonCode: ReturnReasonCode;
+        reasonNote?: string | null;
+    }>;
+    /** The customer's own words. Refused `CUSTOMER_ERASED` for a customer the platform erased. */
+    customerNote?: string | null;
+    preferredSettlementMethod?: ReturnSettlementMethod | null;
+    /** Create it after the store's return window ended. The quantity caps always apply. */
+    overrideWindow?: boolean;
+}
+export interface ApproveReturnInput {
+    /** One decision per line; a line left out is declined (0). */
+    lines: Array<{
+        returnLineId: string;
+        /** 0 declines the line; at most the requested quantity. */
+        approvedQty: number;
+        /** What the line refunds, minor units; the default arithmetic when left out. */
+        refundAmount?: number;
+    }>;
+    /** Appended to the merchant's internal note. */
+    adminNote?: string | null;
+}
+export interface RecordReturnReceiptInput {
+    lines: Array<{
+        returnLineId: string;
+        /** Units that came back in this receipt, 1 or more. */
+        quantity: number;
+        /** `restock` puts them back on stock at `stockLocationId`; `write_off` touches no stock. */
+        disposition: 'restock' | 'write_off';
+        /** For a restock: the store's default restock location when left out. */
+        stockLocationId?: string;
+    }>;
+}
+/** How {@link ReturnsModule.settle} settles a return. Money in minor units. */
+export interface SettleReturnInput {
+    /**
+     * `refund` gives the money back to a settled payment of the order; `store_credit` issues a
+     * credit note (on a store that keeps customer accounts it credits the account, else it credits
+     * the order's invoice and moves no money); `account` puts the money on the customer's account
+     * (unapplied cash), making no refund.
+     */
+    method: ReturnSettlementMethod;
+    /** `refund` only: the payment to refund. Left out, the engine picks a settled one that can carry it. */
+    paymentId?: string | null;
+    /**
+     * What the return settles instead of its approved line total (`settlementOptions.defaultAmount`),
+     * before shipping. Left out, the engine's own figure.
+     */
+    amountOverride?: number | null;
+    /**
+     * Shipping refunded on top. Left out, the figure an earlier failed attempt stated (0 when none
+     * did); state it, 0 included, once a correction credited shipping (`settlementOptions.shippingCeiling`).
+     */
+    shippingRefundAmount?: number | null;
+    /** Recorded on the refund and the return's history. */
+    reason?: string | null;
+}
+/** The store's RMA code format: `{prefix}{year}{number}{suffix}`, e.g. `RMA-000042`. */
+export interface ReturnNumberingConfig {
+    prefix: string;
+    suffix: string;
+    /** How many digits the number is padded to, 3 to 8. */
+    digits: number;
+    /** `none`, `short` (`26`) or `full` (`2026`). */
+    yearFormat: string;
+    /** Restart the count each year (only with a year in the code). */
+    yearReset: boolean;
+}
+/** A PATCH: a field left out keeps its value. */
+export interface UpdateReturnNumberingConfigInput {
+    prefix?: string;
+    suffix?: string;
+    /** Clamped to 3..8. */
+    digits?: number;
+    /** `none`, `short` or `full`; anything else is refused `NUMBERING_YEAR_FORMAT_INVALID`. */
+    yearFormat?: string;
+    yearReset?: boolean;
+}
+/**
+ * The active store's OWN return policy (its channel's fields). A store that inherits
+ * `settings.returns` from its organization is governed by the organization's values instead;
+ * those are the settings resolver's (multi-region), not this read's.
+ */
+export interface ReturnsSettings {
+    /** The store these are the settings of (its channel id). */
+    channelId: string;
+    /** Customers may request returns on the storefront. Staff can always create them. */
+    returnsEnabled: boolean;
+    /** Days after delivery (else shipping, else placement) a customer may request a return. */
+    returnWindowDays: number;
+    /** A customer's request is approved on arrival, in full. */
+    returnsAutoApprove: boolean;
+    /** An approved return is settled only after its goods are received. */
+    returnsRequireReceiptBeforeSettle: boolean;
+    /** Where restocked goods go when a receipt names no location; null when none is set. */
+    returnsDefaultRestockLocationId: string | null;
+}
+/**
+ * What an invoice correction's credit note already credited on an order line. A unit it
+ * credited whole is no longer returnable; a lower amount (a price correction on goods the
+ * customer keeps) lowers what each remaining unit refunds. A head can say "1 already credited
+ * on CN-00053" from it.
+ */
+export interface ReturnLineCorrectionCredit {
+    orderLineId: string;
+    creditNoteId: string;
+    /** The credit note's number, e.g. `CN-00053`. */
+    creditNoteNumber: string;
+    /** `RETAIL`: a credit note on the order's invoice. `AR`: one on the accounts-receivable ledger. */
+    ledger: 'RETAIL' | 'AR' | (string & {});
+    /** Units it credited whole on the line: no longer returnable. */
+    quantity: number;
+    /** What it credited on the line, minor units incl. tax: whole units and price corrections. */
+    amount: number;
+}
+/** One order line and what of it can still be returned. */
+export interface ReturnableOrderLine {
+    orderLineId: string;
+    productVariantId: string;
+    productVariantName: string;
+    productVariantSku: string;
+    /** Units shipped or delivered. */
+    fulfilledQty: number;
+    /**
+     * `fulfilledQty` less the units other open returns already claim, and never more than the
+     * billed units an invoice correction did not credit whole (`creditedQty`).
+     */
+    returnableQty: number;
+    /**
+     * Units an invoice correction credited whole on the line; 0 when none did. Absent from an
+     * engine released before 2026-10-09, which does not subtract them.
+     */
+    creditedQty?: number;
+    /** Every invoice correction credit note that names the line; empty when none does. Absent as above. */
+    correctionCredits?: ReturnLineCorrectionCredit[];
+    /** What one returned unit refunds: the line's price, or what a price correction left of it. */
+    unitPriceWithTax: number;
+    unitPriceWithTaxUnrounded: number;
+}
+export interface ReturnEligibility {
+    orderId: string;
+    /** False only when nothing is returnable: an admin may return outside the window. */
+    eligible: boolean;
+    /** Why not, when not eligible. */
+    reason: string | null;
+    /** ISO-8601 with offset; null when the store sets no window. */
+    returnWindowEndsAt: string | null;
+    /** Lines with a fulfilled quantity only. */
+    lines: ReturnableOrderLine[];
+}
+/** Why a return cannot be settled now, in the order the engine checks them. */
+export declare const RETURN_SETTLEMENT_BLOCKERS: readonly ["OUTCOME_UNKNOWN", "ALREADY_SETTLED", "IN_PROGRESS", "RECEIPT_REQUIRED", "STATE"];
+/**
+ * - `OUTCOME_UNKNOWN`: the refund it waits on reached the provider and was never
+ *   confirmed. Record the provider's answer first (`reconcileRefundOutcome`):
+ *   made completes the return, not made lets it be settled again.
+ * - `ALREADY_SETTLED`: settled, or settled by a credit note.
+ * - `IN_PROGRESS`: a refund is on its way and settles the return when the
+ *   provider confirms it.
+ * - `RECEIPT_REQUIRED`: approved, and the store requires the goods received first.
+ * - `STATE`: requested, rejected or cancelled.
+ */
+export type ReturnSettlementBlocker = (typeof RETURN_SETTLEMENT_BLOCKERS)[number];
+/**
+ * - `NO_REFUNDABLE_PAYMENT`: no settled payment can still give money back (net
+ *   terms, everything refunded, reserved by a refund of unknown outcome, or
+ *   moved to the customer's account).
+ * - `REFUND_ORPHAN_EXISTS`: a refund of the invoiced order stands that no credit
+ *   note names; another refund could pay the same money back twice.
+ */
+export type ReturnRefundUnavailableReason = 'NO_REFUNDABLE_PAYMENT' | 'REFUND_ORPHAN_EXISTS';
+/**
+ * - `AR`: the store keeps an accounts-receivable ledger; the credit note credits
+ *   the customer's account, which is money.
+ * - `RETAIL`: the credit note credits the order's invoice and moves no money.
+ */
+export type ReturnCreditNoteLedger = 'AR' | 'RETAIL';
+/**
+ * - `ISSUER_UNAVAILABLE`: the server runs without the plugin that issues it.
+ * - `CURRENCY_MISMATCH` (`AR`): the order is not in the store's default currency.
+ * - `NO_CREDITABLE_INVOICE` (`RETAIL`): the order has no live invoice to credit.
+ * - `REFUND_ORPHAN_EXISTS` (`AR`): as for the refund.
+ */
+export type ReturnCreditNoteUnavailableReason = 'ISSUER_UNAVAILABLE' | 'CURRENCY_MISMATCH' | 'NO_CREDITABLE_INVOICE' | 'REFUND_ORPHAN_EXISTS';
+/** A settled payment a refund may name, with what it can still give back. */
+export interface ReturnSettlementPayment {
+    paymentId: string;
+    method: string;
+    /** As the platform's refund position counts it. */
+    refundable: number;
+}
+/** Putting the return's money on the customer's account (`account`). */
+export interface ReturnSettlementAccountOption {
+    available: boolean;
+    /**
+     * Null exactly when `available`. The account's own answer (`AR_LEDGER_NOT_ENABLED`: the store
+     * keeps no accounts-receivable ledger; `AR_ACCOUNT_REQUIRED`: the customer has no credit
+     * account; `AR_ACCOUNT_IN_ERP`; `AR_ORDER_ALREADY_INVOICED`; `ACCOUNT_CREDIT_NO_CUSTOMER`), the
+     * store credit's (`STORE_CREDIT_INVOICE_FIRST`, `STORE_CREDIT_CUSTOMER_ANONYMOUS`,
+     * `STORED_VALUE_ACCOUNT_BLOCKED`, `STORED_VALUE_OWNER_REQUIRED`),
+     * `ACCOUNT_CREDIT_NOTHING_OVERPAID` (the settled payments hold nothing more) or
+     * `REFUND_ORPHAN_EXISTS`.
+     */
+    reasonCode: string | null;
+    /** The engine's sentence for `reasonCode`; null when available. */
+    message: string | null;
+    /**
+     * What the order's settled payments still hold, minor units: the most a settlement to the
+     * account may state, shipping included (above it `RETURN_ACCOUNT_CREDIT_EXCEEDS_HELD`).
+     */
+    held: number;
+    /**
+     * Where the money lands, the store's ONE book (incentives sprint 8): `AR` (the customer's
+     * account), `STORE_CREDIT` (the customer's store credit: on an invoiced order the return's credit
+     * note is issued first, and the wallet takes exactly what it credits) or `NONE`. In a
+     * store-credit store an order with no invoice yet, in a store that issues invoices, is refused
+     * `STORE_CREDIT_INVOICE_FIRST`. Absent from an engine before it (read it as the account's).
+     */
+    book?: 'AR' | 'STORE_CREDIT' | 'NONE' | (string & {}) | null;
+}
+export interface ReturnSettlementOptions {
+    returnId: string;
+    currencyCode: string;
+    settleable: boolean;
+    /** Null exactly when `settleable`. */
+    blockedBy: ReturnSettlementBlocker | (string & {}) | null;
+    refund: {
+        available: boolean;
+        /** Null exactly when `available`. */
+        reasonCode: ReturnRefundUnavailableReason | (string & {}) | null;
+        /** Empty when not available. */
+        payments: ReturnSettlementPayment[];
+    };
+    creditNote: {
+        available: boolean;
+        ledger: ReturnCreditNoteLedger | (string & {});
+        /** Null exactly when `available`. */
+        reasonCode: ReturnCreditNoteUnavailableReason | (string & {}) | null;
+        /** `RETAIL` only: the invoice it would credit, when known. */
+        invoiceNumber: string | null;
+    };
+    /** The credit note when asked for or when no refund is possible, and it is available; else `refund`. */
+    initialMethod: ReturnSettlementMethod | (string & {});
+    /**
+     * The approved line total: what a settlement without an override settles, before shipping. A
+     * line an invoice correction already credited counts only what is left of it.
+     */
+    defaultAmount: number;
+    /**
+     * The most `amountOverride` may state when an invoice correction already credited goods of
+     * this return (then equal to `defaultAmount`); null when none did. Above it the settlement is
+     * refused `RETURN_AMOUNT_ALREADY_CREDITED`. Absent from an engine released before 2026-10-09.
+     */
+    amountCeiling?: number | null;
+    /** What invoice corrections already credited on the return's approved order lines. Absent as above. */
+    correctionCredits?: ReturnLineCorrectionCredit[];
+    /**
+     * The most `shippingRefundAmount` may state when an invoice correction already credited the
+     * order's shipping: what the order charged for shipping, less what corrections credited and
+     * other returns refunded of it. Null when no correction credited shipping. Above it the
+     * settlement is refused `RETURN_SHIPPING_ALREADY_CREDITED`. Absent from an engine released
+     * before this field.
+     */
+    shippingCeiling?: number | null;
+    /**
+     * Whether "Close — already credited on CN-…" is open (ruling U15): invoice corrections already
+     * credited all of the return's goods, so nothing is left to settle them with, and
+     * {@link ReturnsModule.closeAlreadyCredited} closes it without money. Absent from an engine
+     * released before it (read it as not available).
+     */
+    alreadyCredited?: {
+        available: boolean;
+        /** Null exactly when `available`. */
+        reasonCode: ReturnAlreadyCreditedUnavailableReason | (string & {}) | null;
+        /** The credit notes that covered the goods, by number. Empty when not available. */
+        creditNotes: ReturnCoveringCreditNote[];
+    };
+    /**
+     * Putting the money on the customer's account. Absent from an engine released before
+     * 2026-10-10 (the method does not exist there).
+     */
+    account?: ReturnSettlementAccountOption;
+}
+export declare const RETURN_QUERY = "\n  query SdkOrderReturn($id: ID!) {\n    orderReturn(id: $id) {\n      \n    id\n    code\n    channelId\n    orderId\n    orderCode\n    customerId\n    currencyCode\n    state\n    initiator\n    customerNote\n    adminNote\n    preferredSettlementMethod\n    settlementMethod\n    shippingRefundAmount\n    settledAmount\n    refundId\n    creditNoteId\n    creditNoteNumber\n    requestedAt\n    resolvedAt\n    createdAt\n    updatedAt\n    lines {\n      id\n      returnId\n      orderLineId\n      productVariantId\n      productVariantName\n      productVariantSku\n      requestedQty\n      approvedQty\n      receivedQty\n      restockQty\n      writeOffQty\n      restockLocationId\n      reasonCode\n      reasonNote\n      unitPriceWithTax\n      unitPriceWithTaxUnrounded\n      refundAmount\n      createdAt\n      updatedAt\n    }\n\n      alreadyCreditedBy {\n        \n        creditNoteId\n        creditNoteNumber\n        ledger\n\n      }\n      \n      history {\n        state\n        actor\n        actorUserId\n        reason\n        createdAt\n      }\n\n      \n    refundEstimate\n    customer {\n      id\n      firstName\n      lastName\n      emailAddress\n      addresses {\n        company\n        defaultBillingAddress\n        defaultShippingAddress\n      }\n    }\n    lines {\n      refundEstimate\n    }\n\n      allowedActions {\n        action\n        allowed\n        reasonCode\n      }\n    }\n  }\n";
+/**
+ * {@link RETURN_QUERY} for an engine with `alreadyCreditedBy` (ruling U15) but released before
+ * `allowedActions`, `refundEstimate` and `customer` (2026-10-11).
+ */
+export declare const RETURN_QUERY_BEFORE_ACTIONS = "\n  query SdkOrderReturnBeforeActions($id: ID!) {\n    orderReturn(id: $id) {\n      \n    id\n    code\n    channelId\n    orderId\n    orderCode\n    customerId\n    currencyCode\n    state\n    initiator\n    customerNote\n    adminNote\n    preferredSettlementMethod\n    settlementMethod\n    shippingRefundAmount\n    settledAmount\n    refundId\n    creditNoteId\n    creditNoteNumber\n    requestedAt\n    resolvedAt\n    createdAt\n    updatedAt\n    lines {\n      id\n      returnId\n      orderLineId\n      productVariantId\n      productVariantName\n      productVariantSku\n      requestedQty\n      approvedQty\n      receivedQty\n      restockQty\n      writeOffQty\n      restockLocationId\n      reasonCode\n      reasonNote\n      unitPriceWithTax\n      unitPriceWithTaxUnrounded\n      refundAmount\n      createdAt\n      updatedAt\n    }\n\n      alreadyCreditedBy {\n        \n        creditNoteId\n        creditNoteNumber\n        ledger\n\n      }\n      \n      history {\n        state\n        actor\n        actorUserId\n        reason\n        createdAt\n      }\n\n    }\n  }\n";
+/** {@link RETURN_QUERY} for an engine released before `alreadyCreditedBy` (ruling U15). */
+export declare const RETURN_QUERY_LEGACY = "\n  query SdkOrderReturnLegacy($id: ID!) {\n    orderReturn(id: $id) {\n      \n    id\n    code\n    channelId\n    orderId\n    orderCode\n    customerId\n    currencyCode\n    state\n    initiator\n    customerNote\n    adminNote\n    preferredSettlementMethod\n    settlementMethod\n    shippingRefundAmount\n    settledAmount\n    refundId\n    creditNoteId\n    creditNoteNumber\n    requestedAt\n    resolvedAt\n    createdAt\n    updatedAt\n    lines {\n      id\n      returnId\n      orderLineId\n      productVariantId\n      productVariantName\n      productVariantSku\n      requestedQty\n      approvedQty\n      receivedQty\n      restockQty\n      writeOffQty\n      restockLocationId\n      reasonCode\n      reasonNote\n      unitPriceWithTax\n      unitPriceWithTaxUnrounded\n      refundAmount\n      createdAt\n      updatedAt\n    }\n\n      \n      history {\n        state\n        actor\n        actorUserId\n        reason\n        createdAt\n      }\n\n    }\n  }\n";
+export declare const RETURNS_LIST_QUERY = "\n  query SdkOrderReturns($options: OrderReturnListOptions) {\n    orderReturns(options: $options) {\n      items {\n        \n    id\n    code\n    channelId\n    orderId\n    orderCode\n    customerId\n    currencyCode\n    state\n    initiator\n    customerNote\n    adminNote\n    preferredSettlementMethod\n    settlementMethod\n    shippingRefundAmount\n    settledAmount\n    refundId\n    creditNoteId\n    creditNoteNumber\n    requestedAt\n    resolvedAt\n    createdAt\n    updatedAt\n    lines {\n      id\n      returnId\n      orderLineId\n      productVariantId\n      productVariantName\n      productVariantSku\n      requestedQty\n      approvedQty\n      receivedQty\n      restockQty\n      writeOffQty\n      restockLocationId\n      reasonCode\n      reasonNote\n      unitPriceWithTax\n      unitPriceWithTaxUnrounded\n      refundAmount\n      createdAt\n      updatedAt\n    }\n\n        alreadyCreditedBy {\n          \n        creditNoteId\n        creditNoteNumber\n        ledger\n\n        }\n        \n    refundEstimate\n    customer {\n      id\n      firstName\n      lastName\n      emailAddress\n      addresses {\n        company\n        defaultBillingAddress\n        defaultShippingAddress\n      }\n    }\n    lines {\n      refundEstimate\n    }\n\n      }\n      totalItems\n    }\n  }\n";
+/** {@link RETURNS_LIST_QUERY} for an engine with `alreadyCreditedBy` but released before 2026-10-11. */
+export declare const RETURNS_LIST_QUERY_BEFORE_ACTIONS = "\n  query SdkOrderReturnsBeforeActions($options: OrderReturnListOptions) {\n    orderReturns(options: $options) {\n      items {\n        \n    id\n    code\n    channelId\n    orderId\n    orderCode\n    customerId\n    currencyCode\n    state\n    initiator\n    customerNote\n    adminNote\n    preferredSettlementMethod\n    settlementMethod\n    shippingRefundAmount\n    settledAmount\n    refundId\n    creditNoteId\n    creditNoteNumber\n    requestedAt\n    resolvedAt\n    createdAt\n    updatedAt\n    lines {\n      id\n      returnId\n      orderLineId\n      productVariantId\n      productVariantName\n      productVariantSku\n      requestedQty\n      approvedQty\n      receivedQty\n      restockQty\n      writeOffQty\n      restockLocationId\n      reasonCode\n      reasonNote\n      unitPriceWithTax\n      unitPriceWithTaxUnrounded\n      refundAmount\n      createdAt\n      updatedAt\n    }\n\n        alreadyCreditedBy {\n          \n        creditNoteId\n        creditNoteNumber\n        ledger\n\n        }\n      }\n      totalItems\n    }\n  }\n";
+/** {@link RETURNS_LIST_QUERY} for an engine released before `alreadyCreditedBy`. */
+export declare const RETURNS_LIST_QUERY_LEGACY = "\n  query SdkOrderReturnsLegacy($options: OrderReturnListOptions) {\n    orderReturns(options: $options) {\n      items {\n        \n    id\n    code\n    channelId\n    orderId\n    orderCode\n    customerId\n    currencyCode\n    state\n    initiator\n    customerNote\n    adminNote\n    preferredSettlementMethod\n    settlementMethod\n    shippingRefundAmount\n    settledAmount\n    refundId\n    creditNoteId\n    creditNoteNumber\n    requestedAt\n    resolvedAt\n    createdAt\n    updatedAt\n    lines {\n      id\n      returnId\n      orderLineId\n      productVariantId\n      productVariantName\n      productVariantSku\n      requestedQty\n      approvedQty\n      receivedQty\n      restockQty\n      writeOffQty\n      restockLocationId\n      reasonCode\n      reasonNote\n      unitPriceWithTax\n      unitPriceWithTaxUnrounded\n      refundAmount\n      createdAt\n      updatedAt\n    }\n\n      }\n      totalItems\n    }\n  }\n";
+export declare const OPEN_RETURNS_COUNT_QUERY = "\n  query SdkOpenReturnsCount {\n    orderReturns(options: { take: 1, state: requested }) {\n      totalItems\n    }\n  }\n";
+export declare const CREATE_RETURN_MUTATION = "\n  mutation SdkCreateReturn($input: CreateReturnInput!) {\n    createReturn(input: $input) {\n      \n    id\n    code\n    channelId\n    orderId\n    orderCode\n    customerId\n    currencyCode\n    state\n    initiator\n    customerNote\n    adminNote\n    preferredSettlementMethod\n    settlementMethod\n    shippingRefundAmount\n    settledAmount\n    refundId\n    creditNoteId\n    creditNoteNumber\n    requestedAt\n    resolvedAt\n    createdAt\n    updatedAt\n    lines {\n      id\n      returnId\n      orderLineId\n      productVariantId\n      productVariantName\n      productVariantSku\n      requestedQty\n      approvedQty\n      receivedQty\n      restockQty\n      writeOffQty\n      restockLocationId\n      reasonCode\n      reasonNote\n      unitPriceWithTax\n      unitPriceWithTaxUnrounded\n      refundAmount\n      createdAt\n      updatedAt\n    }\n\n    }\n  }\n";
+export declare const APPROVE_RETURN_MUTATION = "\n  mutation SdkApproveReturn($input: ApproveReturnInput!) {\n    approveReturn(input: $input) {\n      \n    id\n    code\n    channelId\n    orderId\n    orderCode\n    customerId\n    currencyCode\n    state\n    initiator\n    customerNote\n    adminNote\n    preferredSettlementMethod\n    settlementMethod\n    shippingRefundAmount\n    settledAmount\n    refundId\n    creditNoteId\n    creditNoteNumber\n    requestedAt\n    resolvedAt\n    createdAt\n    updatedAt\n    lines {\n      id\n      returnId\n      orderLineId\n      productVariantId\n      productVariantName\n      productVariantSku\n      requestedQty\n      approvedQty\n      receivedQty\n      restockQty\n      writeOffQty\n      restockLocationId\n      reasonCode\n      reasonNote\n      unitPriceWithTax\n      unitPriceWithTaxUnrounded\n      refundAmount\n      createdAt\n      updatedAt\n    }\n\n    }\n  }\n";
+export declare const REJECT_RETURN_MUTATION = "\n  mutation SdkRejectReturn($id: ID!, $reason: String!) {\n    rejectReturn(id: $id, reason: $reason) {\n      \n    id\n    code\n    channelId\n    orderId\n    orderCode\n    customerId\n    currencyCode\n    state\n    initiator\n    customerNote\n    adminNote\n    preferredSettlementMethod\n    settlementMethod\n    shippingRefundAmount\n    settledAmount\n    refundId\n    creditNoteId\n    creditNoteNumber\n    requestedAt\n    resolvedAt\n    createdAt\n    updatedAt\n    lines {\n      id\n      returnId\n      orderLineId\n      productVariantId\n      productVariantName\n      productVariantSku\n      requestedQty\n      approvedQty\n      receivedQty\n      restockQty\n      writeOffQty\n      restockLocationId\n      reasonCode\n      reasonNote\n      unitPriceWithTax\n      unitPriceWithTaxUnrounded\n      refundAmount\n      createdAt\n      updatedAt\n    }\n\n    }\n  }\n";
+export declare const CANCEL_RETURN_MUTATION = "\n  mutation SdkCancelReturn($id: ID!, $reason: String) {\n    cancelReturn(id: $id, reason: $reason) {\n      \n    id\n    code\n    channelId\n    orderId\n    orderCode\n    customerId\n    currencyCode\n    state\n    initiator\n    customerNote\n    adminNote\n    preferredSettlementMethod\n    settlementMethod\n    shippingRefundAmount\n    settledAmount\n    refundId\n    creditNoteId\n    creditNoteNumber\n    requestedAt\n    resolvedAt\n    createdAt\n    updatedAt\n    lines {\n      id\n      returnId\n      orderLineId\n      productVariantId\n      productVariantName\n      productVariantSku\n      requestedQty\n      approvedQty\n      receivedQty\n      restockQty\n      writeOffQty\n      restockLocationId\n      reasonCode\n      reasonNote\n      unitPriceWithTax\n      unitPriceWithTaxUnrounded\n      refundAmount\n      createdAt\n      updatedAt\n    }\n\n    }\n  }\n";
+export declare const RECORD_RETURN_RECEIPT_MUTATION = "\n  mutation SdkRecordReturnReceipt($input: RecordReturnReceiptInput!) {\n    recordReturnReceipt(input: $input) {\n      \n    id\n    code\n    channelId\n    orderId\n    orderCode\n    customerId\n    currencyCode\n    state\n    initiator\n    customerNote\n    adminNote\n    preferredSettlementMethod\n    settlementMethod\n    shippingRefundAmount\n    settledAmount\n    refundId\n    creditNoteId\n    creditNoteNumber\n    requestedAt\n    resolvedAt\n    createdAt\n    updatedAt\n    lines {\n      id\n      returnId\n      orderLineId\n      productVariantId\n      productVariantName\n      productVariantSku\n      requestedQty\n      approvedQty\n      receivedQty\n      restockQty\n      writeOffQty\n      restockLocationId\n      reasonCode\n      reasonNote\n      unitPriceWithTax\n      unitPriceWithTaxUnrounded\n      refundAmount\n      createdAt\n      updatedAt\n    }\n\n    }\n  }\n";
+export declare const SETTLE_RETURN_MUTATION = "\n  mutation SdkSettleReturn($input: SettleReturnInput!, $idempotencyKey: String) {\n    settleReturn(input: $input, idempotencyKey: $idempotencyKey) {\n      \n    id\n    code\n    channelId\n    orderId\n    orderCode\n    customerId\n    currencyCode\n    state\n    initiator\n    customerNote\n    adminNote\n    preferredSettlementMethod\n    settlementMethod\n    shippingRefundAmount\n    settledAmount\n    refundId\n    creditNoteId\n    creditNoteNumber\n    requestedAt\n    resolvedAt\n    createdAt\n    updatedAt\n    lines {\n      id\n      returnId\n      orderLineId\n      productVariantId\n      productVariantName\n      productVariantSku\n      requestedQty\n      approvedQty\n      receivedQty\n      restockQty\n      writeOffQty\n      restockLocationId\n      reasonCode\n      reasonNote\n      unitPriceWithTax\n      unitPriceWithTaxUnrounded\n      refundAmount\n      createdAt\n      updatedAt\n    }\n\n      \n      history {\n        state\n        actor\n        actorUserId\n        reason\n        createdAt\n      }\n\n    }\n  }\n";
+export declare const ADD_RETURN_NOTE_MUTATION = "\n  mutation SdkAddReturnNote($id: ID!, $note: String!) {\n    addReturnNote(id: $id, note: $note) {\n      \n    id\n    code\n    channelId\n    orderId\n    orderCode\n    customerId\n    currencyCode\n    state\n    initiator\n    customerNote\n    adminNote\n    preferredSettlementMethod\n    settlementMethod\n    shippingRefundAmount\n    settledAmount\n    refundId\n    creditNoteId\n    creditNoteNumber\n    requestedAt\n    resolvedAt\n    createdAt\n    updatedAt\n    lines {\n      id\n      returnId\n      orderLineId\n      productVariantId\n      productVariantName\n      productVariantSku\n      requestedQty\n      approvedQty\n      receivedQty\n      restockQty\n      writeOffQty\n      restockLocationId\n      reasonCode\n      reasonNote\n      unitPriceWithTax\n      unitPriceWithTaxUnrounded\n      refundAmount\n      createdAt\n      updatedAt\n    }\n\n    }\n  }\n";
+export declare const RETURN_NUMBERING_QUERY = "\n  query SdkReturnNumberingConfig {\n    returnNumberingConfig {\n      \n      prefix\n      suffix\n      digits\n      yearFormat\n      yearReset\n\n    }\n  }\n";
+export declare const UPDATE_RETURN_NUMBERING_MUTATION = "\n  mutation SdkUpdateReturnNumberingConfig($input: UpdateReturnNumberingConfigInput!) {\n    updateReturnNumberingConfig(input: $input) {\n      \n      prefix\n      suffix\n      digits\n      yearFormat\n      yearReset\n\n    }\n  }\n";
+export declare const RETURNS_SETTINGS_QUERY = "\n  query SdkReturnsSettings {\n    activeChannel {\n      id\n      customFields {\n        returnsEnabled\n        returnWindowDays\n        returnsAutoApprove\n        returnsRequireReceiptBeforeSettle\n        returnsDefaultRestockLocationId\n      }\n    }\n  }\n";
+export declare const RETURNS_FOR_ORDER_QUERY = "\n  query SdkReturnsForOrder($orderId: ID!) {\n    returnsForOrder(orderId: $orderId) {\n      \n    id\n    code\n    channelId\n    orderId\n    orderCode\n    customerId\n    currencyCode\n    state\n    initiator\n    customerNote\n    adminNote\n    preferredSettlementMethod\n    settlementMethod\n    shippingRefundAmount\n    settledAmount\n    refundId\n    creditNoteId\n    creditNoteNumber\n    requestedAt\n    resolvedAt\n    createdAt\n    updatedAt\n    lines {\n      id\n      returnId\n      orderLineId\n      productVariantId\n      productVariantName\n      productVariantSku\n      requestedQty\n      approvedQty\n      receivedQty\n      restockQty\n      writeOffQty\n      restockLocationId\n      reasonCode\n      reasonNote\n      unitPriceWithTax\n      unitPriceWithTaxUnrounded\n      refundAmount\n      createdAt\n      updatedAt\n    }\n\n      alreadyCreditedBy {\n        \n        creditNoteId\n        creditNoteNumber\n        ledger\n\n      }\n    }\n  }\n";
+/** {@link RETURNS_FOR_ORDER_QUERY} for an engine released before `alreadyCreditedBy`. */
+export declare const RETURNS_FOR_ORDER_QUERY_LEGACY = "\n  query SdkReturnsForOrderLegacy($orderId: ID!) {\n    returnsForOrder(orderId: $orderId) {\n      \n    id\n    code\n    channelId\n    orderId\n    orderCode\n    customerId\n    currencyCode\n    state\n    initiator\n    customerNote\n    adminNote\n    preferredSettlementMethod\n    settlementMethod\n    shippingRefundAmount\n    settledAmount\n    refundId\n    creditNoteId\n    creditNoteNumber\n    requestedAt\n    resolvedAt\n    createdAt\n    updatedAt\n    lines {\n      id\n      returnId\n      orderLineId\n      productVariantId\n      productVariantName\n      productVariantSku\n      requestedQty\n      approvedQty\n      receivedQty\n      restockQty\n      writeOffQty\n      restockLocationId\n      reasonCode\n      reasonNote\n      unitPriceWithTax\n      unitPriceWithTaxUnrounded\n      refundAmount\n      createdAt\n      updatedAt\n    }\n\n    }\n  }\n";
+export declare const CLOSE_RETURN_ALREADY_CREDITED_MUTATION = "\n  mutation SdkCloseReturnAlreadyCredited($input: CloseReturnAlreadyCreditedInput!) {\n    closeReturnAlreadyCredited(input: $input) {\n      \n    id\n    code\n    channelId\n    orderId\n    orderCode\n    customerId\n    currencyCode\n    state\n    initiator\n    customerNote\n    adminNote\n    preferredSettlementMethod\n    settlementMethod\n    shippingRefundAmount\n    settledAmount\n    refundId\n    creditNoteId\n    creditNoteNumber\n    requestedAt\n    resolvedAt\n    createdAt\n    updatedAt\n    lines {\n      id\n      returnId\n      orderLineId\n      productVariantId\n      productVariantName\n      productVariantSku\n      requestedQty\n      approvedQty\n      receivedQty\n      restockQty\n      writeOffQty\n      restockLocationId\n      reasonCode\n      reasonNote\n      unitPriceWithTax\n      unitPriceWithTaxUnrounded\n      refundAmount\n      createdAt\n      updatedAt\n    }\n\n      alreadyCreditedBy {\n        \n        creditNoteId\n        creditNoteNumber\n        ledger\n\n      }\n      \n      history {\n        state\n        actor\n        actorUserId\n        reason\n        createdAt\n      }\n\n    }\n  }\n";
+export declare const RETURN_ELIGIBILITY_QUERY = "\n  query SdkReturnEligibility($orderId: ID!) {\n    returnEligibilityForOrder(orderId: $orderId) {\n      orderId\n      eligible\n      reason\n      returnWindowEndsAt\n      lines {\n        orderLineId\n        productVariantId\n        productVariantName\n        productVariantSku\n        fulfilledQty\n        returnableQty\n        creditedQty\n        correctionCredits {\n          \n          orderLineId\n          creditNoteId\n          creditNoteNumber\n          ledger\n          quantity\n          amount\n\n        }\n        unitPriceWithTax\n        unitPriceWithTaxUnrounded\n      }\n    }\n  }\n";
+/**
+ * {@link RETURN_ELIGIBILITY_QUERY} for an engine released before 2026-10-09, which has no
+ * `creditedQty`/`correctionCredits`: GraphQL refuses a whole document over one unknown field.
+ */
+export declare const RETURN_ELIGIBILITY_QUERY_LEGACY = "\n  query SdkReturnEligibilityLegacy($orderId: ID!) {\n    returnEligibilityForOrder(orderId: $orderId) {\n      orderId\n      eligible\n      reason\n      returnWindowEndsAt\n      lines {\n        orderLineId\n        productVariantId\n        productVariantName\n        productVariantSku\n        fulfilledQty\n        returnableQty\n        unitPriceWithTax\n        unitPriceWithTaxUnrounded\n      }\n    }\n  }\n";
+export declare const RETURN_SETTLEMENT_OPTIONS_QUERY = "\n  query SdkReturnSettlementOptions($returnId: ID!) {\n    returnSettlementOptions(returnId: $returnId) {\n      returnId\n      currencyCode\n      settleable\n      blockedBy\n      refund {\n        available\n        reasonCode\n        payments {\n          paymentId\n          method\n          refundable\n        }\n      }\n      creditNote {\n        available\n        ledger\n        reasonCode\n        invoiceNumber\n      }\n      account {\n        available\n        reasonCode\n        message\n        held\n        book\n      }\n      initialMethod\n      defaultAmount\n      amountCeiling\n      correctionCredits {\n        \n          orderLineId\n          creditNoteId\n          creditNoteNumber\n          ledger\n          quantity\n          amount\n\n      }\n      shippingCeiling\n      alreadyCredited {\n        available\n        reasonCode\n        creditNotes {\n          \n        creditNoteId\n        creditNoteNumber\n        ledger\n\n        }\n      }\n    }\n  }\n";
+/**
+ * {@link RETURN_SETTLEMENT_OPTIONS_QUERY} for an engine with `alreadyCredited` but released before
+ * the account option named the store's book (incentives sprint 8 PR 4).
+ */
+export declare const RETURN_SETTLEMENT_OPTIONS_QUERY_BEFORE_BOOK = "\n  query SdkReturnSettlementOptionsBeforeBook($returnId: ID!) {\n    returnSettlementOptions(returnId: $returnId) {\n      returnId\n      currencyCode\n      settleable\n      blockedBy\n      refund {\n        available\n        reasonCode\n        payments {\n          paymentId\n          method\n          refundable\n        }\n      }\n      creditNote {\n        available\n        ledger\n        reasonCode\n        invoiceNumber\n      }\n      account {\n        available\n        reasonCode\n        message\n        held\n      }\n      initialMethod\n      defaultAmount\n      amountCeiling\n      correctionCredits {\n        \n          orderLineId\n          creditNoteId\n          creditNoteNumber\n          ledger\n          quantity\n          amount\n\n      }\n      shippingCeiling\n      alreadyCredited {\n        available\n        reasonCode\n        creditNotes {\n          \n        creditNoteId\n        creditNoteNumber\n        ledger\n\n        }\n      }\n    }\n  }\n";
+/**
+ * {@link RETURN_SETTLEMENT_OPTIONS_QUERY} for an engine with the account settlement (2026-10-10)
+ * but released before `alreadyCredited` (ruling U15).
+ */
+export declare const RETURN_SETTLEMENT_OPTIONS_QUERY_BEFORE_CLOSE = "\n  query SdkReturnSettlementOptionsBeforeClose($returnId: ID!) {\n    returnSettlementOptions(returnId: $returnId) {\n      returnId\n      currencyCode\n      settleable\n      blockedBy\n      refund {\n        available\n        reasonCode\n        payments {\n          paymentId\n          method\n          refundable\n        }\n      }\n      creditNote {\n        available\n        ledger\n        reasonCode\n        invoiceNumber\n      }\n      account {\n        available\n        reasonCode\n        message\n        held\n      }\n      initialMethod\n      defaultAmount\n      amountCeiling\n      correctionCredits {\n        \n          orderLineId\n          creditNoteId\n          creditNoteNumber\n          ledger\n          quantity\n          amount\n\n      }\n      shippingCeiling\n    }\n  }\n";
+/**
+ * {@link RETURN_SETTLEMENT_OPTIONS_QUERY} for an engine with `shippingCeiling` but released before
+ * the account settlement (2026-10-10).
+ */
+export declare const RETURN_SETTLEMENT_OPTIONS_QUERY_BEFORE_ACCOUNT = "\n  query SdkReturnSettlementOptionsBeforeAccount($returnId: ID!) {\n    returnSettlementOptions(returnId: $returnId) {\n      returnId\n      currencyCode\n      settleable\n      blockedBy\n      refund {\n        available\n        reasonCode\n        payments {\n          paymentId\n          method\n          refundable\n        }\n      }\n      creditNote {\n        available\n        ledger\n        reasonCode\n        invoiceNumber\n      }\n      initialMethod\n      defaultAmount\n      amountCeiling\n      correctionCredits {\n        \n          orderLineId\n          creditNoteId\n          creditNoteNumber\n          ledger\n          quantity\n          amount\n\n      }\n      shippingCeiling\n    }\n  }\n";
+/**
+ * {@link RETURN_SETTLEMENT_OPTIONS_QUERY} for an engine with the correction credits (2026-10-09)
+ * but released before `shippingCeiling`.
+ */
+export declare const RETURN_SETTLEMENT_OPTIONS_QUERY_BEFORE_SHIPPING = "\n  query SdkReturnSettlementOptionsBeforeShipping($returnId: ID!) {\n    returnSettlementOptions(returnId: $returnId) {\n      returnId\n      currencyCode\n      settleable\n      blockedBy\n      refund {\n        available\n        reasonCode\n        payments {\n          paymentId\n          method\n          refundable\n        }\n      }\n      creditNote {\n        available\n        ledger\n        reasonCode\n        invoiceNumber\n      }\n      initialMethod\n      defaultAmount\n      amountCeiling\n      correctionCredits {\n        \n          orderLineId\n          creditNoteId\n          creditNoteNumber\n          ledger\n          quantity\n          amount\n\n      }\n    }\n  }\n";
+/**
+ * {@link RETURN_SETTLEMENT_OPTIONS_QUERY} for an engine with the plan (W9-47) but released before
+ * 2026-10-09, which has no `amountCeiling`/`correctionCredits`.
+ */
+export declare const RETURN_SETTLEMENT_OPTIONS_QUERY_LEGACY = "\n  query SdkReturnSettlementOptionsLegacy($returnId: ID!) {\n    returnSettlementOptions(returnId: $returnId) {\n      returnId\n      currencyCode\n      settleable\n      blockedBy\n      refund {\n        available\n        reasonCode\n        payments {\n          paymentId\n          method\n          refundable\n        }\n      }\n      creditNote {\n        available\n        ledger\n        reasonCode\n        invoiceNumber\n      }\n      initialMethod\n      defaultAmount\n    }\n  }\n";
+/** `admin.returns.numbering`: the store's RMA code format. */
+export interface ReturnNumberingModule {
+    /**
+     * The format the store's next RMA code takes (the defaults until it is first set). Needs
+     * `ReadOrderReturn`.
+     *
+     * @effect read
+     */
+    get(options?: Call): Promise<ReturnNumberingConfig>;
+    /**
+     * Change the format; a field left out keeps its value, `digits` clamps to 3..8. Codes already
+     * issued keep theirs. A year format other than `none`, `short` or `full` is refused
+     * `NUMBERING_YEAR_FORMAT_INVALID`, a `digits` that is not a whole number
+     * `RETURN_NUMBERING_CONFIG_INVALID`. Needs `UpdateOrderReturn`.
+     *
+     * @effect write
+     */
+    set(input: UpdateReturnNumberingConfigInput, options?: Call): Promise<ReturnNumberingConfig>;
+}
+/** `admin.returns.settings`: the store's own return policy (G80: typed per domain). */
+export interface ReturnsSettingsModule {
+    /**
+     * The active store's OWN return policy, as its channel stores it. Writing it is
+     * `tenant`/channel settings' (a later `.set()`).
+     *
+     * @effect read
+     */
+    get(options?: Call): Promise<ReturnsSettings>;
+}
+export interface ReturnsModule {
+    /**
+     * One return with its lines and its status log (newest first), or `null`
+     * when this store holds no return with that id (another store's return answers the same).
+     * Needs `ReadOrderReturn`.
+     *
+     * It also says which steps the return offers now (`allowedActions`), what it refunds by
+     * default (`refundEstimate`, per line too) and who the customer is (`customer`, for a caller
+     * holding `ReadCustomer` or `ReadOrder`). `allowedActions` is a PLAN: every write judges again.
+     * Against an engine released before 2026-10-11 the call retries once without them (and keeps
+     * doing so for this client), and they are absent.
+     *
+     * @effect read
+     */
+    get(id: string, options?: Call): Promise<OrderReturnDetail | null>;
+    /**
+     * Every return of one order, newest first. Needs `ReadOrderReturn`. Degrades
+     * like {@link ReturnsModule.get} against an older engine.
+     *
+     * @effect read
+     */
+    forOrder(orderId: string, options?: Call): Promise<OrderReturn[]>;
+    /**
+     * What of an order can still be returned, line by line, and the return
+     * window. The window is reported, never enforced here: an admin may return
+     * outside it. Needs `ReadOrderReturn`.
+     *
+     * A unit an invoice correction credited whole is not returnable: each line
+     * says how many (`creditedQty`) and on which credit notes
+     * (`correctionCredits`), and a return asking for more is refused
+     * `RETURN_QUANTITY_ALREADY_CREDITED`. An engine released before 2026-10-09
+     * has none of these: the call then retries once without them (and keeps doing
+     * so for this client), and the fields are absent.
+     *
+     * @effect read
+     */
+    eligibility(orderId: string, options?: Call): Promise<ReturnEligibility>;
+    /**
+     * How a return can be settled now: whether it is settleable (and why not),
+     * which methods are open (with the payments a refund may name and what each
+     * can still give back), and which method to preselect. Needs
+     * `ReadOrderReturn` AND `ReadOrder`: it names the order's payments.
+     *
+     * This is the PLAN. The write ({@link ReturnsModule.settle}) loads its own facts and judges
+     * again, so settling can still be refused when something changed in between,
+     * and an `amountOverride` above a payment's headroom is refused there. A
+     * return this store does not hold is a `NotFoundError` (`ENTITY_NOT_FOUND`).
+     *
+     * When an invoice correction already credited goods of the return,
+     * `defaultAmount` is what is left of them, `amountCeiling` the most an
+     * override may state (above it: `RETURN_AMOUNT_ALREADY_CREDITED`), and
+     * `correctionCredits` names the credit notes. When one credited the order's
+     * shipping, `shippingCeiling` is the most a shipping refund may state (above
+     * it: `RETURN_SHIPPING_ALREADY_CREDITED`). When corrections credited ALL of
+     * the goods, `alreadyCredited.available` opens
+     * {@link ReturnsModule.closeAlreadyCredited}.
+     *
+     * `account` says whether the money can go onto the customer's account instead
+     * ({@link ReturnsModule.settle} with method `account`): only where the store keeps the
+     * accounts-receivable ledger itself and the customer has a credit account,
+     * with what the order's settled payments still hold (`held`).
+     *
+     * Needs an engine that serves `returnSettlementOptions`; against an older one
+     * this call fails validation and nothing else does. Each newer field an older
+     * engine does not know (`alreadyCredited`, then `account`, `shippingCeiling`, then
+     * `amountCeiling`/`correctionCredits`) is dropped by retrying once with the next
+     * older document, and this client keeps asking that one.
+     *
+     * @effect read
+     */
+    settlementOptions(returnId: string, options?: Call): Promise<ReturnSettlementOptions>;
+    /**
+     * Closes a return whose goods invoice corrections already credited in full:
+     * "Close — already credited on CN-…" (ruling U15). Such a return can never be
+     * settled (nothing is left) and, once received, never cancelled. The close
+     * moves NO money and touches no stock: the return reads `settled` with
+     * `settledAmount` 0, no `settlementMethod`, and `alreadyCreditedBy` naming
+     * the credit notes. `reason` goes on its status history (default: it names
+     * the credit notes). Needs `UpdateOrderReturn`.
+     *
+     * Open exactly when `settlementOptions(...).alreadyCredited.available`; the
+     * engine judges again under the order's money turn. Repeating it on a return
+     * it closed answers that return unchanged. Refusals, all coded:
+     * `RETURN_NOT_ALREADY_CREDITED` (money is still left: settle it; or no
+     * correction names its goods), `RETURN_CLOSE_STATE_CONFLICT` (it cannot be
+     * settled now: requested, settled, a refund in flight, a receipt required),
+     * `IDEMPOTENCY_OUTCOME_UNKNOWN` (a refund it waits on was never confirmed),
+     * `ORDER_MONEY_ACTION_IN_PROGRESS` (retryable: another money action on the
+     * order holds its turn) and `ENTITY_NOT_FOUND` (not this store's return).
+     *
+     * Needs an engine that serves `closeReturnAlreadyCredited`; against an older
+     * one the call fails validation.
+     *
+     * @effect irreversible
+     */
+    closeAlreadyCredited(returnId: string, input?: {
+        reason?: string | null;
+    }, options?: Call): Promise<OrderReturnDetail>;
+    /**
+     * A page of the store's returns, newest first, each with `refundEstimate` and `customer` (no
+     * second request for names). Needs `ReadOrderReturn`. Retries without the two fields against an
+     * engine released before 2026-10-11, as `get` does.
+     *
+     * @effect read
+     */
+    list(filter?: ReturnListFilter, options?: Call): Promise<OrderReturnList>;
+    /**
+     * How many returns wait for review (state `requested`): the count behind a "Returns" badge.
+     * Needs `ReadOrderReturn`.
+     *
+     * @effect read
+     */
+    openCount(options?: Call): Promise<number>;
+    /**
+     * Create a return on the order's customer's behalf. Refused `RETURN_INPUT_INVALID` (a quantity
+     * above what is returnable, a line of another order), `RETURN_QUANTITY_ALREADY_CREDITED` (units
+     * an invoice correction credited), `RETURN_WINDOW_CLOSED` (after the window, unless
+     * `overrideWindow`), `CUSTOMER_ERASED` (the customer's words for an erased customer). Needs
+     * `CreateOrderReturn`.
+     *
+     * @effect write
+     */
+    create(input: CreateReturnInput, options?: Call): Promise<OrderReturn>;
+    /**
+     * Approve a requested return, line by line. Refused `RETURN_STATE_INVALID` unless it is
+     * requested (`allowedActions` says `APPROVE`), `RETURN_INPUT_INVALID` for a decision the
+     * lines cannot take, `RETURN_QUANTITY_ALREADY_CREDITED` / `RETURN_AMOUNT_ALREADY_CREDITED` on a
+     * line an invoice correction credited since the request. Needs `UpdateOrderReturn`.
+     *
+     * @effect write
+     */
+    approve(id: string, input: ApproveReturnInput, options?: Call): Promise<OrderReturn>;
+    /**
+     * Reject a requested return, for good: it cannot be reopened. The reason is recorded and shown
+     * to the customer. Refused `RETURN_STATE_INVALID` unless it is requested,
+     * `RETURN_INPUT_INVALID` without a reason. Needs `UpdateOrderReturn`.
+     *
+     * @effect destructive
+     */
+    reject(id: string, reason: string, options?: Call): Promise<OrderReturn>;
+    /**
+     * Cancel a return, for good: it cannot be reopened, and its quantities become returnable
+     * again. Only while requested or approved and before any goods came back; otherwise
+     * `RETURN_STATE_INVALID` (`details[0].reasonCode` `STATE` or `RECEIPT_RECORDED`, as
+     * `allowedActions` reports it). Needs `UpdateOrderReturn`.
+     *
+     * @effect destructive
+     */
+    cancel(id: string, input?: {
+        reason?: string | null;
+    }, options?: Call): Promise<OrderReturn>;
+    /**
+     * Record goods that came back, graded per line (restock to a location, or write off).
+     * Receipts add up; the first moves the return to `items_received`. Refused
+     * `RETURN_STATE_INVALID` outside approved/items_received or when nothing approved is still to
+     * come back (`NOTHING_TO_RECEIVE`), `RETURN_INPUT_INVALID` for a quantity above what is still
+     * to come back or a location the store does not hold. Restocked units raise stock at that
+     * location. Needs `UpdateOrderReturn`.
+     *
+     * @effect write
+     */
+    recordReceipt(id: string, input: RecordReturnReceiptInput, options?: Call): Promise<OrderReturn>;
+    /**
+     * Append to the merchant's internal note (never shown to the customer). Refused
+     * `RETURN_INPUT_INVALID` for an empty note. Needs `UpdateOrderReturn`.
+     *
+     * @effect write
+     */
+    addNote(id: string, note: string, options?: Call): Promise<OrderReturn>;
+    /**
+     * Settle a received return with money: `refund` (to a settled payment of the order),
+     * `store_credit` (a credit note) or `account` (the money goes on the customer's account,
+     * ruling U10). Read {@link ReturnsModule.settlementOptions} first: it says which methods are
+     * open, with the engine's reasons and figures. The engine judges again here and answers the
+     * settled return, with its history. Needs `UpdateOrderReturn`.
+     *
+     * A refund that a gateway settles later leaves the return `settlement_pending` (`refundId` names
+     * the refund) until the provider confirms it; an offline method settles it at once.
+     *
+     * **Pass `options.idempotencyKey`, one per settlement attempt, and reuse it for every send of
+     * that attempt.** A repeat under the same key answers the first one's outcome (the settled
+     * return, or the same coded refusal) and never moves money again; a repeat while the first is
+     * still running is `IDEMPOTENCY_IN_PROGRESS` (wait, then send it again under the same key); the
+     * same key with a different `input` is `IDEMPOTENCY_CONFLICT` (409). Without a key the return's
+     * own state still refuses a second settlement (`RETURN_SETTLE_STATE_INVALID`), but a resend
+     * cannot learn what the first send did. A refusal ends the attempt: a changed request goes
+     * under a new key.
+     *
+     * Refusals, all coded:
+     * - `REFUND_ORPHAN_EXISTS` (ruling G57): a refund of the invoiced order stands that no credit
+     *   note names, so money (a refund, an accounts-receivable credit, the account) is withheld; a
+     *   credit note on a retail invoice moves no money and stays open;
+     * - `RETURN_AMOUNT_ALREADY_CREDITED` / `RETURN_SHIPPING_ALREADY_CREDITED` (ruling G66): an
+     *   invoice correction already credited these goods or the shipping (`amountCeiling`,
+     *   `shippingCeiling` say what is left);
+     * - `ORDER_MONEY_ACTION_IN_PROGRESS` (409, ruling G72): another money action on the order (a
+     *   correction, another settlement) held its turn past 30 seconds. Nothing ran: send it again
+     *   (this SDK repeats no write on its own);
+     * - `IDEMPOTENCY_OUTCOME_UNKNOWN` (`error.outcomeUnknown`): the refund reached the payment
+     *   provider and its answer never came, so the money may have moved. The return waits in
+     *   `settlement_pending` and nothing settles it again until the provider's answer is recorded on
+     *   the refund (`payments.reconcileRefund`): made completes the return, not made lets it be
+     *   settled again;
+     * - `RETURN_SETTLE_STATE_INVALID` (422): already settled, a refund on its way, a receipt the
+     *   store requires first, or requested/rejected/cancelled (`details[0].code` names which:
+     *   `ALREADY_SETTLED`, `IN_PROGRESS`, `RECEIPT_REQUIRED`, `STATE`, as `settlementOptions.blockedBy`);
+     * - `RETURN_SETTLE_INPUT_INVALID` (400): an amount that is not a whole number of minor units of
+     *   0 or more, nothing to settle, a `paymentId` the order does not hold or that is not settled;
+     * - `RETURN_SETTLE_NO_REFUNDABLE_PAYMENT`: no settled payment can carry the refund;
+     * - `REFUND_EXCEEDS_SETTLED` / `REFUND_EXCEEDS_PAYMENT`: more than the order or the payment can
+     *   give back now;
+     * - `RETURN_SETTLE_REFUND_REFUSED`: the refund was refused before the payment provider was
+     *   asked, so nothing moved (`details[0].code` says why); a refund that fails after the
+     *   provider was asked is `IDEMPOTENCY_OUTCOME_UNKNOWN` instead, the return parked on it;
+     * - `RETURN_SETTLE_CREDIT_NOTE_UNAVAILABLE`: this server cannot issue that credit note;
+     * - `RETURN_ACCOUNT_CREDIT_UNAVAILABLE` (`details[0].code` is the account's reason) /
+     *   `RETURN_ACCOUNT_CREDIT_EXCEEDS_HELD`;
+     * - `RETURN_NOT_FOUND` (404): this store holds no such return (another store's answers the same).
+     *
+     * Needs an engine that takes `settleReturn(idempotencyKey)` (2026-10-10); an older one fails
+     * validation and settles nothing.
+     *
+     * @effect money
+     */
+    settle(returnId: string, input: SettleReturnInput, options?: Call): Promise<OrderReturnDetail>;
+    /** The store's RMA code format. */
+    numbering: ReturnNumberingModule;
+    /** The store's own return policy. */
+    settings: ReturnsSettingsModule;
+}
+export declare function createReturnsModule(transport: Transport): ReturnsModule;