@sixtyninecommerce/admin 0.9.0 → 0.11.0

package/dist/orders/status.d.ts

@@ -34,7 +34,7 @@ export type OrderAllocationBadge = (typeof ORDER_ALLOCATION_BADGES)[number];
 export declare const ORDER_EDIT_BLOCK_CODES: readonly ["INVOICE_LOCKED", "COMPLETED", "CANCELLED"];
 export type OrderEditBlockCode = (typeof ORDER_EDIT_BLOCK_CODES)[number];
 /** The actions the engine answers for, in the order it lists them. */
-export declare const ORDER_STATUS_ACTIONS: readonly ["MODIFY", "DELETE", "RELEASE_ALLOCATION", "CORRECT_FULFILLMENT", "CANCEL", "TRANSITION", "MARK_COMPLETED", "REOPEN"];
+export declare const ORDER_STATUS_ACTIONS: readonly ["MODIFY", "DELETE", "RELEASE_ALLOCATION", "CORRECT_FULFILLMENT", "CANCEL", "TRANSITION", "MARK_COMPLETED", "REOPEN", "SET_PAYMENT_NOT_REQUIRED", "SET_FULFILLMENT_HOLD", "SET_GOODWILL_ROUNDING", "SET_BILLING_FIELDS", "APPLY_GOODWILL_ROUNDING", "SET_PRICING_FIELDS"];
 /**
  * One thing that can be done to an order, with the engine write behind it and
  * what `allowed` asks of the caller:
@@ -56,14 +56,76 @@ export declare const ORDER_STATUS_ACTIONS: readonly ["MODIFY", "DELETE", "RELEAS
  *   locations (an API token or app installation with `locationIds`) must also
  *   hold every location the order's reservation sits at; otherwise the release
  *   answers `LOCATION_NOT_ALLOWED` and this action `PERMISSION`.
- * - `CANCEL`: `cancelOrder` for the whole order. Needs `UpdateOrder`.
+ * - `CANCEL`: `cancelOrder` for the whole order. Needs `UpdateOrder`. A credential
+ *   restricted to stock locations must also hold every location the order's
+ *   reservation sits at (a cancel releases it there); otherwise the cancel answers
+ *   `LOCATION_OUT_OF_SCOPE` and this action `PERMISSION`.
  * - `TRANSITION`: `transitionOrderToState` into one of `nextStates`. Needs
  *   `UpdateOrder`.
- * - `MARK_COMPLETED`: `markOrderCompleted`. Needs `UpdateOrder`.
- * - `REOPEN`: `reopenOrder`. Needs `UpdateOrder`.
+ * - `MARK_COMPLETED`: `orders.markCompleted`. Needs `UpdateOrder`.
+ * - `REOPEN`: `orders.reopen`. Needs `UpdateOrder`.
+ * - `SET_PAYMENT_NOT_REQUIRED`: `orders.setPaymentNotRequired`, in the direction it would go
+ *   next: lifting the waiver while the order carries one (`lifecycle.payment` then reads
+ *   `not_required`), waiving it otherwise. A cancelled order changes neither way (`CANCELLED`);
+ *   an order whose payment reads `not_required` without a waiver (a total of 0) has nothing to
+ *   waive or lift (`STATE`); a waiver waits while an invoice still bills the order
+ *   (`CREDIT_NOTE_REQUIRED`). The write refuses the `CANCELLED` and `CREDIT_NOTE_REQUIRED`
+ *   cases, `ORDER_PAYMENT_WAIVER_REFUSED`; it takes a waiver on a zero-total order, which this
+ *   action does not offer. Needs `UpdateOrder`.
+ * - `SET_FULFILLMENT_HOLD`: `orders.setFulfillmentHold`, in the direction it would go next: a
+ *   release while `lifecycle.fulfillment` is `on_hold` (any order but a live cart), a new hold
+ *   only on an open order (`STATE` otherwise). Needs `UpdateOrder`.
+ * - `SET_GOODWILL_ROUNDING`: `orders.setGoodwillRounding`, either way (apply or clear). Closed
+ *   once the order's total no longer moves: an invoice bills it (`INVOICE_LOCKED`), it is
+ *   completed or cancelled (`COMPLETED`, `CANCELLED`), or it is settled or invoiced in the
+ *   store's ERP (`ERP_LOCKED`); the write then refuses `GOODWILL_ROUNDING_LOCKED`. Whether
+ *   there is anything to round (one VAT rate, a total that is not whole) is not answered here:
+ *   applying to such an order is refused `GOODWILL_ROUNDING_NOT_APPLICABLE`. Needs
+ *   `UpdateOrder`. Whether APPLYING one is open is `APPLY_GOODWILL_ROUNDING`.
+ * - `APPLY_GOODWILL_ROUNDING`: `orders.setGoodwillRounding` with `apply: true`. The same lock as
+ *   `SET_GOODWILL_ROUNDING` first, then `LEAVES_MONEY_OVER`: the order is paid, and its payments
+ *   would hold more than the rounded total; the write then refuses
+ *   `GOODWILL_ROUNDING_LEAVES_MONEY_OVER`, because the rounding refunds nothing. Clearing a
+ *   rounding stays `SET_GOODWILL_ROUNDING` alone. Needs `UpdateOrder`.
+ * - `SET_BILLING_FIELDS`: a change of `customFields.removeTax`, `paymentTermsDays` or
+ *   `paymentConditionCode`, the order's fields that decide what it BILLS, through the engine's
+ *   `setOrderCustomFields` or `setOrderRemoveTax`. Closed while a live invoice bills the order
+ *   (`INVOICE_LOCKED`): its standard invoice not voided, or an accounts-receivable invoice
+ *   neither voided nor superseded. The write then refuses `ORDER_INVOICE_LOCKED` (422), with
+ *   the field in `details[].field` (a pointer into the arguments) and a sentence naming the
+ *   invoice and its ledger in `details[].message`; what the order bills is changed through that
+ *   invoice's correction (`documents.commitCorrection`). A value equal to the stored one is
+ *   never refused, and notes and the order's reference (`orders.setPurchaseOrderNumber`) are
+ *   not part of it. It answers those two writes only, and they store the value without
+ *   recalculating the order. Applying it to the order's amounts (the order edit:
+ *   `orders.planEdit`, `orders.commitEdit`), and changing a line's `unitPriceOverride` or
+ *   `unitPriceImported`, which this lock refuses too, are also closed while `MODIFY` answers
+ *   `INVOICE_LOCKED`, and that outlives the void of a retail invoice. The void opens the payment
+ *   terms again, not `removeTax`: `SET_PRICING_FIELDS` answers that. Needs `UpdateOrder`.
+ * - `SET_PRICING_FIELDS`: a change of `customFields.removeTax`, or of a line's
+ *   `unitPriceOverride` or `unitPriceImported`, the fields that decide the order's AMOUNTS, at
+ *   the engine's custom-field writes (`setOrderCustomFields`, `setOrderRemoveTax`,
+ *   `modifyOrder`, the draft line writes). Closed (`INVOICE_LOCKED`) while a live invoice bills
+ *   the order, and while its content stays locked with none: after its retail invoice was
+ *   voided, and on an order the platform it was imported from invoiced. Nothing recalculates
+ *   such an order, so its tax and prices stay as invoiced. The write refuses
+ *   `ORDER_INVOICE_LOCKED` (422) with the field in `details[].field` and the reason in
+ *   `details[].message`. A value equal to the stored one is never refused; the payment terms
+ *   are not part of it. Needs `UpdateOrder`.
+ *
+ * The two toggles are answered by engines from W10-25 on, the rounding from W10-26 on, and
+ * `SET_BILLING_FIELDS` and `SET_PRICING_FIELDS` from the engines that enforce them on; an older
+ * engine leaves them out of `actions`. For the first three that reads as "not available"; an
+ * engine that does not answer `SET_BILLING_FIELDS` does not lock those fields either, and one
+ * that does not answer `SET_PRICING_FIELDS` locks them only as `SET_BILLING_FIELDS` says. `APPLY_GOODWILL_ROUNDING` is answered
+ * by the engine that refuses a rounding on a paid order; an older one leaves it out and does not
+ * refuse it, so read a missing answer as "not available" (never offer the rounding on a guess).
  * - `CORRECT_FULFILLMENT`: one of TWO writes, with different gates.
- *   - `updateFulfillmentLineQuantities` needs `UpdateOrder`, and corrects any
- *     fulfillment of the order on any store.
+ *   - `updateFulfillmentLineQuantities` (`orders.correctFulfillmentQuantities`) needs
+ *     `UpdateOrder`, and corrects any fulfillment of the order on any store. A credential
+ *     restricted to stock locations (an API token or app installation with `locationIds`)
+ *     corrects only a fulfillment that ships from one of them (`LOCATION_OUT_OF_SCOPE`
+ *     otherwise).
  *   - `correctFulfillmentQuantities` needs `UpdateFulfillment` or
  *     `UpdateOrder`, and works only on a store with the warehouse workspace
  *     (`WAREHOUSE_NOT_ENABLED` otherwise). For a caller without `UpdateOrder`
@@ -73,7 +135,8 @@ export declare const ORDER_STATUS_ACTIONS: readonly ["MODIFY", "DELETE", "RELEAS
  *     quantity (`OFFICE_ONLY`).
  *
  *   So `allowed` is true for a caller with `UpdateOrder` whenever the order is
- *   eligible. For a caller holding `UpdateFulfillment` without `UpdateOrder`
+ *   eligible, except a credential restricted to stock locations, for which it is true only
+ *   while one of THIS order's fulfillments ships from one of its locations. For a caller holding `UpdateFulfillment` without `UpdateOrder`
  *   it is true only on a store with the warehouse workspace, and only while
  *   at least one of THIS order's fulfillments ships from one of the caller's
  *   warehouses. That caller must call `correctFulfillmentQuantities`: the
@@ -86,7 +149,7 @@ export declare const ORDER_STATUS_ACTIONS: readonly ["MODIFY", "DELETE", "RELEAS
  */
 export type OrderStatusActionName = (typeof ORDER_STATUS_ACTIONS)[number];
 /** Why an action is not allowed, in the order the engine lists them. */
