@sixtyninecommerce/admin 0.11.0 → 0.12.0

package/dist/orders/cancel-with-money.d.ts

@@ -19,6 +19,16 @@ export interface CancelWithMoneyCall extends Call {
     overpayment?: OrderOverpaymentChoice;
     /** The settled money stays on the cancelled order (with a `reason`). */
     retain?: boolean;
+    /**
+     * With `overpayment: 'ACCOUNT_CREDIT'` in a store whose book is store credit (the preview's
+     * `accountCredit.book` `STORE_CREDIT`): whether the customer expressly agreed to store credit
+     * instead of a refund to their payment (EU consumer law, CRD art. 13(1)), as staff recorded it.
+     * The move records it on its ledger entries (`StoredValueEntry.customerAgreed`); never a
+     * condition, nothing is refused for it. Part of the request: a repeat under the same key sends
+     * the same answer. Sent only when given; an engine before the field (incentives sprint 8 PR 6a)
+     * refuses a call that gives it.
+     */
+    customerAgreed?: boolean;
 }
 /** What a cancel with a money decision did. */
 /**

package/dist/orders/cancel-with-money.js

@@ -1,4 +1,5 @@
 import { creditNotedAware } from '../payments/credit-noted-fields.js';
+import { customerAgreedVariable } from '../payments/customer-consent.js';
 import { STORE_CREDIT_MOVE_FIELDS, storeCreditAware } from '../payments/store-credit-fields.js';
 const OPTION_FIELDS = /* GraphQL */ `
   available
@@ -127,6 +128,7 @@ export function createOrderCancelWithMoneyModule(transport) {
                         reason: options?.reason,
                         overpayment: options?.overpayment,
                         retain: options?.retain,
+                        customerAgreed: customerAgreedVariable(options?.customerAgreed),
                     },
                     idempotencyKey: options?.idempotencyKey,
                 },

package/dist/orders/commit-edit.d.ts

@@ -72,12 +72,28 @@ export interface CommitOrderEditCall extends Call {
      * Part of the request: a retry under the same key re-sends the same choice.
      */
     overpaymentChoice?: OrderOverpaymentChoice;
+    /**
+     * With `overpaymentChoice: 'ACCOUNT_CREDIT'` in a store whose book is store credit (the plan's
+     * `overpayment.accountCredit.book` `STORE_CREDIT`): whether the customer expressly agreed to
+     * store credit instead of a refund to their payment (EU consumer law, CRD art. 13(1)), as staff
+     * recorded it. The move records it on its ledger entries (`StoredValueEntry.customerAgreed`);
+     * never a condition, nothing is refused for it. Part of the request like the choice: a retry
+     * under the same key re-sends the same answer, and another answer under it is
+     * `IDEMPOTENCY_CONFLICT`. Sent only when given; an engine before the field (incentives sprint 8
+     * PR 6a) refuses a call that gives it.
+     */
+    customerAgreed?: boolean;
 }
 /**
  * Its own document on purpose: `commitOrderEdit` exists only on an engine with the order-edit
  * commit, so on an older one this call alone fails validation and no other order call does.
  */
 export declare const COMMIT_ORDER_EDIT_MUTATION = "\n  mutation CommitOrderEdit(\n    $orderId: ID!\n    $diff: OrderEditDiffInput!\n    $expectedPlanHash: String!\n    $idempotencyKey: String!\n    $overpaymentChoice: OrderOverpaymentChoice\n  ) {\n    commitOrderEdit(\n      orderId: $orderId\n      diff: $diff\n      expectedPlanHash: $expectedPlanHash\n      idempotencyKey: $idempotencyKey\n      overpaymentChoice: $overpaymentChoice\n    ) {\n      order {\n        id\n        code\n        state\n        currencyCode\n        totalWithTax\n      }\n      plan {\n        orderId\n        planHash\n        orderVersion\n        steps {\n          kind\n          input\n          moneyEffect\n        }\n        refund {\n          paymentId\n          amount\n        }\n        overpayment {\n          amount\n          currencyCode\n          surchargeIds\n          refund {\n            available\n            code\n            message\n            book\n          }\n          accountCredit {\n            available\n            code\n            message\n            book\n          }\n          refundWhenChosen {\n            paymentId\n            amount\n          }\n        }\n        returnState\n        blockers {\n          code\n          message\n          details\n        }\n        notices {\n          code\n          message\n          details\n        }\n        payment {\n          collected\n          reason\n          method\n        }\n        preview {\n          currencyCode\n          subTotal\n          subTotalWithTax\n          shipping\n          shippingWithTax\n          surcharges\n          surchargesWithTax\n          total\n          totalWithTax\n          taxSummary {\n            description\n            taxRate\n            taxBase\n            taxTotal\n          }\n          totalWithTaxBefore\n        }\n      }\n      refund {\n        id\n        state\n        total\n        paymentId\n      }\n      overpayment {\n        choice\n        amount\n        currencyCode\n        unappliedCashIds\n        storeCredit { accountId amount currencyCode entryIds }\n      }\n    }\n  }\n";
+/**
+ * The same, declaring the customer's answer to store credit: sent only by a call that states it,
+ * so an engine before the argument still takes every call that does not.
+ */
+export declare const COMMIT_ORDER_EDIT_WITH_CONSENT_MUTATION: string;
 export interface OrderCommitEditModule {
     /**
      * Carry out an edit of a placed order as its plan (`planEdit`) states it, once. Needs

package/dist/orders/commit-edit.js

@@ -1,4 +1,5 @@
 import { idempotencyKey as mintIdempotencyKey } from '@sixtyninecommerce/core';
+import { customerAgreedVariable, withCustomerAgreed } from '../payments/customer-consent.js';
 import { STORE_CREDIT_MOVE_FIELDS, storeCreditAware } from '../payments/store-credit-fields.js';
 /**
  * Its own document on purpose: `commitOrderEdit` exists only on an engine with the order-edit
@@ -111,14 +112,25 @@ export const COMMIT_ORDER_EDIT_MUTATION = /* GraphQL */ `
     }
   }
 `;
+/**
+ * The same, declaring the customer's answer to store credit: sent only by a call that states it,
+ * so an engine before the argument still takes every call that does not.
+ */
+export const COMMIT_ORDER_EDIT_WITH_CONSENT_MUTATION = withCustomerAgreed(COMMIT_ORDER_EDIT_MUTATION, {
+    declaration: '$overpaymentChoice: OrderOverpaymentChoice',
+    argument: 'overpaymentChoice: $overpaymentChoice',
+});
 export function createOrderCommitEditModule(transport) {
     return {
         async commitEdit(orderId, diff, options) {
             const key = options.idempotencyKey ?? mintIdempotencyKey();
+            const customerAgreed = customerAgreedVariable(options.customerAgreed);
             try {
                 const data = await storeCreditAware(transport).graphql({
                     api: 'admin',
-                    query: COMMIT_ORDER_EDIT_MUTATION,
+                    query: customerAgreed === undefined
+                        ? COMMIT_ORDER_EDIT_MUTATION
+                        : COMMIT_ORDER_EDIT_WITH_CONSENT_MUTATION,
                     // The diff goes out as given, never normalised (see `planEdit`): left out, `null` and
                     // a value are three different requests.
                     variables: {
@@ -130,6 +142,7 @@ export function createOrderCommitEditModule(transport) {
                         ...(options.overpaymentChoice !== undefined
                             ? { overpaymentChoice: options.overpaymentChoice }
                             : {}),
+                        ...(customerAgreed !== undefined ? { customerAgreed } : {}),
                     },
                 }, { ...options, idempotencyKey: key });
                 return { ...data.commitOrderEdit, idempotencyKey: key };

package/dist/orders/deposit-policy.d.ts

@@ -32,7 +32,9 @@ export interface OrderDepositPolicy {
     /**
      * The store-wide switch. Off: a payment must cover the whole outstanding
      * amount (`payments.record` refuses a part payment `DEPOSITS_NOT_ENABLED`) and
-     * no order can be parked.
+     * no order can be parked. Stored value (a gift card or store credit) is the
+     * exception: it may pay part of an order still arranging payment, and the
+     * order is placed only once its money covers it.
      */
     enabled: boolean;
     /**

package/dist/orders/index.d.ts

@@ -14,6 +14,7 @@ import { type OrderLinePricePreviewModule } from './line-price-preview.js';
 import { type OrderListModule } from './list.js';
 import { type ManualDiscountsModule } from './manual-discounts.js';
 import { type OrderManualPricingModule } from './manual-pricing.js';
+import { type OrderMoneyViewModule } from './money-view.js';
 import { type OrderEntryModule } from './order-entry.js';
 import { type OrderParcelChargeModule } from './parcel-charge.js';
 import { type OrderPlanEditModule } from './plan-edit.js';
@@ -28,7 +29,7 @@ export type { ClonedDraft, DraftAddLineInput, DraftAddressDefault, DraftAddressD
 export { DraftInsufficientStockError } from './drafts.js';
 export type { FulfillmentQuantityCorrection, FulfillmentQuantityCorrectionInput, FulfillmentQuantityCorrectionLine, FulfillmentUnitDisposition, OrderCustomerAssignment, OrderFieldsModule, OrderGoodwillRounding, OrderNote, OrderNoteInput, OrderNotesModule, OrderPurchaseOrderNumber, } from './fields.js';
 export type { FulfillmentHoldInput, OrderLifecycleModule, OrderLifecycleRecord, } from './lifecycle.js';
-export type { OrderListFilter, OrderListModule, OrderListOptions, OrderListSort, OrderListSortField, OrderSummary, RecentOrder, RecentOrderLine, RecentOrdersOptions, } from './list.js';
+export type { OrderBillableTotals, OrderListFilter, OrderListModule, OrderListOptions, OrderListSort, OrderListSortField, OrderSummary, RecentOrder, RecentOrderLine, RecentOrdersOptions, } from './list.js';
 export { MAX_ORDER_LIST_TAKE, MAX_RECENT_ORDERS, ORDER_LIST_SORT_FIELDS } from './list.js';
 export type { DiscountPolicy, DiscountPolicyInput, DiscountPolicyModule, DiscountReason, DiscountReasonInput, DiscountReasonsModule, ManualDiscountsModule, OrderManualDiscount, } from './manual-discounts.js';
 export type { ExternalLinePriceBasis, ExternalOrder, ExternalOrderAddressInput, ExternalOrderCall, ExternalOrderCatalogLine, ExternalOrderExternalLine, ExternalOrderFulfilment, ExternalOrderInput, ExternalOrderLine, ExternalOrderLineInput, ExternalOrderSurcharge, ExternalOrderSurchargeInput, ExternalOrderTargetState, ExternalOrderTaxLine, } from './order-entry.js';
@@ -84,7 +85,7 @@ export interface OrderSettlement {
  * The manual pricing doors (`setLinePrices`, `setOneTimeDiscounts`) sit there too, beside their
  * read twin `previewLinePrices`, which prices the same changes without saving them.
  */
-export interface OrdersModule extends OrderEntryModule, OrderGetModule, OrderListModule, OrderParcelChargeModule, OrderLinePricePreviewModule, OrderManualPricingModule, OrderPlanEditModule, OrderCommitEditModule, OrderCancelWithMoneyModule, OrderLifecycleModule, OrderFieldsModule, OrderStatusModule {
+export interface OrdersModule extends OrderEntryModule, OrderGetModule, OrderListModule, OrderParcelChargeModule, OrderLinePricePreviewModule, OrderManualPricingModule, OrderPlanEditModule, OrderCommitEditModule, OrderCancelWithMoneyModule, OrderLifecycleModule, OrderFieldsModule, OrderStatusModule, OrderMoneyViewModule {
     surcharges: SurchargesModule;
     /**
      * The draft-order builder: staff create a draft, set its customer, lines (with manual prices
@@ -242,8 +243,9 @@ export interface OrdersModule extends OrderEntryModule, OrderGetModule, OrderLis
      */
     unpark(orderId: string, options?: Call): Promise<PaidOrder>;
     /**
-     * What the order has actually been paid, what its credit notes took off and what it still owes
-     * (`payments.position`'s answer). Needs `ReadOrder`.
+     * What the order has actually been paid, what its credit notes took off, what it still owes
+     * and what its settled money must reach before it counts as paid (`payments.position`'s
+     * answer). Needs `ReadOrder`.
      *
      * @effect read
      */
@@ -252,7 +254,10 @@ export interface OrdersModule extends OrderEntryModule, OrderGetModule, OrderLis
      * Move a fully paid order to `PaymentSettled`. Needs `UpdateOrder`.
      *
      * Refuses `COVERAGE_INSUFFICIENT` while the order's SETTLED money does not
-     * cover its total, with the position attached. Settled, not covered: an
+     * cover what it must be paid (`payable` on the position: its total, less what
+     * a live invoice's credit notes took off it; an order paid down to what its
+     * invoice bills net of its credit notes IS paid), with the position attached.
+     * Settled, not covered: an
      * authorization is permission to take money, not money, so an order whose
      * remainder is merely authorized settles once that authorization is captured
      * where it stands (`settlePayment` on the Admin API): the capture settles it,
@@ -280,17 +285,23 @@ export interface OrdersModule extends OrderEntryModule, OrderGetModule, OrderLis
      *
      * Calling this on an order the platform ALREADY settled succeeds rather than
      * refusing. Expect that to be the common case: the engine settles an order as
-     * soon as its settled payments cover its total, so recording the payment that
-     * clears a deposit usually settles the order on its own, and this call is then
-     * a confirmation.
+     * soon as its settled payments cover what it must be paid, so recording the
+     * payment that clears a deposit usually settles the order on its own, and this
+     * call is then a confirmation. A credit note that alone makes an order paid
+     * moves nothing: a held order waits for this call.
      *
      * So do not wait on a settle CALL to learn that a deposit was paid off — in
      * the ordinary flow nobody makes one. The close signal is the platform event
      * `payment.partial_recorded` with `outstanding_after: 0`, on the payment that
      * cleared the balance. That figure nets settled PLUS authorized money, so it
-     * means fully COVERED; "fully settled" is `settled >= total` on the position,
+     * means fully COVERED; "fully settled" is `settled >= payable` on the position,
      * which is what this method requires. For money recorded through
-     * `payments.record` the two coincide — it only creates settled payments.
+     * `payments.record` the two coincide — it only creates settled payments —
+     * except on an order whose credit notes lowered what it must be paid, which
+     * settles with `outstanding_after` still naming the credited part
+     * (`order.settlement_completed` then carries `credit_noted`).
+     *
+     * @effect money
      */
     settle(orderId: string, options?: Call & {
         fulfil?: boolean;
@@ -307,5 +318,5 @@ export interface OrdersModule extends OrderEntryModule, OrderGetModule, OrderLis
 export declare const PARK_ORDER_MUTATION = "\n  mutation ParkOrder($orderId: ID!, $reason: String, $idempotencyKey: String) {\n    parkOrder(orderId: $orderId, reason: $reason, idempotencyKey: $idempotencyKey) {\n      id\n      code\n      state\n      currencyCode\n      total\n      totalWithTax\n    }\n  }\n";
 export declare const UNPARK_ORDER_MUTATION = "\n  mutation UnparkOrder($orderId: ID!, $idempotencyKey: String) {\n    unparkOrder(orderId: $orderId, idempotencyKey: $idempotencyKey) {\n      id\n      code\n      state\n      currencyCode\n      total\n      totalWithTax\n    }\n  }\n";
 export declare const SETTLE_ORDER_MUTATION = "\n  mutation SettleOrder($orderId: ID!, $fulfil: Boolean!, $idempotencyKey: String) {\n    settleOrder(orderId: $orderId, fulfil: $fulfil, idempotencyKey: $idempotencyKey) {\n      \n  order {\n    id\n    code\n    state\n    currencyCode\n    total\n    totalWithTax\n  }\n  position {\n    total\n    covered\n    settled\n    authorized\n    refunded\n    outstanding\n    overpaid\n    availableToCharge\n  }\n  fulfilRequested\n\n    }\n  }\n";
-export declare const ORDER_POSITION_QUERY = "\n  query OrderPosition($orderId: ID!) {\n    orderPaymentPosition(orderId: $orderId) {\n      total\n      covered\n      settled\n      authorized\n      refunded\n      creditNoted\n      owed\n      outstanding\n      overpaid\n      availableToCharge\n    }\n  }\n";
+export declare const ORDER_POSITION_QUERY = "\n  query OrderPosition($orderId: ID!) {\n    orderPaymentPosition(orderId: $orderId) {\n      total\n      covered\n      settled\n      authorized\n      refunded\n      creditNoted\n      owed\n      payable\n      outstanding\n      overpaid\n      availableToCharge\n    }\n  }\n";
 export declare function createOrdersModule(transport: Transport): OrdersModule;

package/dist/orders/index.js

@@ -1,5 +1,5 @@
 import { NotFoundError } from '@sixtyninecommerce/core';
-import { creditNotedAware } from '../payments/credit-noted-fields.js';
+import { creditNotedAware, payableAware } from '../payments/credit-noted-fields.js';
 import { bulkOrders, deleteOrder, readOrderBulkRun, } from './bulk.js';
 import { createOrderCancelWithMoneyModule, } from './cancel-with-money.js';
 import { createOrderCommitEditModule } from './commit-edit.js';
@@ -12,6 +12,7 @@ import { createOrderLinePricePreviewModule, } from './line-price-preview.js';
 import { createOrderListModule } from './list.js';
 import { createManualDiscountsModule } from './manual-discounts.js';
 import { createOrderManualPricingModule } from './manual-pricing.js';
+import { createOrderMoneyViewModule } from './money-view.js';
 import { createOrderEntryModule } from './order-entry.js';
 import { createOrderParcelChargeModule } from './parcel-charge.js';
 import { createOrderPlanEditModule } from './plan-edit.js';
@@ -97,6 +98,7 @@ export const ORDER_POSITION_QUERY = /* GraphQL */ `
       refunded
       creditNoted
       owed
