@sixtyninecommerce/admin 0.10.0 → 0.12.0

package/dist/returns/index.js

@@ -1,3 +1,18 @@
+/**
+ * `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 { NotFoundError, ValidationError } from '@sixtyninecommerce/core';
+import { statedCustomerAgreed } from '../payments/customer-consent.js';
 /** A return's state: the latest row of its status log. */
 export const RETURN_STATES = [
     'requested',
@@ -13,9 +28,24 @@ export const RETURN_STATES = [
  * 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.
+ * 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 const RETURN_SETTLEMENT_METHODS = ['refund', 'store_credit', 'account'];
+/**
+ * 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 const RETURN_SETTLEMENT_METHODS = ['refund', 'store_credit'];
+export const RETURN_ACTIONS = [
+    'APPROVE',
+    'REJECT',
+    'RECORD_RECEIPT',
+    'CANCEL',
+    'SETTLE',
+    'CLOSE_CREDITED',
+];
 /** Why a return cannot be settled now, in the order the engine checks them. */
 export const RETURN_SETTLEMENT_BLOCKERS = [
     'OUTCOME_UNKNOWN',
@@ -70,10 +100,31 @@ const RETURN_FIELDS = /* GraphQL */ `
       updatedAt
     }
 `;
-export const RETURN_QUERY = /* GraphQL */ `
-  query SdkOrderReturn($id: ID!) {
-    orderReturn(id: $id) {
-      ${RETURN_FIELDS}
+/** The fields of a `ReturnCoveringCreditNote` (a selection, spliced into several documents). */
+const COVERING_CREDIT_NOTE_FIELDS = /* GraphQL */ `
+        creditNoteId
+        creditNoteNumber
+        ledger
+`;
+/** What `get` and `list` add to a return's fields (engines from 2026-10-11). */
+const READ_FIELDS = /* GraphQL */ `
+    refundEstimate
+    customer {
+      id
+      firstName
+      lastName
+      emailAddress
+      addresses {
+        company
+        defaultBillingAddress
+        defaultShippingAddress
+      }
+    }
+    lines {
+      refundEstimate
+    }
+`;
+const HISTORY_FIELDS = /* GraphQL */ `
       history {
         state
         actor
@@ -81,6 +132,176 @@ export const RETURN_QUERY = /* GraphQL */ `
         reason
         createdAt
       }
+`;
+export const RETURN_QUERY = /* GraphQL */ `
+  query SdkOrderReturn($id: ID!) {
+    orderReturn(id: $id) {
+      ${RETURN_FIELDS}
+      alreadyCreditedBy {
+        ${COVERING_CREDIT_NOTE_FIELDS}
+      }
+      ${HISTORY_FIELDS}
+      ${READ_FIELDS}
+      allowedActions {
+        action
+        allowed
+        reasonCode
+      }
+    }
+  }
+`;
+/**
+ * {@link RETURN_QUERY} for an engine with `alreadyCreditedBy` (ruling U15) but released before
+ * `allowedActions`, `refundEstimate` and `customer` (2026-10-11).
+ */
+export const RETURN_QUERY_BEFORE_ACTIONS = /* GraphQL */ `
+  query SdkOrderReturnBeforeActions($id: ID!) {
+    orderReturn(id: $id) {
+      ${RETURN_FIELDS}
+      alreadyCreditedBy {
+        ${COVERING_CREDIT_NOTE_FIELDS}
+      }
+      ${HISTORY_FIELDS}
+    }
+  }
+`;
+/** {@link RETURN_QUERY} for an engine released before `alreadyCreditedBy` (ruling U15). */
+export const RETURN_QUERY_LEGACY = /* GraphQL */ `
+  query SdkOrderReturnLegacy($id: ID!) {
+    orderReturn(id: $id) {
+      ${RETURN_FIELDS}
+      ${HISTORY_FIELDS}
+    }
+  }
+`;
+export const RETURNS_LIST_QUERY = /* GraphQL */ `
+  query SdkOrderReturns($options: OrderReturnListOptions) {
+    orderReturns(options: $options) {
+      items {
+        ${RETURN_FIELDS}
+        alreadyCreditedBy {
+          ${COVERING_CREDIT_NOTE_FIELDS}
+        }
+        ${READ_FIELDS}
+      }
+      totalItems
+    }
+  }
+`;
+/** {@link RETURNS_LIST_QUERY} for an engine with `alreadyCreditedBy` but released before 2026-10-11. */
+export const RETURNS_LIST_QUERY_BEFORE_ACTIONS = /* GraphQL */ `
+  query SdkOrderReturnsBeforeActions($options: OrderReturnListOptions) {
+    orderReturns(options: $options) {
+      items {
+        ${RETURN_FIELDS}
+        alreadyCreditedBy {
+          ${COVERING_CREDIT_NOTE_FIELDS}
+        }
+      }
+      totalItems
+    }
+  }
+`;
+/** {@link RETURNS_LIST_QUERY} for an engine released before `alreadyCreditedBy`. */
+export const RETURNS_LIST_QUERY_LEGACY = /* GraphQL */ `
+  query SdkOrderReturnsLegacy($options: OrderReturnListOptions) {
+    orderReturns(options: $options) {
+      items {
+        ${RETURN_FIELDS}
+      }
+      totalItems
+    }
+  }
+`;
+export const OPEN_RETURNS_COUNT_QUERY = /* GraphQL */ `
+  query SdkOpenReturnsCount {
+    orderReturns(options: { take: 1, state: requested }) {
+      totalItems
+    }
+  }
+`;
+export const CREATE_RETURN_MUTATION = /* GraphQL */ `
+  mutation SdkCreateReturn($input: CreateReturnInput!) {
+    createReturn(input: $input) {
+      ${RETURN_FIELDS}
+    }
+  }
+`;
+export const APPROVE_RETURN_MUTATION = /* GraphQL */ `
+  mutation SdkApproveReturn($input: ApproveReturnInput!) {
+    approveReturn(input: $input) {
+      ${RETURN_FIELDS}
+    }
+  }
+`;
+export const REJECT_RETURN_MUTATION = /* GraphQL */ `
+  mutation SdkRejectReturn($id: ID!, $reason: String!) {
+    rejectReturn(id: $id, reason: $reason) {
+      ${RETURN_FIELDS}
+    }
+  }
+`;
+export const CANCEL_RETURN_MUTATION = /* GraphQL */ `
+  mutation SdkCancelReturn($id: ID!, $reason: String) {
+    cancelReturn(id: $id, reason: $reason) {
+      ${RETURN_FIELDS}
+    }
+  }
+`;
+export const RECORD_RETURN_RECEIPT_MUTATION = /* GraphQL */ `
+  mutation SdkRecordReturnReceipt($input: RecordReturnReceiptInput!) {
+    recordReturnReceipt(input: $input) {
+      ${RETURN_FIELDS}
+    }
+  }
+`;
+export const SETTLE_RETURN_MUTATION = /* GraphQL */ `
+  mutation SdkSettleReturn($input: SettleReturnInput!, $idempotencyKey: String) {
+    settleReturn(input: $input, idempotencyKey: $idempotencyKey) {
+      ${RETURN_FIELDS}
+      ${HISTORY_FIELDS}
+    }
+  }
+`;
+export const ADD_RETURN_NOTE_MUTATION = /* GraphQL */ `
+  mutation SdkAddReturnNote($id: ID!, $note: String!) {
+    addReturnNote(id: $id, note: $note) {
+      ${RETURN_FIELDS}
+    }
+  }
+`;
+const NUMBERING_FIELDS = /* GraphQL */ `
+      prefix
+      suffix
+      digits
+      yearFormat
+      yearReset
+`;
+export const RETURN_NUMBERING_QUERY = /* GraphQL */ `
+  query SdkReturnNumberingConfig {
+    returnNumberingConfig {
+      ${NUMBERING_FIELDS}
+    }
+  }
+`;
+export const UPDATE_RETURN_NUMBERING_MUTATION = /* GraphQL */ `
+  mutation SdkUpdateReturnNumberingConfig($input: UpdateReturnNumberingConfigInput!) {
+    updateReturnNumberingConfig(input: $input) {
+      ${NUMBERING_FIELDS}
+    }
+  }
+`;
+export const RETURNS_SETTINGS_QUERY = /* GraphQL */ `
+  query SdkReturnsSettings {
+    activeChannel {
+      id
+      customFields {
+        returnsEnabled
+        returnWindowDays
+        returnsAutoApprove
+        returnsRequireReceiptBeforeSettle
+        returnsDefaultRestockLocationId
+      }
     }
   }
 `;
@@ -88,11 +309,70 @@ export const RETURNS_FOR_ORDER_QUERY = /* GraphQL */ `
   query SdkReturnsForOrder($orderId: ID!) {
     returnsForOrder(orderId: $orderId) {
       ${RETURN_FIELDS}
+      alreadyCreditedBy {
+        ${COVERING_CREDIT_NOTE_FIELDS}
+      }
+    }
+  }
+`;
+/** {@link RETURNS_FOR_ORDER_QUERY} for an engine released before `alreadyCreditedBy`. */
+export const RETURNS_FOR_ORDER_QUERY_LEGACY = /* GraphQL */ `
+  query SdkReturnsForOrderLegacy($orderId: ID!) {
+    returnsForOrder(orderId: $orderId) {
+      ${RETURN_FIELDS}
+    }
+  }
+`;
+export const CLOSE_RETURN_ALREADY_CREDITED_MUTATION = /* GraphQL */ `
+  mutation SdkCloseReturnAlreadyCredited($input: CloseReturnAlreadyCreditedInput!) {
+    closeReturnAlreadyCredited(input: $input) {
+      ${RETURN_FIELDS}
+      alreadyCreditedBy {
+        ${COVERING_CREDIT_NOTE_FIELDS}
+      }
+      ${HISTORY_FIELDS}
     }
   }
 `;
+/** The fields of a `ReturnLineCorrectionCredit` (a selection, spliced into two documents). */
+const CORRECTION_CREDIT_FIELDS = /* GraphQL */ `
+          orderLineId
+          creditNoteId
+          creditNoteNumber
+          ledger
+          quantity
+          amount
+`;
 export const RETURN_ELIGIBILITY_QUERY = /* GraphQL */ `
   query SdkReturnEligibility($orderId: ID!) {
+    returnEligibilityForOrder(orderId: $orderId) {
+      orderId
+      eligible
+      reason
+      returnWindowEndsAt
+      lines {
+        orderLineId
+        productVariantId
+        productVariantName
+        productVariantSku
+        fulfilledQty
+        returnableQty
+        creditedQty
+        correctionCredits {
+          ${CORRECTION_CREDIT_FIELDS}
+        }
+        unitPriceWithTax
+        unitPriceWithTaxUnrounded
+      }
+    }
+  }
+`;
+/**
+ * {@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 const RETURN_ELIGIBILITY_QUERY_LEGACY = /* GraphQL */ `
+  query SdkReturnEligibilityLegacy($orderId: ID!) {
     returnEligibilityForOrder(orderId: $orderId) {
       orderId
       eligible
@@ -133,28 +413,493 @@ export const RETURN_SETTLEMENT_OPTIONS_QUERY = /* GraphQL */ `
         reasonCode
         invoiceNumber
       }
+      account {
+        available
+        reasonCode
+        message
+        held
+        book
+      }
+      initialMethod
+      defaultAmount
+      amountCeiling
+      correctionCredits {
+        ${CORRECTION_CREDIT_FIELDS}
+      }
+      shippingCeiling
+      alreadyCredited {
+        available
+        reasonCode
+        creditNotes {
+          ${COVERING_CREDIT_NOTE_FIELDS}
+        }
+      }
+      creditNoteTaxRate {
+        suggested
+        basis
+        rates
+        methods
+        invoiceTotal
+      }
+    }
+  }
+`;
+/**
+ * {@link RETURN_SETTLEMENT_OPTIONS_QUERY} for an engine with the account's book but released before
+ * the credit note's VAT rate (USER PD11, B6b).
+ */
+export const RETURN_SETTLEMENT_OPTIONS_QUERY_BEFORE_TAX_RATE = /* GraphQL */ `
+  query SdkReturnSettlementOptionsBeforeTaxRate($returnId: ID!) {
+    returnSettlementOptions(returnId: $returnId) {
+      returnId
+      currencyCode
+      settleable
+      blockedBy
+      refund {
+        available
+        reasonCode
+        payments {
+          paymentId
+          method
+          refundable
+        }
+      }
+      creditNote {
+        available
+        ledger
+        reasonCode
+        invoiceNumber
+      }
+      account {
+        available
+        reasonCode
+        message
+        held
+        book
+      }
+      initialMethod
+      defaultAmount
+      amountCeiling
+      correctionCredits {
+        ${CORRECTION_CREDIT_FIELDS}
+      }
+      shippingCeiling
+      alreadyCredited {
+        available
+        reasonCode
+        creditNotes {
+          ${COVERING_CREDIT_NOTE_FIELDS}
+        }
+      }
+    }
+  }
+`;
+/**
+ * {@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 const RETURN_SETTLEMENT_OPTIONS_QUERY_BEFORE_BOOK = /* GraphQL */ `
+  query SdkReturnSettlementOptionsBeforeBook($returnId: ID!) {
+    returnSettlementOptions(returnId: $returnId) {
+      returnId
+      currencyCode
+      settleable
+      blockedBy
+      refund {
+        available
+        reasonCode
+        payments {
+          paymentId
+          method
+          refundable
+        }
+      }
+      creditNote {
+        available
+        ledger
+        reasonCode
+        invoiceNumber
+      }
+      account {
+        available
+        reasonCode
+        message
+        held
+      }
       initialMethod
       defaultAmount
+      amountCeiling
+      correctionCredits {
+        ${CORRECTION_CREDIT_FIELDS}
+      }
+      shippingCeiling
+      alreadyCredited {
+        available
+        reasonCode
+        creditNotes {
+          ${COVERING_CREDIT_NOTE_FIELDS}
+        }
+      }
     }
   }
 `;
+/**
+ * {@link RETURN_SETTLEMENT_OPTIONS_QUERY} for an engine with the account settlement (2026-10-10)
+ * but released before `alreadyCredited` (ruling U15).
+ */
+export const RETURN_SETTLEMENT_OPTIONS_QUERY_BEFORE_CLOSE = /* GraphQL */ `
+  query SdkReturnSettlementOptionsBeforeClose($returnId: ID!) {
+    returnSettlementOptions(returnId: $returnId) {
+      returnId
+      currencyCode
+      settleable
+      blockedBy
+      refund {
+        available
+        reasonCode
+        payments {
+          paymentId
+          method
+          refundable
+        }
+      }
+      creditNote {
+        available
+        ledger
+        reasonCode
+        invoiceNumber
+      }
+      account {
+        available
+        reasonCode
+        message
+        held
+      }
+      initialMethod
+      defaultAmount
+      amountCeiling
+      correctionCredits {
+        ${CORRECTION_CREDIT_FIELDS}
+      }
+      shippingCeiling
+    }
+  }
+`;
+/**
+ * {@link RETURN_SETTLEMENT_OPTIONS_QUERY} for an engine with `shippingCeiling` but released before
+ * the account settlement (2026-10-10).
+ */
+export const RETURN_SETTLEMENT_OPTIONS_QUERY_BEFORE_ACCOUNT = /* GraphQL */ `
+  query SdkReturnSettlementOptionsBeforeAccount($returnId: ID!) {
+    returnSettlementOptions(returnId: $returnId) {
+      returnId
+      currencyCode
+      settleable
+      blockedBy
+      refund {
+        available
+        reasonCode
+        payments {
+          paymentId
+          method
+          refundable
+        }
+      }
+      creditNote {
+        available
+        ledger
+        reasonCode
+        invoiceNumber
+      }
+      initialMethod
+      defaultAmount
+      amountCeiling
+      correctionCredits {
+        ${CORRECTION_CREDIT_FIELDS}
+      }
+      shippingCeiling
+    }
+  }
+`;
+/**
+ * {@link RETURN_SETTLEMENT_OPTIONS_QUERY} for an engine with the correction credits (2026-10-09)
+ * but released before `shippingCeiling`.
+ */
+export const RETURN_SETTLEMENT_OPTIONS_QUERY_BEFORE_SHIPPING = /* GraphQL */ `
+  query SdkReturnSettlementOptionsBeforeShipping($returnId: ID!) {
+    returnSettlementOptions(returnId: $returnId) {
+      returnId
+      currencyCode
+      settleable
+      blockedBy
+      refund {
+        available
+        reasonCode
+        payments {
+          paymentId
+          method
+          refundable
+        }
+      }
+      creditNote {
+        available
+        ledger
+        reasonCode
+        invoiceNumber
+      }
+      initialMethod
+      defaultAmount
+      amountCeiling
+      correctionCredits {
+        ${CORRECTION_CREDIT_FIELDS}
+      }
+    }
+  }
+`;
+/**
+ * {@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 const RETURN_SETTLEMENT_OPTIONS_QUERY_LEGACY = /* GraphQL */ `
+  query SdkReturnSettlementOptionsLegacy($returnId: ID!) {
+    returnSettlementOptions(returnId: $returnId) {
+      returnId
+      currencyCode
+      settleable
+      blockedBy
+      refund {
+        available
+        reasonCode
+        payments {
+          paymentId
+          method
+          refundable
+        }
+      }
+      creditNote {
+        available
+        ledger
+        reasonCode
+        invoiceNumber
+      }
+      initialMethod
+      defaultAmount
+    }
+  }
+`;
+/**
+ * Whether a failure is "this engine does not know that field yet": the document refused before
+ * it ran, never an execution-time refusal or a transient failure (degrading on those would hide
+ * an outage behind silently missing fields). graphql-js answers a validation failure with HTTP
+ * 400, which reaches the SDK as `BAD_REQUEST`, or coded `GRAPHQL_VALIDATION_FAILED` (the storefront
+ * SDK's `isUnknownFieldRejection` reads the same two).
+ */
+function isUnknownFieldRejection(error) {
+    if (!(error instanceof ValidationError) || error.service !== 'vendure')
+        return false;
+    return (error.code === 'BAD_REQUEST' ||
+        error.code === 'GRAPHQL_VALIDATION_FAILED' ||
+        /Cannot query field/i.test(error.message));
+}
+/** The plan's documents, newest first: each drops the newest field the one before it asks. */
+const SETTLEMENT_OPTIONS_DOCUMENTS = [
+    RETURN_SETTLEMENT_OPTIONS_QUERY,
+    RETURN_SETTLEMENT_OPTIONS_QUERY_BEFORE_TAX_RATE,
+    RETURN_SETTLEMENT_OPTIONS_QUERY_BEFORE_BOOK,
+    RETURN_SETTLEMENT_OPTIONS_QUERY_BEFORE_CLOSE,
+    RETURN_SETTLEMENT_OPTIONS_QUERY_BEFORE_ACCOUNT,
+    RETURN_SETTLEMENT_OPTIONS_QUERY_BEFORE_SHIPPING,
+    RETURN_SETTLEMENT_OPTIONS_QUERY_LEGACY,
+];
 export function createReturnsModule(transport) {
+    /**
+     * Latched once the engine proved it predates the correction-credit fields, so the downgrade
+     * costs one refused request per client.
+     */
+    let correctionCreditsUnsupported = false;
+    /** Which of {@link SETTLEMENT_OPTIONS_DOCUMENTS} this engine answers (latched, never back up). */
+    let settlementOptionsTier = 0;
+    /** Latched once the engine proved it predates `alreadyCreditedBy` (one refused request per client). */
+    let alreadyCreditedByUnsupported = false;
+    /** Sends the current document, or the legacy one once the engine refused the new fields. */
+    async function withFallback(query, legacy, variables, options) {
+        if (!correctionCreditsUnsupported) {
+            try {
+                return await transport.graphql({ api: 'admin', query, variables }, options);
+            }
+            catch (error) {
+                if (!isUnknownFieldRejection(error))
+                    throw error;
+            }
+        }
+        const data = await transport.graphql({ api: 'admin', query: legacy, variables }, options);
+        correctionCreditsUnsupported = true;
+        return data;
+    }
+    /** The return reads: with `alreadyCreditedBy`, or without it once the engine refused it. */
+    async function readReturns(query, legacy, variables, options) {
+        if (!alreadyCreditedByUnsupported) {
+            try {
+                return await transport.graphql({ api: 'admin', query, variables }, options);
+            }
+            catch (error) {
+                if (!isUnknownFieldRejection(error))
+                    throw error;
+            }
+        }
+        const data = await transport.graphql({ api: 'admin', query: legacy, variables }, options);
+        alreadyCreditedByUnsupported = true;
+        return data;
+    }
+    /**
+     * Which tier of the `get`/`list` documents this engine answers (latched, never back up): 0 has
+     * `allowedActions`/`refundEstimate`/`customer` (2026-10-11), 1 only `alreadyCreditedBy`
+     * (U15), 2 neither. Tier 2 also latches `alreadyCreditedByUnsupported`, as `forOrder` reads it.
+     */
+    let returnReadTier = 0;
+    async function readTiered(documents, variables, options) {
+        if (alreadyCreditedByUnsupported)
+            returnReadTier = 2;
+        for (;;) {
+            const tier = returnReadTier;
+            try {
+                const data = await transport.graphql({ api: 'admin', query: documents[tier], variables }, options);
+                if (tier === 2)
+                    alreadyCreditedByUnsupported = true;
+                return data;
+            }
+            catch (error) {
+                if (tier === 2 || !isUnknownFieldRejection(error))
+                    throw error;
+                // A refused document names no field the SDK can read (the transport answers a generic
+                // 400), so each older tier is asked in turn, once per client.
+                returnReadTier = tier + 1;
+            }
+        }
+    }
+    /** One write that answers the return it changed. */
+    async function write(field, query, variables, options) {
+        const data = await transport.graphql({ api: 'admin', query, variables }, options);
+        return data[field];
+    }
     return {
         async get(id, options) {
-            const data = await transport.graphql({ api: 'admin', query: RETURN_QUERY, variables: { id } }, options);
+            const data = await readTiered([RETURN_QUERY, RETURN_QUERY_BEFORE_ACTIONS, RETURN_QUERY_LEGACY], { id }, options);
             return data.orderReturn;
         },
+        async list(filter, options) {
+            const data = await readTiered([RETURNS_LIST_QUERY, RETURNS_LIST_QUERY_BEFORE_ACTIONS, RETURNS_LIST_QUERY_LEGACY], { options: filter ?? {} }, options);
+            return data.orderReturns;
+        },
         async forOrder(orderId, options) {
-            const data = await transport.graphql({ api: 'admin', query: RETURNS_FOR_ORDER_QUERY, variables: { orderId } }, options);
+            const data = await readReturns(RETURNS_FOR_ORDER_QUERY, RETURNS_FOR_ORDER_QUERY_LEGACY, { orderId }, options);
             return data.returnsForOrder;
         },
         async eligibility(orderId, options) {
-            const data = await transport.graphql({ api: 'admin', query: RETURN_ELIGIBILITY_QUERY, variables: { orderId } }, options);
+            const data = await withFallback(RETURN_ELIGIBILITY_QUERY, RETURN_ELIGIBILITY_QUERY_LEGACY, { orderId }, options);
             return data.returnEligibilityForOrder;
         },
         async settlementOptions(returnId, options) {
-            const data = await transport.graphql({ api: 'admin', query: RETURN_SETTLEMENT_OPTIONS_QUERY, variables: { returnId } }, options);
-            return data.returnSettlementOptions;
+            const last = SETTLEMENT_OPTIONS_DOCUMENTS.length - 1;
+            // An engine that refused the correction credits on `eligibility` predates every newer tier.
+            if (correctionCreditsUnsupported)
+                settlementOptionsTier = last;
+            for (;;) {
+                const tier = settlementOptionsTier;
+                try {
+                    const data = await transport.graphql({
+                        api: 'admin',
+                        query: SETTLEMENT_OPTIONS_DOCUMENTS[tier],
+                        variables: { returnId },
+                    }, options);
+                    if (tier === last)
+                        correctionCreditsUnsupported = true;
+                    return data.returnSettlementOptions;
+                }
+                catch (error) {
+                    if (tier === last || !isUnknownFieldRejection(error))
+                        throw error;
+                    settlementOptionsTier = tier + 1;
+                }
+            }
+        },
+        async openCount(options) {
+            const data = await transport.graphql({ api: 'admin', query: OPEN_RETURNS_COUNT_QUERY }, options);
+            return data.orderReturns.totalItems;
+        },
+        create: (input, options) => write('createReturn', CREATE_RETURN_MUTATION, { input }, options),
+        approve: (id, input, options) => write('approveReturn', APPROVE_RETURN_MUTATION, { input: { id, ...input } }, options),
+        reject: (id, reason, options) => write('rejectReturn', REJECT_RETURN_MUTATION, { id, reason }, options),
+        cancel: (id, input, options) => write('cancelReturn', CANCEL_RETURN_MUTATION, { id, reason: input?.reason ?? null }, options),
+        recordReceipt: (id, input, options) => write('recordReturnReceipt', RECORD_RETURN_RECEIPT_MUTATION, { input: { id, lines: input.lines } }, options),
+        addNote: (id, note, options) => write('addReturnNote', ADD_RETURN_NOTE_MUTATION, { id, note }, options),
+        async settle(returnId, input, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: SETTLE_RETURN_MUTATION,
+                variables: {
+                    input: {
+                        id: returnId,
+                        method: input.method,
+                        ...(input.paymentId != null ? { paymentId: input.paymentId } : {}),
+                        ...(input.amountOverride != null ? { amountOverride: input.amountOverride } : {}),
+                        ...(input.shippingRefundAmount != null
+                            ? { shippingRefundAmount: input.shippingRefundAmount }
+                            : {}),
+                        ...(input.reason != null ? { reason: input.reason } : {}),
+                        ...statedCustomerAgreed(input.customerAgreed),
+                        ...(input.taxRate != null ? { taxRate: input.taxRate } : {}),
+                    },
+                    // A variable, not a header: the Admin API takes the key as an argument. `undefined`
+                    // when omitted, never null: `JSON.stringify` drops it, so no key stays off the wire.
+                    idempotencyKey: options?.idempotencyKey,
+                },
+            }, options);
+            return data.settleReturn;
+        },
+        numbering: {
+            async get(options) {
+                const data = await transport.graphql({ api: 'admin', query: RETURN_NUMBERING_QUERY }, options);
+                return data.returnNumberingConfig;
+            },
+            async set(input, options) {
+                const data = await transport.graphql({ api: 'admin', query: UPDATE_RETURN_NUMBERING_MUTATION, variables: { input } }, options);
+                return data.updateReturnNumberingConfig;
+            },
+        },
+        settings: {
+            async get(options) {
+                const data = await transport.graphql({ api: 'admin', query: RETURNS_SETTINGS_QUERY }, options);
+                const channel = data.activeChannel;
+                if (!channel) {
+                    throw new NotFoundError({
+                        code: 'CHANNEL_NOT_FOUND',
+                        message: 'No store is active for this session, so it has no return policy to read.',
+                        status: 404,
+                        service: 'vendure',
+                    });
+                }
+                const fields = channel.customFields;
+                return {
+                    channelId: channel.id,
+                    // The engine's own defaults (the plugin's field declarations) for a field it answers null.
+                    returnsEnabled: fields?.returnsEnabled === true,
+                    returnWindowDays: fields?.returnWindowDays ?? 30,
+                    returnsAutoApprove: fields?.returnsAutoApprove === true,
+                    returnsRequireReceiptBeforeSettle: fields?.returnsRequireReceiptBeforeSettle !== false,
+                    returnsDefaultRestockLocationId: fields?.returnsDefaultRestockLocationId ?? null,
+                };
+            },
+        },
+        async closeAlreadyCredited(returnId, input, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: CLOSE_RETURN_ALREADY_CREDITED_MUTATION,
+                variables: {
+                    input: { id: returnId, ...(input?.reason != null ? { reason: input.reason } : {}) },
+                },
+            }, options);
+            return data.closeReturnAlreadyCredited;
         },
     };
 }