-export declare const ORDER_STATUS_REASON_CODES: readonly ["INVOICE_LOCKED", "COMPLETED", "CANCELLED", "STATE", "NOTHING_ALLOCATED", "HAS_RECORDS", "NOTHING_TO_CANCEL", "SHOPPER_CART", "UNITS_SHIPPED", "ACTIVE_FULFILLMENT", "PERMISSION"];
+export declare const ORDER_STATUS_REASON_CODES: readonly ["INVOICE_LOCKED", "COMPLETED", "CANCELLED", "STATE", "NOTHING_ALLOCATED", "HAS_RECORDS", "NOTHING_TO_CANCEL", "SHOPPER_CART", "UNITS_SHIPPED", "ACTIVE_FULFILLMENT", "CREDIT_NOTE_REQUIRED", "HOLDS_MONEY", "ERP_LOCKED", "LEAVES_MONEY_OVER", "PERMISSION"];
 /**
  * - `INVOICE_LOCKED`, `COMPLETED`, `CANCELLED`: the edit block.
  * - `STATE`: the order's state does not allow it.
@@ -104,6 +167,31 @@ export declare const ORDER_STATUS_REASON_CODES: readonly ["INVOICE_LOCKED", "COM
  *   units come back through a return.
  * - `ACTIVE_FULFILLMENT`: a fulfillment not yet shipped holds a line. Detach
  *   the order from it or correct its quantities first.
+ * - `CREDIT_NOTE_REQUIRED` (`CANCEL` and `SET_PAYMENT_NOT_REQUIRED`): an invoice
+ *   still bills the order, paid or not. For `SET_PAYMENT_NOT_REQUIRED`, correct
+ *   the invoice first. For `CANCEL`, cancelling (whole or by lines) would leave
+ *   the invoice standing. Do what {@link OrderStatusView.cancelCreditNote}'s `remedy`
+ *   says first, then cancel: `CORRECT_INVOICE`, correct the invoice it names
+ *   (`documents.commitCorrection` on its ledger: credit it in full, with a
+ *   refund on a retail invoice); `REFUND_PAYMENT`, refund the order's settled
+ *   payment (`payments.refund`), whose AR credit note corrects the invoice,
+ *   and do NOT correct it as well (that credits the customer twice). Both cancel
+ *   doors (`cancelOrder` and `orders.cancelWithMoney`) refuse
+ *   `ORDER_CANCEL_CREDIT_NOTE_CONFLICT` (409) meanwhile. Named before
+ *   `HOLDS_MONEY`.
+ * - `HOLDS_MONEY`: `CANCEL` only. The order has been placed or parked and
+ *   still holds money, which a plain cancel would leave on it (the Admin
+ *   `cancelOrder` refuses it `ORDER_HOLDS_MONEY`). Cancel it with
+ *   `orders.cancelWithMoney`, or give its money back first: refund settled
+ *   payments, cancel card holds (a hold released at the payment provider
+ *   first where its payment method cannot). The value of spent gift cards
+ *   sold on it is never given back: only `orders.cancelWithMoney`'s
+ *   `retain` keeps it.
+ * - `ERP_LOCKED`: `SET_GOODWILL_ROUNDING` and `APPLY_GOODWILL_ROUNDING` only. The order is
+ *   settled or invoiced in the store's ERP, which holds its total: correct it there.
+ * - `LEAVES_MONEY_OVER`: `APPLY_GOODWILL_ROUNDING` only. The order is paid: rounding its total
+ *   down would leave the customer's money over the rounded total, which nothing pays back.
+ *   Refund the customer instead.
  * - `PERMISSION`: the order allows it and this caller may not. The only
  *   reason about the caller.
  */