+      payable
       outstanding
       overpaid
       availableToCharge
@@ -118,6 +120,7 @@ export function createOrdersModule(transport) {
         ...createOrderLifecycleModule(transport),
         ...createOrderFieldsModule(transport),
         ...createOrderStatusModule(transport),
+        ...createOrderMoneyViewModule(transport),
         surcharges: createSurchargesModule(transport),
         drafts: createOrderDraftsModule(transport, getModule),
         manualDiscounts: createManualDiscountsModule(transport),
@@ -170,7 +173,7 @@ export function createOrdersModule(transport) {
         },
         async paymentPosition(orderId, options) {
             // The credit fields fall away on an engine before them: the position itself still reads.
-            const data = await creditNotedAware(transport).graphql({ api: 'admin', query: ORDER_POSITION_QUERY, variables: { orderId } }, options);
+            const data = await creditNotedAware(payableAware(transport)).graphql({ api: 'admin', query: ORDER_POSITION_QUERY, variables: { orderId } }, options);
             return data.orderPaymentPosition;
         },
         async settle(orderId, options) {

package/dist/orders/list.d.ts

@@ -11,8 +11,17 @@ export interface OrderSummary {
     id: string;
     code: string;
     state: string;
+    /** Core's total excl. VAT, before a staff rounding. */
     total: number;
+    /** Core's total incl. VAT, before a staff rounding. Print {@link billableTotals} instead. */
     totalWithTax: number;
+    /**
+     * What the order bills: `total` incl. VAT is `totalWithTax` with a staff (goodwill) rounding
+     * folded in, the figure the order page (`moneyView.total`), the invoice and the payment carry;
+     * `totalExcludingTax` the same excl. VAT. Print these as the order's total. `null` from an
+     * engine before the field: print `totalWithTax` / `total` then.
+     */
+    billableTotals: OrderBillableTotals | null;
     currencyCode: string;
     /** ISO-8601; null for an order not placed yet (a cart, a draft). */
     orderPlacedAt: string | null;
@@ -59,6 +68,13 @@ export interface OrderSummary {
      */
     redacted?: true;
 }
+/** What an order bills, a staff rounding included (`Order.billableTotals`). Minor units. */
+export interface OrderBillableTotals {
+    /** Incl. VAT; equals the order's `moneyView.total`. */
+    total: number;
+    /** Excl. VAT; equals the order's `moneyView.totalExcludingTax`. */
+    totalExcludingTax: number;
+}
 /**
  * Which orders a list holds. Every key narrows it; several keys are combined with AND. An empty
  * list (`state: []`) matches nothing.
@@ -118,10 +134,10 @@ export interface OrderListOptions extends Call {
 }
 /** The engine's `adminListQueryLimit`: a larger page is refused. */
 export declare const MAX_ORDER_LIST_TAKE = 1000;
-export declare const ORDER_SUMMARY_FIELDS = "\n  id\n  code\n  state\n  total\n  totalWithTax\n  currencyCode\n  orderPlacedAt\n  customer {\n    id\n    firstName\n    lastName\n    emailAddress\n    addresses {\n      company\n      defaultBillingAddress\n      defaultShippingAddress\n    }\n  }\n  billingAddress {\n    company\n  }\n  shippingAddress {\n    company\n  }\n  lines {\n    quantity\n  }\n  payments {\n    id\n    state\n  }\n  customFields {\n    externalOrderId\n    externalPlatform\n    isGift\n    paymentStatus\n    fulfillmentStatus\n    returnStatus\n    lifecycleStatus\n    statusOverrides {\n      fulfillmentHoldReason\n    }\n  }\n";
-export declare const ORDERS_LIST_QUERY = "\n  query OrdersList($options: OrderListOptions) {\n    orders(options: $options) {\n      items {\n        \n  id\n  code\n  state\n  total\n  totalWithTax\n  currencyCode\n  orderPlacedAt\n  customer {\n    id\n    firstName\n    lastName\n    emailAddress\n    addresses {\n      company\n      defaultBillingAddress\n      defaultShippingAddress\n    }\n  }\n  billingAddress {\n    company\n  }\n  shippingAddress {\n    company\n  }\n  lines {\n    quantity\n  }\n  payments {\n    id\n    state\n  }\n  customFields {\n    externalOrderId\n    externalPlatform\n    isGift\n    paymentStatus\n    fulfillmentStatus\n    returnStatus\n    lifecycleStatus\n    statusOverrides {\n      fulfillmentHoldReason\n    }\n  }\n\n      }\n      totalItems\n    }\n  }\n";
+export declare const ORDER_SUMMARY_FIELDS = "\n  \n  id\n  code\n  state\n  total\n  totalWithTax\n  currencyCode\n  orderPlacedAt\n  customer {\n    id\n    firstName\n    lastName\n    emailAddress\n    addresses {\n      company\n      defaultBillingAddress\n      defaultShippingAddress\n    }\n  }\n  billingAddress {\n    company\n  }\n  shippingAddress {\n    company\n  }\n  lines {\n    quantity\n  }\n  payments {\n    id\n    state\n  }\n  customFields {\n    externalOrderId\n    externalPlatform\n    isGift\n    paymentStatus\n    fulfillmentStatus\n    returnStatus\n    lifecycleStatus\n    statusOverrides {\n      fulfillmentHoldReason\n    }\n  }\n\n  billableTotals {\n    total\n    totalExcludingTax\n  }\n";
+export declare const ORDERS_LIST_QUERY = "\n  query OrdersList($options: OrderListOptions) {\n    orders(options: $options) {\n      items {\n        \n  \n  id\n  code\n  state\n  total\n  totalWithTax\n  currencyCode\n  orderPlacedAt\n  customer {\n    id\n    firstName\n    lastName\n    emailAddress\n    addresses {\n      company\n      defaultBillingAddress\n      defaultShippingAddress\n    }\n  }\n  billingAddress {\n    company\n  }\n  shippingAddress {\n    company\n  }\n  lines {\n    quantity\n  }\n  payments {\n    id\n    state\n  }\n  customFields {\n    externalOrderId\n    externalPlatform\n    isGift\n    paymentStatus\n    fulfillmentStatus\n    returnStatus\n    lifecycleStatus\n    statusOverrides {\n      fulfillmentHoldReason\n    }\n  }\n\n  billableTotals {\n    total\n    totalExcludingTax\n  }\n\n      }\n      totalItems\n    }\n  }\n";
 export declare const ORDERS_COUNT_QUERY = "\n  query OrdersCount($options: OrderListOptions) {\n    orders(options: $options) {\n      totalItems\n    }\n  }\n";
-export declare const CUSTOMER_ORDERS_QUERY = "\n  query CustomerOrders($id: ID!, $options: OrderListOptions) {\n    customer(id: $id) {\n      id\n      orders(options: $options) {\n        items {\n          \n  id\n  code\n  state\n  total\n  totalWithTax\n  currencyCode\n  orderPlacedAt\n  customer {\n    id\n    firstName\n    lastName\n    emailAddress\n    addresses {\n      company\n      defaultBillingAddress\n      defaultShippingAddress\n    }\n  }\n  billingAddress {\n    company\n  }\n  shippingAddress {\n    company\n  }\n  lines {\n    quantity\n  }\n  payments {\n    id\n    state\n  }\n  customFields {\n    externalOrderId\n    externalPlatform\n    isGift\n    paymentStatus\n    fulfillmentStatus\n    returnStatus\n    lifecycleStatus\n    statusOverrides {\n      fulfillmentHoldReason\n    }\n  }\n\n        }\n        totalItems\n      }\n    }\n  }\n";
+export declare const CUSTOMER_ORDERS_QUERY = "\n  query CustomerOrders($id: ID!, $options: OrderListOptions) {\n    customer(id: $id) {\n      id\n      orders(options: $options) {\n        items {\n          \n  \n  id\n  code\n  state\n  total\n  totalWithTax\n  currencyCode\n  orderPlacedAt\n  customer {\n    id\n    firstName\n    lastName\n    emailAddress\n    addresses {\n      company\n      defaultBillingAddress\n      defaultShippingAddress\n    }\n  }\n  billingAddress {\n    company\n  }\n  shippingAddress {\n    company\n  }\n  lines {\n    quantity\n  }\n  payments {\n    id\n    state\n  }\n  customFields {\n    externalOrderId\n    externalPlatform\n    isGift\n    paymentStatus\n    fulfillmentStatus\n    returnStatus\n    lifecycleStatus\n    statusOverrides {\n      fulfillmentHoldReason\n    }\n  }\n\n  billableTotals {\n    total\n    totalExcludingTax\n  }\n\n        }\n        totalItems\n      }\n    }\n  }\n";
 /** The Admin API's `OrderFilterParameter` for a typed filter; unknown keys are refused. */
 export declare function toOrderFilterParameter(filter: OrderListFilter | undefined): Record<string, unknown>;
 export interface OrderListModule {
@@ -205,8 +221,13 @@ export interface RecentOrder {
     code: string;
     /** ISO-8601. */
     orderPlacedAt: string;
-    /** Minor units of `currencyCode`. */
+    /** Minor units of `currencyCode`: core's total, before a staff rounding. */
     totalWithTax: number;
+    /**
+     * What the order bills (a staff rounding folded in): print `billableTotals.total`. `null` from
+     * an engine before the field: print `totalWithTax` then.
+     */
+    billableTotals: OrderBillableTotals | null;
     currencyCode: string;
     lines: RecentOrderLine[];
 }
@@ -214,7 +235,7 @@ export interface RecentOrdersOptions extends Call {
     /** How many orders, 1 to {@link MAX_RECENT_ORDERS}; 5 when omitted. */
     take?: number;
 }
-export declare const CUSTOMER_RECENT_ORDERS_QUERY = "\n  query CustomerRecentOrders($id: ID!, $options: OrderListOptions) {\n    customer(id: $id) {\n      id\n      orders(options: $options) {\n        items {\n          id\n          code\n          orderPlacedAt\n          totalWithTax\n          currencyCode\n          lines {\n            id\n            quantity\n            listPriceIncludesTax\n            productVariant {\n              id\n              name\n              sku\n              product {\n                id\n                name\n              }\n            }\n            customFields {\n              unitPriceOverride\n              unitPriceImported\n            }\n          }\n        }\n        totalItems\n      }\n    }\n  }\n";
+export declare const CUSTOMER_RECENT_ORDERS_QUERY = "\n  query CustomerRecentOrders($id: ID!, $options: OrderListOptions) {\n    customer(id: $id) {\n      id\n      orders(options: $options) {\n        items {\n          id\n          code\n          orderPlacedAt\n          totalWithTax\n          billableTotals {\n            total\n            totalExcludingTax\n          }\n          currencyCode\n          lines {\n            id\n            quantity\n            listPriceIncludesTax\n            productVariant {\n              id\n              name\n              sku\n              product {\n                id\n                name\n              }\n            }\n            customFields {\n              unitPriceOverride\n              unitPriceImported\n            }\n          }\n        }\n        totalItems\n      }\n    }\n  }\n";
 /**
  * A customer's last placed orders, newest first, each with its lines, as `customers.recentOrders`
  * reads them; `null` when the store holds no customer with that id.

package/dist/orders/list.js

@@ -13,7 +13,8 @@ export const ORDER_LIST_SORT_FIELDS = [
 /** The engine's `adminListQueryLimit`: a larger page is refused. */
 export const MAX_ORDER_LIST_TAKE = 1000;
 const DEFAULT_TAKE = 25;
-export const ORDER_SUMMARY_FIELDS = /* GraphQL */ `
+/** {@link ORDER_SUMMARY_FIELDS} as an engine before `Order.billableTotalWithTax` accepts it. */
+const ORDER_SUMMARY_FIELDS_BEFORE_BILLABLE = /* GraphQL */ `
   id
   code
   state
@@ -58,6 +59,15 @@ export const ORDER_SUMMARY_FIELDS = /* GraphQL */ `
     }
   }
 `;
+export const ORDER_SUMMARY_FIELDS = /* GraphQL */ `
+  ${ORDER_SUMMARY_FIELDS_BEFORE_BILLABLE}
+  billableTotals {
+    total
+    totalExcludingTax
+  }
+`;
+// Each document is spelled out with a named constant inside, never built by a function: the
+// GraphQL cost spec (`graphql-cost-fits-repo.spec.ts`) resolves `${NAME}` statically.
 export const ORDERS_LIST_QUERY = /* GraphQL */ `
   query OrdersList($options: OrderListOptions) {
     orders(options: $options) {
@@ -68,6 +78,16 @@ export const ORDERS_LIST_QUERY = /* GraphQL */ `
     }
   }
 `;
+const ORDERS_LIST_QUERY_BEFORE_BILLABLE = /* GraphQL */ `
+  query OrdersList($options: OrderListOptions) {
+    orders(options: $options) {
+      items {
+        ${ORDER_SUMMARY_FIELDS_BEFORE_BILLABLE}
+      }
+      totalItems
+    }
+  }
+`;
 export const ORDERS_COUNT_QUERY = /* GraphQL */ `
   query OrdersCount($options: OrderListOptions) {
     orders(options: $options) {
@@ -88,6 +108,44 @@ export const CUSTOMER_ORDERS_QUERY = /* GraphQL */ `
     }
   }
 `;
+const CUSTOMER_ORDERS_QUERY_BEFORE_BILLABLE = /* GraphQL */ `
+  query CustomerOrders($id: ID!, $options: OrderListOptions) {
+    customer(id: $id) {
+      id
+      orders(options: $options) {
+        items {
+          ${ORDER_SUMMARY_FIELDS_BEFORE_BILLABLE}
+        }
+        totalItems
+      }
+    }
+  }
+`;
+/**
+ * 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 (the purchasing module's rule).
+ */
+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));
+}
+/**
+ * Sends the current document; only an engine that refuses it as naming an unknown field (one
+ * before `Order.billableTotals`, services deploy separately) is sent the one before it.
+ */
+async function withBillableFallback(send) {
+    try {
+        return await send(false);
+    }
+    catch (error) {
+        if (!isUnknownFieldRejection(error))
+            throw error;
+        return send(true);
+    }
+}
 function invalid(message) {
     return new ValidationError({
         code: 'INVALID_ORDER_LIST_OPTIONS',
@@ -238,17 +296,22 @@ async function listOrders(read, options) {
     const sort = toOrderSort(options?.sort);
     const fetchPage = async (pageSkip) => {
         const redaction = redactionWatcher();
-        const list = await read({
+        const variables = {
             options: {
                 skip: pageSkip,
                 take,
                 ...(Object.keys(filter).length > 0 ? { filter, filterOperator: 'AND' } : {}),
                 ...(sort ? { sort } : {}),
             },
-        }, redaction.onExtensions);
+        };
+        const list = await withBillableFallback((beforeBillable) => read(variables, redaction.onExtensions, beforeBillable));
         if (list === null)
             return null;
-        return pageFromVendureList({ items: list.items.map((item) => redaction.mark(item)), totalItems: list.totalItems }, pageSkip, take, async (cursor) => {
+        const items = list.items.map((item) => ({
+            ...item,
+            billableTotals: item.billableTotals ?? null,
+        }));
+        return pageFromVendureList({ items: items.map((item) => redaction.mark(item)), totalItems: list.totalItems }, pageSkip, take, async (cursor) => {
             const next = await fetchPage(readOffsetCursor(cursor));
             if (next === null) {
                 throw new UpstreamError({
@@ -266,8 +329,9 @@ async function listOrders(read, options) {
 export function createOrderListModule(transport) {
     return {
         async list(options) {
-            const page = await listOrders(async (variables, onExtensions) => {
-                const data = await transport.graphql({ api: 'admin', query: ORDERS_LIST_QUERY, variables, onExtensions }, options);
+            const page = await listOrders(async (variables, onExtensions, beforeBillable) => {
+                const query = beforeBillable ? ORDERS_LIST_QUERY_BEFORE_BILLABLE : ORDERS_LIST_QUERY;
+                const data = await transport.graphql({ api: 'admin', query, variables, onExtensions }, options);
                 return data.orders;
             }, options);
             // `read` above never answers null: the store's own list always exists.
@@ -298,10 +362,10 @@ export function createOrderListModule(transport) {
  * as `orders.list`, or `null` when the store holds no customer with that id.
  */
 export async function listCustomerOrders(transport, customerId, options) {
-    return listOrders(async (variables, onExtensions) => {
+    return listOrders(async (variables, onExtensions, beforeBillable) => {
         const data = await transport.graphql({
             api: 'admin',
-            query: CUSTOMER_ORDERS_QUERY,
+            query: beforeBillable ? CUSTOMER_ORDERS_QUERY_BEFORE_BILLABLE : CUSTOMER_ORDERS_QUERY,
             variables: { id: customerId, ...variables },
             onExtensions,
         }, options);
@@ -312,6 +376,45 @@ export async function listCustomerOrders(transport, customerId, options) {
 export const MAX_RECENT_ORDERS = 20;
 const DEFAULT_RECENT_ORDERS = 5;
 export const CUSTOMER_RECENT_ORDERS_QUERY = /* GraphQL */ `
+  query CustomerRecentOrders($id: ID!, $options: OrderListOptions) {
+    customer(id: $id) {
+      id
+      orders(options: $options) {
+        items {
+          id
+          code
+          orderPlacedAt
+          totalWithTax
+          billableTotals {
+            total
+            totalExcludingTax
+          }
+          currencyCode
+          lines {
+            id
+            quantity
+            listPriceIncludesTax
+            productVariant {
+              id
+              name
+              sku
+              product {
+                id
+                name
+              }
+            }
+            customFields {
+              unitPriceOverride
+              unitPriceImported
+            }
+          }
+        }
+        totalItems
+      }
+    }
+  }
+`;
+const CUSTOMER_RECENT_ORDERS_QUERY_BEFORE_BILLABLE = /* GraphQL */ `
   query CustomerRecentOrders($id: ID!, $options: OrderListOptions) {
     customer(id: $id) {
       id
@@ -355,9 +458,11 @@ export async function listCustomerRecentOrders(transport, customerId, options) {
     if (!Number.isInteger(take) || take < 1 || take > MAX_RECENT_ORDERS) {
         throw invalid(`take must be a whole number from 1 to ${String(MAX_RECENT_ORDERS)}.`);
     }
-    const data = await transport.graphql({
+    const data = await withBillableFallback((beforeBillable) => transport.graphql({
         api: 'admin',
-        query: CUSTOMER_RECENT_ORDERS_QUERY,
+        query: beforeBillable
+            ? CUSTOMER_RECENT_ORDERS_QUERY_BEFORE_BILLABLE
+            : CUSTOMER_RECENT_ORDERS_QUERY,
         variables: {
             id: customerId,
             options: {
@@ -371,7 +476,12 @@ export async function listCustomerRecentOrders(transport, customerId, options) {
                 sort: { orderPlacedAt: 'DESC' },
             },
         },
-    }, call);
-    // The document selects exactly the members of `RecentOrder`: the answer is the wire's.
-    return data.customer ? data.customer.orders.items : null;
+    }, call));
+    // The document selects the members of `RecentOrder`; an older engine leaves out the billable one.
+    return data.customer
+        ? data.customer.orders.items.map((order) => ({
+            ...order,
+            billableTotals: order.billableTotals ?? null,
+        }))
+        : null;
 }

package/dist/orders/manual-discounts.d.ts

@@ -41,7 +41,10 @@ export interface DiscountPolicy {
      * The store's ceiling on manual discounts in basis points (1000 = 10 %), or `null` for none: how
      * far below the price the customer would get anyway (its contract included) staff without the
      * `OverrideDiscountLimit` permission may take a line (`DISCOUNT_OVER_LIMIT`). Reducing a
-     * discount is never refused. The POS till is not held to it.
+     * discount is never refused. The POS till is held to it too (a till discount and a lowered
+     * till price, cart-wide and per line): there only a session holding `OverrideDiscountLimit`, or
+     * a staff member holding the explicit `discount_over_limit` grant (a grant no role holds by
+     * default), goes past it.
      */
     maxDiscountBps: number | null;
 }
@@ -63,14 +66,16 @@ export interface OrderManualDiscount {
     /** The line the movement was on; `null` for a till discount on the whole cart. */
     orderLineId: string | null;
     /**
-     * `price_list`, `line_override` or `till` (`pos.sale.applyDiscount`, one row per call). Accept a
-     * value you do not know.
+     * `price_list`, `line_override` or `till` (`pos.sale.applyDiscount`, one row per call, and a row
+     * per change the till made to that money since: a removal, a cap or a re-split). Accept a value
+     * you do not know.
      */
     door: string;
     /**
      * The change of the line's total, net: (unit price after − before) × quantity, minor units of
      * `currencyCode`, as the order holds it. Negative when the price fell (a manual discount). For
-     * `till`: the money the call's negative surcharges added.
+     * `till`: the money the call's negative surcharges added; a later row of that discount carries
+     * the till's change, signed, so an order's `till` rows sum to its till discount in force.
      */
     amount: number;
     /** The same movement gross. */
@@ -85,7 +90,10 @@ export interface OrderManualDiscount {
     } | null;
     /** The Vendure user of the session that moved it. */
     actorUserId: string | null;
-    /** The vouched-for `x-on-behalf-of` ref; for a till vouched for nothing, `pos-staff:<id>`. */
+    /**
+     * The vouched-for `x-on-behalf-of` ref; for a till vouched for nothing, `pos-staff:<id>`. A `till`
+     * row that changes a discount carries the ref of the row that gave it.
+     */
     onBehalfOfRef: string | null;
     /** The vouched-for `x-device-ref` ref; for a paired till vouched for nothing, `pos-device:<id>`. */
     deviceRef: string | null;