@@ -147,13 +235,18 @@ export interface OrderStatusView {
         locked: boolean;
         reason: OrderLockReason | (string & {});
         /**
-         * Set only when the reason is `INVOICE`: the live standard invoice, else a
-         * voided standard one (voiding does not unlock the order).
+         * Set only when the reason is `INVOICE`: the live standard retail invoice,
+         * else the live accounts-receivable invoice billing the order, else a voided
+         * standard retail one (voiding a retail invoice does not unlock the order;
+         * an AR invoice locks only while it is live, so it is never voided here).
+         * `ledger` is `RETAIL` or `AR`: the ledger to correct it on
+         * (`documents.planCorrection`).
          */
         lockingInvoice: {
             id: string;
             number: string;
             voided: boolean;
+            ledger: 'RETAIL' | 'AR' | (string & {});
         } | null;
     };
     /** Null when the order's content may change; the message is the one every edit is refused with. */
@@ -192,6 +285,12 @@ export interface OrderStatusView {
      * fulfillment provider, and the store blocks shipping it again.
      */
     sourceFulfilled: boolean;
+    /**
+     * Why `sourceFulfilled` is true, in words for staff (the source platform and its order
+     * number), the same sentence the warehouse demand carries; null when it is false. Show it as
+     * sent rather than composing one.
+     */
+    sourceFulfilledReason: string | null;
     /** Set while the order is parked. */
     park: {
         reason: string | null;
@@ -207,6 +306,13 @@ export interface OrderStatusView {
     } | null;
     /** Empty when the order runs on every provider the store assigned. */
     providerFallbacks: OrderStatusProviderFallback[];
+    /**
+     * Set while a cancel (whole or by lines) waits for a credit note (`CANCEL` answers
+     * `CREDIT_NOTE_REQUIRED`, unless a more fundamental reason comes first).
+     * This SDK's document selects it, so against an engine older than the field
+     * `status` fails validation: deploy the engine first.
+     */
+    cancelCreditNote: OrderStatusCancelCreditNote | null;
     /**
      * The states a change-status menu lists, in the engine's order: without
      * `Cancelled` and `Modifying` (their own actions), without the cart phase,
@@ -216,7 +322,41 @@ export interface OrderStatusView {
     nextStates: string[];
     actions: OrderStatusAction[];
 }
-export declare const ORDER_STATUS_QUERY = "\n  query OrderStatus($orderId: ID!) {\n    orderStatus(orderId: $orderId) {\n      orderId\n      state\n      lifecycle {\n        status\n        payment\n        fulfillment\n        return\n      }\n      lock {\n        locked\n        reason\n        lockingInvoice {\n          id\n          number\n          voided\n        }\n      }\n      editBlock {\n        code\n        message\n      }\n      modifiable\n      deletable\n      releasableUnits\n      releaseAllowed\n      allocationBadge\n      fulfillmentCorrection {\n        blocked\n        code\n      }\n      sourceFulfilled\n      park {\n        reason\n      }\n      hold {\n        forReview\n        byApp\n      }\n      providerFallbacks {\n        kind\n        installationId\n        reason\n        since\n      }\n      nextStates\n      actions {\n        action\n        eligible\n        allowed\n        reasonCode\n      }\n    }\n  }\n";
+/**
+ * Why a cancel (whole or by lines) waits for a credit note: an invoice still
+ * bills the order, paid or not (cancelling would leave the invoice
+ * standing for revenue the order no longer has).
+ */
+export interface OrderStatusCancelCreditNote {
+    /** The `InvoiceCorrectionLedger` to correct the invoice on: `RETAIL` or `AR`. */
+    ledger: 'RETAIL' | 'AR' | (string & {});
+    /**
+     * What to do first. `CORRECT_INVOICE`: correct this invoice (credited in
+     * full; a `RETAIL` correction refunds along). `REFUND_PAYMENT`: refund the
+     * order's settled payment first (`payments.refund`): on an AR-invoiced
+     * order the refund issues the AR credit note that corrects the invoice, and
+     * correcting the invoice as well would credit the customer twice.
+     */
+    remedy: 'CORRECT_INVOICE' | 'REFUND_PAYMENT' | (string & {});
+    invoiceId: string;
+    invoiceNumber: string;
+    /**
+     * What the invoice still bills the order for, in minor units of
+     * `currencyCode`: its total (on `AR`, the order's share) less its credit
+     * notes.
+     */
+    uncredited: number;
+    /**
+     * What the order still holds, in minor units of `currencyCode`: its settled
+     * payments less what went back, or the receipts on its live
+     * accounts-receivable invoices, whichever is larger (a collected direct
+     * debit records the same money on both).
+     */
+    held: number;
+    /** The order's currency. */
+    currencyCode: string;
+}
+export declare const ORDER_STATUS_QUERY = "\n  query OrderStatus($orderId: ID!) {\n    orderStatus(orderId: $orderId) {\n      orderId\n      state\n      lifecycle {\n        status\n        payment\n        fulfillment\n        return\n      }\n      lock {\n        locked\n        reason\n        lockingInvoice {\n          id\n          number\n          voided\n          ledger\n        }\n      }\n      editBlock {\n        code\n        message\n      }\n      modifiable\n      deletable\n      releasableUnits\n      releaseAllowed\n      allocationBadge\n      fulfillmentCorrection {\n        blocked\n        code\n      }\n      sourceFulfilled\n      sourceFulfilledReason\n      park {\n        reason\n      }\n      hold {\n        forReview\n        byApp\n      }\n      providerFallbacks {\n        kind\n        installationId\n        reason\n        since\n      }\n      cancelCreditNote {\n        ledger\n        remedy\n        invoiceId\n        invoiceNumber\n        uncredited\n        held\n        currencyCode\n      }\n      nextStates\n      actions {\n        action\n        eligible\n        allowed\n        reasonCode\n      }\n    }\n  }\n";
 export interface OrderStatusModule {
     /**
      * Why the order is the way it is, and the actions open to this caller.
@@ -227,8 +367,14 @@ export interface OrderStatusModule {
      * the ORDER allows it (`eligible`) and whether THIS caller may take it now
      * (`allowed`), so a head can show an action greyed out with its reason.
      *
-     * Needs an engine that serves `orderStatus`; against an older one this call
-     * fails validation and nothing else does.
+     * An order a live accounts-receivable invoice bills is invoice-locked like a
+     * retail-invoiced one (`INVOICE_LOCKED`, `lock.lockingInvoice.ledger: 'AR'`).
+     *
+     * Needs an engine that serves `orderStatus` with `cancelCreditNote`,
+     * `lock.lockingInvoice.ledger` and `sourceFulfilledReason`; against an older
+     * one this call fails validation and nothing else does.
+     *
+     * @effect read
      */
     status(orderId: string, options?: Call): Promise<OrderStatusView>;
 }

package/dist/orders/status.js

@@ -14,6 +14,12 @@ export const ORDER_STATUS_ACTIONS = [
     'TRANSITION',
     'MARK_COMPLETED',
     'REOPEN',
+    'SET_PAYMENT_NOT_REQUIRED',
+    'SET_FULFILLMENT_HOLD',
+    'SET_GOODWILL_ROUNDING',
+    'SET_BILLING_FIELDS',
+    'APPLY_GOODWILL_ROUNDING',
+    'SET_PRICING_FIELDS',
 ];
 /** Why an action is not allowed, in the order the engine lists them. */
 export const ORDER_STATUS_REASON_CODES = [
@@ -27,6 +33,10 @@ export const ORDER_STATUS_REASON_CODES = [
     'SHOPPER_CART',
     'UNITS_SHIPPED',
     'ACTIVE_FULFILLMENT',
+    'CREDIT_NOTE_REQUIRED',
+    'HOLDS_MONEY',
+    'ERP_LOCKED',
+    'LEAVES_MONEY_OVER',
     'PERMISSION',
 ];
 export const ORDER_STATUS_QUERY = /* GraphQL */ `
@@ -47,6 +57,7 @@ export const ORDER_STATUS_QUERY = /* GraphQL */ `
           id
           number
           voided
+          ledger
         }
       }
       editBlock {
@@ -63,6 +74,7 @@ export const ORDER_STATUS_QUERY = /* GraphQL */ `
         code
       }
       sourceFulfilled
+      sourceFulfilledReason
       park {
         reason
       }
@@ -76,6 +88,15 @@ export const ORDER_STATUS_QUERY = /* GraphQL */ `
         reason
         since
       }
+      cancelCreditNote {
+        ledger
+        remedy
+        invoiceId
+        invoiceNumber
+        uncredited
+        held
+        currencyCode
+      }
       nextStates
       actions {
         action

package/dist/orders/surcharges.d.ts

@@ -133,6 +133,13 @@ export interface OverpaymentOption {
     available: boolean;
     code: string | null;
     message: string | null;
+    /**
+     * On an `accountCredit` option: where "credit the customer" lands in this store, its ONE
+     * customer-credit book. `AR` (unapplied cash on the AR ledger), `STORE_CREDIT` (the customer's
+     * store-credit wallet) or `NONE` (neither: the option is closed). Null on the other options and
+     * from an engine before it.
+     */
+    book?: string | null;
 }
 /** What a surcharge change would do to an order's money. Nothing was saved. */
 export interface SurchargeChangePreview {
@@ -190,5 +197,5 @@ export declare const UPDATE_ORDER_SURCHARGE_MUTATION = "\n  mutation UpdateOrder
 export declare const UPDATE_ORDER_SURCHARGE_WITH_OVERPAYMENT_MUTATION = "\n  mutation UpdateOrderSurchargeWithOverpayment(\n    $orderId: ID!\n    $surchargeId: ID!\n    $input: SurchargeInput!\n    $taxClass: String\n    $idempotencyKey: String\n    $overpayment: OrderOverpaymentChoice\n  ) {\n    updateOrderSurcharge(\n      orderId: $orderId\n      surchargeId: $surchargeId\n      input: $input\n      taxClass: $taxClass\n      idempotencyKey: $idempotencyKey\n      overpayment: $overpayment\n    ) {\n      \n  id\n  code\n  currencyCode\n  total\n  totalWithTax\n  surcharges {\n    id\n    description\n    sku\n    price\n    priceWithTax\n    taxRate\n  }\n\n    }\n  }\n";
 export declare const REMOVE_ORDER_SURCHARGE_MUTATION = "\n  mutation RemoveOrderSurcharge($orderId: ID!, $surchargeId: ID!, $idempotencyKey: String) {\n    removeOrderSurcharge(\n      orderId: $orderId\n      surchargeId: $surchargeId\n      idempotencyKey: $idempotencyKey\n    ) {\n      \n  id\n  code\n  currencyCode\n  total\n  totalWithTax\n  surcharges {\n    id\n    description\n    sku\n    price\n    priceWithTax\n    taxRate\n  }\n\n    }\n  }\n";
 export declare const REMOVE_ORDER_SURCHARGE_WITH_OVERPAYMENT_MUTATION = "\n  mutation RemoveOrderSurchargeWithOverpayment(\n    $orderId: ID!\n    $surchargeId: ID!\n    $idempotencyKey: String\n    $overpayment: OrderOverpaymentChoice\n  ) {\n    removeOrderSurcharge(\n      orderId: $orderId\n      surchargeId: $surchargeId\n      idempotencyKey: $idempotencyKey\n      overpayment: $overpayment\n    ) {\n      \n  id\n  code\n  currencyCode\n  total\n  totalWithTax\n  surcharges {\n    id\n    description\n    sku\n    price\n    priceWithTax\n    taxRate\n  }\n\n    }\n  }\n";
-export declare const PREVIEW_ORDER_SURCHARGE_CHANGE_QUERY = "\n  query PreviewOrderSurchargeChange($orderId: ID!, $change: OrderSurchargeChangeInput!) {\n    previewOrderSurchargeChange(orderId: $orderId, change: $change) {\n      currencyCode\n      totalBefore\n      totalAfter\n      overpayment {\n        amount\n        currencyCode\n        refund { available code message }\n        accountCredit { available code message }\n      }\n    }\n  }\n";
+export declare const PREVIEW_ORDER_SURCHARGE_CHANGE_QUERY = "\n  query PreviewOrderSurchargeChange($orderId: ID!, $change: OrderSurchargeChangeInput!) {\n    previewOrderSurchargeChange(orderId: $orderId, change: $change) {\n      currencyCode\n      totalBefore\n      totalAfter\n      overpayment {\n        amount\n        currencyCode\n        refund { available code message book }\n        accountCredit { available code message book }\n      }\n    }\n  }\n";
 export declare function createSurchargesModule(transport: Transport): SurchargesModule;

package/dist/orders/surcharges.js

@@ -1,3 +1,4 @@
+import { storeCreditAware } from '../payments/store-credit-fields.js';
 const SURCHARGED_ORDER_FIELDS = /* GraphQL */ `
   id
   code
@@ -120,7 +121,7 @@ export const REMOVE_ORDER_SURCHARGE_WITH_OVERPAYMENT_MUTATION = /* GraphQL */ `
     }
   }
 `;
-const OVERPAYMENT_OPTION_FIELDS = 'available code message';
+const OVERPAYMENT_OPTION_FIELDS = 'available code message book';
 export const PREVIEW_ORDER_SURCHARGE_CHANGE_QUERY = /* GraphQL */ `
   query PreviewOrderSurchargeChange($orderId: ID!, $change: OrderSurchargeChangeInput!) {
     previewOrderSurchargeChange(orderId: $orderId, change: $change) {
@@ -202,7 +203,7 @@ export function createSurchargesModule(transport) {
         },
         async preview(orderId, change, options) {
             const taxClass = taxClassVariable(options);
-            const data = await transport.graphql({
+            const data = await storeCreditAware(transport).graphql({
                 api: 'admin',
                 query: PREVIEW_ORDER_SURCHARGE_CHANGE_QUERY,
                 variables: {

package/dist/payments/account-credit.d.ts

@@ -33,6 +33,19 @@ export interface UnappliedCash {
     /** ISO-8601 with offset. */
     createdAt: string;
 }
+/**
+ * Money of an order's settled payments moved to the customer's store-credit wallet instead of a
+ * refund: one never-expiring ledger entry per payment it came from. Minor units of
+ * `currencyCode`, the order's own currency.
+ */
+export interface StoreCreditMove {
+    /** The customer's store-credit wallet (a stored-value account of kind `store_credit`). */
+    accountId: string;
+    amount: number;
+    currencyCode: string;
+    /** The ledger entries, one per payment the money came from. */
+    entryIds: string[];
+}
 export interface CreditOverpaymentInput {
     orderId: string;
     /**
@@ -123,6 +136,22 @@ export interface AccountCreditModule {
      * account refusals above.
      */
     creditOverpayment(input: CreditOverpaymentInput, options?: Call): Promise<UnappliedCash[]>;
+    /**
+     * The store-credit sibling of {@link creditOverpayment}, for a store whose customer-credit book
+     * is store credit (`storedValue.storeCreditSettings`): what the order holds over its bill moves
+     * to the customer's store-credit wallet, in the order's currency, one ledger entry per payment
+     * it came from. Same bounds and `ACCOUNT_CREDIT_*` refusals; an AR store is refused
+     * `STORE_CREDIT_STORE_KEEPS_ACCOUNTS` (use {@link creditOverpayment} there), a store without
+     * store credit `STORE_CREDIT_NOT_ENABLED` / `_NOT_GRANTED` / `_METHOD_REQUIRED`. A gift card's or
+     * store credit's payment is never moved (`STORE_CREDIT_STORED_VALUE_REFUND_INSTEAD`: refund it),
+     * and the customer must be reachable (`STORE_CREDIT_CUSTOMER_ANONYMOUS`,
+     * `STORED_VALUE_ACCOUNT_BLOCKED`). The overpayment is what the order's payments hold over what
+     * it BILLS, the larger of its total and its live invoices', as a plain refund of an invoiced order
+     * measures it. From then on that money is no longer the order's: `payments.refundPosition` takes
+     * it off `refundable` and `payments.position` no longer reports it as `overpaid`. Needs an
+     * engine with incentives sprint 8 PR 3.
+     */
+    creditOverpaymentToStoreCredit(input: CreditOverpaymentInput, options?: Call): Promise<StoreCreditMove>;
     /** A customer's unapplied cash in this store, oldest first. */
     list(customerId: string, options?: Call): Promise<UnappliedCash[]>;
     /**
@@ -159,6 +188,7 @@ export interface AccountCreditModule {
     onOrder(orderId: string, options?: Call): Promise<OrderMoneyOnAccount>;
 }
 export declare const CREDIT_ORDER_OVERPAYMENT_MUTATION = "\n  mutation CreditOrderOverpaymentToAccount(\n    $input: CreditOrderOverpaymentInput!\n    $idempotencyKey: String\n  ) {\n    creditOrderOverpaymentToAccount(input: $input, idempotencyKey: $idempotencyKey) {\n      \n  id\n  customerId\n  currencyCode\n  amount\n  applied\n  refunded\n  remaining\n  orderId\n  paymentId\n  receivedOn\n  reference\n  notes\n  createdAt\n\n    }\n  }\n";
+export declare const CREDIT_ORDER_OVERPAYMENT_TO_STORE_CREDIT_MUTATION = "\n  mutation CreditOrderOverpaymentToStoreCredit(\n    $input: CreditOrderOverpaymentInput!\n    $idempotencyKey: String\n  ) {\n    creditOrderOverpaymentToStoreCredit(input: $input, idempotencyKey: $idempotencyKey) {\n      accountId amount currencyCode entryIds\n    }\n  }\n";
 export declare const UNAPPLIED_CASH_QUERY = "\n  query ArUnappliedCash($customerId: ID!) {\n    arUnappliedCash(customerId: $customerId) {\n      \n  id\n  customerId\n  currencyCode\n  amount\n  applied\n  refunded\n  remaining\n  orderId\n  paymentId\n  receivedOn\n  reference\n  notes\n  createdAt\n\n    }\n  }\n";
 export declare const APPLY_UNAPPLIED_CASH_MUTATION = "\n  mutation ApplyArUnappliedCash($input: ApplyArUnappliedCashInput!, $idempotencyKey: String) {\n    applyArUnappliedCash(input: $input, idempotencyKey: $idempotencyKey) {\n      \n  id\n  customerId\n  currencyCode\n  amount\n  applied\n  refunded\n  remaining\n  orderId\n  paymentId\n  receivedOn\n  reference\n  notes\n  createdAt\n\n    }\n  }\n";
 export declare const REFUND_UNAPPLIED_CASH_MUTATION = "\n  mutation RefundArUnappliedCash($input: RefundArUnappliedCashInput!, $idempotencyKey: String) {\n    refundArUnappliedCash(input: $input, idempotencyKey: $idempotencyKey) {\n      id\n      total\n      state\n      method\n      transactionId\n      reason\n    }\n  }\n";

package/dist/payments/account-credit.js

@@ -1,3 +1,4 @@
+import { STORE_CREDIT_MOVE_FIELDS } from './store-credit-fields.js';
 const UNAPPLIED_CASH_FIELDS = /* GraphQL */ `
   id
   customerId
@@ -23,6 +24,16 @@ export const CREDIT_ORDER_OVERPAYMENT_MUTATION = /* GraphQL */ `
     }
   }
 `;
+export const CREDIT_ORDER_OVERPAYMENT_TO_STORE_CREDIT_MUTATION = /* GraphQL */ `
+  mutation CreditOrderOverpaymentToStoreCredit(
+    $input: CreditOrderOverpaymentInput!
+    $idempotencyKey: String
+  ) {
+    creditOrderOverpaymentToStoreCredit(input: $input, idempotencyKey: $idempotencyKey) {
+      ${STORE_CREDIT_MOVE_FIELDS}
+    }
+  }
+`;
 export const UNAPPLIED_CASH_QUERY = /* GraphQL */ `
   query ArUnappliedCash($customerId: ID!) {
     arUnappliedCash(customerId: $customerId) {
@@ -79,6 +90,14 @@ export function createAccountCreditModule(transport) {
             }, options);
             return data.creditOrderOverpaymentToAccount;
         },
+        async creditOverpaymentToStoreCredit(input, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: CREDIT_ORDER_OVERPAYMENT_TO_STORE_CREDIT_MUTATION,
+                variables: { input, idempotencyKey: options?.idempotencyKey },
+            }, options);
+            return data.creditOrderOverpaymentToStoreCredit;
+        },
         async list(customerId, options) {
             const data = await transport.graphql({ api: 'admin', query: UNAPPLIED_CASH_QUERY, variables: { customerId } }, options);
             return data.arUnappliedCash;