@sixtyninecommerce/admin 0.10.0 → 0.12.0

package/dist/orders/index.d.ts

@@ -3,23 +3,38 @@ import type { JobHandle } from '../jobs/index.js';
 import type { OrderPaymentPosition, PaidOrder } from '../payments/index.js';
 import type { Call } from '../types.js';
 import { type OrderBulkInput, type OrderBulkRun } from './bulk.js';
+import { type OrderCancelWithMoneyModule } from './cancel-with-money.js';
 import { type OrderCommitEditModule } from './commit-edit.js';
 import { type OrderDepositPolicyModule } from './deposit-policy.js';
+import { type OrderDraftsModule } from './drafts.js';
+import { type OrderFieldsModule } from './fields.js';
 import { type OrderGetModule } from './get.js';
+import { type OrderLifecycleModule } from './lifecycle.js';
 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';
+import { type OrderSettingsModule } from './settings.js';
 import { type OrderStatusModule } from './status.js';
 import { type SurchargesModule } from './surcharges.js';
 export type { PaidOrder } from '../payments/index.js';
 export type { OrderBulkAction, OrderBulkCapture, OrderBulkInput, OrderBulkItem, OrderBulkRun, } from './bulk.js';
 export { MAX_BULK_ORDERS, ORDER_BULK_ACTIONS, ORDER_BULK_TRANSITION_REFUSED } from './bulk.js';
 export type { OrderDepositPolicy, OrderDepositPolicyModule, StorefrontDepositPolicy, } from './deposit-policy.js';
+export type { ClonedDraft, DraftAddLineInput, DraftAddressDefault, DraftAddressDefaults, DraftAddressFields, DraftAddressInput, DraftAddressSide, DraftAdjustLineInput, DraftCloneSkipReason, DraftCouponsModule, DraftLinePriceInput, DraftMinimumModule, DraftMinimumStatus, DraftOrder, DraftOrderFields, DraftOrderLine, DraftPaymentInput, DraftRepriceOutcome, DraftShippingQuote, KeyedDraftCall, OrderDraftsModule, PlaceDraftInput, PlacedDraftOrder, PlacedDraftPayment, SaveDraftAddressesInput, SavedDraftAddresses, } from './drafts.js';
+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 { 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';
+export type { MinimumAgeSource, OrderSettings, OrderSettingsModule, OrderStatusRule, OrderStatusRuleConditionType, OrderStatusRuleTargetState, UpdateOrderSettingsInput, } from './settings.js';
+export { MINIMUM_AGE_MAX, MINIMUM_AGE_MIN, ORDER_CODE_DIGITS_MAX, ORDER_CODE_DIGITS_MIN, ORDER_CODE_PREFIX_MAX_LENGTH, ORDER_SETTINGS_AMOUNT_MAX, ORDER_STATUS_RULE_CONDITION_TYPES, ORDER_STATUS_RULE_TARGET_STATES, } from './settings.js';
 /** An app provider an order is running without (`admin.orders.providerFallbacks`). */
 export interface OrderProviderFallback {
     /** `shipping.rates` or `tax.calculate`. */
@@ -70,8 +85,14 @@ 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, OrderParcelChargeModule, OrderLinePricePreviewModule, OrderManualPricingModule, OrderPlanEditModule, OrderCommitEditModule, 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
+     * and reasons), fields, shipping and order-minimum override, and re-price it, one step at a
+     * time (headless W10-21). See {@link OrderDraftsModule}.
+     */
+    drafts: OrderDraftsModule;
     /**
      * Manual discounts with a reason (incentives spec §4 decision 6): read an order's records,
      * and the store's reason list and policy (`reasons`, `policy`). A discount itself is given
@@ -94,14 +115,21 @@ export interface OrdersModule extends OrderEntryModule, OrderGetModule, OrderPar
      * (that read's vocabulary), before anything is written. Then by its single door, under the
      * door's own lock, with the door's own code: `ORDER_STATE_TRANSITION_ERROR` (and core's other
      * order codes), `ORDER_CART_NOT_CANCELLABLE`, `ORDER_UNITS_SHIPPED`,
-     * `ORDER_HAS_ACTIVE_FULFILLMENT`, `ORDER_INVOICE_LOCKED`, `ORDER_HAS_RECORDS`,
-     * `ORDER_NOT_DELETED`. Another store's order answers `ENTITY_NOT_FOUND` on its item. A
-     * `SUCCEEDED` run can hold `FAILED` items: read them.
+     * `ORDER_HAS_ACTIVE_FULFILLMENT`, `ORDER_CANCEL_CREDIT_NOTE_CONFLICT`, `ORDER_HOLDS_MONEY`,
+     * `ORDER_INVOICE_LOCKED`, `ORDER_HAS_RECORDS`, `ORDER_NOT_DELETED`. Another store's order
+     * answers `ENTITY_NOT_FOUND` on its item. A `SUCCEEDED` run can hold `FAILED` items: read them.
      *
      * - `TRANSITION` (`toState` required): as `transitionOrderToState`. Never `Cancelled` (use
      *   `CANCEL`), `PaymentSettled` (use `MARK_PAID`), `Modifying` or `AddingItems`.
      * - `CANCEL` (`reason` optional): the whole order, shipping included, as `cancelOrder`. **It
-     *   moves no money:** a paid order keeps its payment, to be refunded through `payments.refund`.
+     *   moves no money:** an order that has been placed or parked and still holds money (settled
+     *   money, a card hold) answers `ORDER_HOLDS_MONEY` and is not cancelled; cancel it on its own
+     *   with `orders.cancelWithMoney`, which decides what happens to the money. An INVOICED order,
+     *   paid or not, is not cancelled by either (reason `CREDIT_NOTE_REQUIRED`): do what
+     *   `orders.status`'s `cancelCreditNote.remedy` says first (correct the invoice, or refund the
+     *   payment whose AR credit note corrects it, never both), then cancel it. A credential
+     *   restricted to stock locations (`locationIds`) cancels only an order whose stock is reserved
+     *   at its own locations; any other item answers `LOCATION_OUT_OF_SCOPE`, as `cancelOrder` does.
      * - `DELETE`: a draft or a cart holding no payment or stock movement, as `deleteOrder`.
      * - `MARK_PAID`: **captures** each payment of the order that is `Authorized` when the run reaches
      *   it, read by the engine (never your list's copy), each as `settlePayment` and on its own
@@ -153,6 +181,12 @@ export interface OrdersModule extends OrderEntryModule, OrderGetModule, OrderPar
      * applies; `set` replaces it, validated against the schema's bounds first.
      */
     depositPolicy: OrderDepositPolicyModule;
+    /**
+     * The store's order settings (Settings → Orders): the order minimum and its exemptions, order
+     * numbering, the minimum purchase age, the status rules and the outstanding-balance tiers.
+     * `get` answers them as the engine applies them; `set` changes the keys a patch names.
+     */
+    settings: OrderSettingsModule;
     /**
      * Hold a placed order while the rest of its money is arranged. Needs
      * `UpdateOrder`.
@@ -208,13 +242,22 @@ export interface OrdersModule extends OrderEntryModule, OrderGetModule, OrderPar
      * position.
      */
     unpark(orderId: string, options?: Call): Promise<PaidOrder>;
-    /** What the order has actually been paid. 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
+     */
     paymentPosition(orderId: string, options?: Call): Promise<OrderPaymentPosition>;
     /**
      * 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,
@@ -235,22 +278,30 @@ export interface OrdersModule extends OrderEntryModule, OrderGetModule, OrderPar
      * is covered only by an AUTHORIZED payment owes nothing and is refused
      * `COVERAGE_INSUFFICIENT` with the hold kept: accept it by capturing that
      * payment with `settlePayment`, which settles and places it. To turn the order
-     * down, refund the payment, then {@link OrdersModule.unpark} and cancel it: a
-     * refund alone leaves it parked, held and holding its stock.
+     * down, cancel it with {@link OrdersModule.cancelWithMoney}: one call, straight
+     * out of the park, that refunds its money, credits it to the customer's account
+     * or keeps it (with a reason), and gives the reserved stock back. A refund alone
+     * leaves it parked, held and holding its stock.
      *
      * 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;
@@ -267,5 +318,5 @@ export interface OrdersModule extends OrderEntryModule, OrderGetModule, OrderPar
 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      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,17 +1,28 @@
 import { NotFoundError } from '@sixtyninecommerce/core';
+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';
 import { createOrderDepositPolicyModule } from './deposit-policy.js';
+import { createOrderDraftsModule } from './drafts.js';
+import { createOrderFieldsModule } from './fields.js';
 import { createOrderGetModule } from './get.js';
+import { createOrderLifecycleModule } from './lifecycle.js';
 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';
+import { createOrderSettingsModule } from './settings.js';
 import { createOrderStatusModule } from './status.js';
 import { createSurchargesModule } from './surcharges.js';
 export { MAX_BULK_ORDERS, ORDER_BULK_ACTIONS, ORDER_BULK_TRANSITION_REFUSED } from './bulk.js';
+export { DraftInsufficientStockError } from './drafts.js';
+export { MAX_ORDER_LIST_TAKE, MAX_RECENT_ORDERS, ORDER_LIST_SORT_FIELDS } from './list.js';
+export { MINIMUM_AGE_MAX, MINIMUM_AGE_MIN, ORDER_CODE_DIGITS_MAX, ORDER_CODE_DIGITS_MIN, ORDER_CODE_PREFIX_MAX_LENGTH, ORDER_SETTINGS_AMOUNT_MAX, ORDER_STATUS_RULE_CONDITION_TYPES, ORDER_STATUS_RULE_TARGET_STATES, } from './settings.js';
 const ORDER_PROVIDER_FALLBACKS_QUERY = /* GraphQL */ `
   query OrderProviderFallbacks($id: ID!) {
     order(id: $id) {
@@ -85,6 +96,9 @@ export const ORDER_POSITION_QUERY = /* GraphQL */ `
       settled
       authorized
       refunded
+      creditNoted
+      owed
+      payable
       outstanding
       overpaid
       availableToCharge
@@ -92,18 +106,26 @@ export const ORDER_POSITION_QUERY = /* GraphQL */ `
   }
 `;
 export function createOrdersModule(transport) {
+    const getModule = createOrderGetModule(transport);
     return {
         ...createOrderEntryModule(transport),
-        ...createOrderGetModule(transport),
+        ...getModule,
+        ...createOrderListModule(transport),
         ...createOrderParcelChargeModule(transport),
         ...createOrderLinePricePreviewModule(transport),
         ...createOrderManualPricingModule(transport),
         ...createOrderPlanEditModule(transport),
         ...createOrderCommitEditModule(transport),
+        ...createOrderCancelWithMoneyModule(transport),
+        ...createOrderLifecycleModule(transport),
+        ...createOrderFieldsModule(transport),
         ...createOrderStatusModule(transport),
+        ...createOrderMoneyViewModule(transport),
         surcharges: createSurchargesModule(transport),
+        drafts: createOrderDraftsModule(transport, getModule),
         manualDiscounts: createManualDiscountsModule(transport),
         depositPolicy: createOrderDepositPolicyModule(transport),
+        settings: createOrderSettingsModule(transport),
         bulk(input, options) {
             return bulkOrders(transport, input, options);
         },
@@ -150,7 +172,8 @@ export function createOrdersModule(transport) {
             return data.order.providerFallbacks;
         },
         async paymentPosition(orderId, options) {
-            const data = await transport.graphql({ api: 'admin', query: ORDER_POSITION_QUERY, variables: { orderId } }, options);
+            // The credit fields fall away on an engine before them: the position itself still reads.
+            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/lifecycle.d.ts

@@ -0,0 +1,128 @@
+/**
+ * The single-order lifecycle writes (headless spec §9.2 `orders`, "holds, cancel/reopen/complete";
+ * W10-25): complete, reopen, waive the payment, hold the fulfilment, move the order to another
+ * state, and cancel it whole.
+ *
+ * Which of them an order allows now, and why not, is `orders.status(orderId).actions`
+ * (`MARK_COMPLETED`, `REOPEN`, `SET_PAYMENT_NOT_REQUIRED`, `SET_FULFILLMENT_HOLD`, `TRANSITION`
+ * with `nextStates`, `CANCEL`): ask it before offering one. Every refusal below is a coded
+ * `PlatformError`; core's own transition refusals carry the gate's reason as their message, never
+ * Vendure's "Cannot transition Order from X to Y" template.
+ */
+import { type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+import type { OrderFulfillmentHoldReason } from './get.js';
+/** The order as a lifecycle write leaves it. */
+export interface OrderLifecycleRecord {
+    id: string;
+    code: string;
+    /** The engine state. */
+    state: string;
+    /**
+     * The four projected dimensions (`orders.status` reads the same). Each is null on an order that
+     * predates them, and for a moment after a change: the engine writes them after the change.
+     */
+    lifecycle: {
+        status: string | null;
+        payment: string | null;
+        fulfillment: string | null;
+        return: string | null;
+    };
+}
+/** Putting a hold on (`hold: true`, with a reason) or releasing it (`hold: false`, nothing else). */
+export type FulfillmentHoldInput = {
+    hold: true;
+    reason: OrderFulfillmentHoldReason;
+    /** At most 500 characters. Required for `other`. */
+    note?: string | null;
+} | {
+    hold: false;
+};
+export interface OrderLifecycleModule {
+    /**
+     * Mark the order completed. Needs `UpdateOrder`.
+     *
+     * Refused `ORDER_ALREADY_COMPLETED` on a completed order and `ORDER_COMPLETE_CANCELLED` on a
+     * cancelled one (`BusinessRuleError`, 422); nothing changes. Against an engine older than these
+     * codes the same call succeeded without changing anything.
+     *
+     * @effect write
+     */
+    markCompleted(orderId: string, options?: Call): Promise<OrderLifecycleRecord>;
+    /**
+     * Reopen a completed order. Needs `UpdateOrder`. Does nothing to an order that is not
+     * completed. Refused `ORDER_REOPEN_LOCKED` (422) while an invoice locks the order: an invoiced
+     * order is corrected by void & reissue, not reopened.
+     *
+     * @effect write
+     */
+    reopen(orderId: string, options?: Call): Promise<OrderLifecycleRecord>;
+    /**
+     * Waive the payment the order expects (`notRequired: true`: a comp, a sample) or lift the
+     * waiver (`false`). The payment dimension reads `not_required` while waived. Needs
+     * `UpdateOrder`.
+     *
+     * Refused `ORDER_PAYMENT_WAIVER_REFUSED` (422) on a cancelled order either way, and when
+     * waiving an order an invoice still bills: correct the invoice first (`orders.status` answers
+     * `CREDIT_NOTE_REQUIRED`). Lifting a waiver is otherwise never refused.
+     *
+     * @effect money
+     */
+    setPaymentNotRequired(orderId: string, notRequired: boolean, options?: Call): Promise<OrderLifecycleRecord>;
+    /**
+     * Put the order's fulfilment on hold with a reason, or release it. Re-holding replaces the
+     * reason and note. Both directions write a private (staff-only) history entry. Needs
+     * `UpdateOrder`.
+     *
+     * Refused `ORDER_FULFILLMENT_HOLD_INVALID` (`ValidationError`, 400) for an unknown reason, a
+     * note over 500 characters, or `other` without a note. `orders.status` offers a NEW hold on an
+     * open order only (`SET_FULFILLMENT_HOLD`), and a release on any order holding one.
+     *
+     * @effect write
+     */
+    setFulfillmentHold(orderId: string, input: FulfillmentHoldInput, options?: Call): Promise<OrderLifecycleRecord>;
+    /**
+     * Move the order to one of `orders.status(orderId).nextStates`. Needs `UpdateOrder`.
+     *
+     * A move into `PaymentSettled`, or into `PaymentAuthorized` from the unpaid side, is refused
+     * `COVERAGE_INSUFFICIENT` (422) while the order's money does not cover it (settled money for
+     * `PaymentSettled`; a net-terms order is judged when it was authorized): it never settles an
+     * order without its money (`nextStates` already leaves such a move out). A move into
+     * `Cancelled` is a cancel, and refused as {@link OrderLifecycleModule.cancel} is. Any other
+     * refusal is core's `ORDER_STATE_TRANSITION_ERROR` with the gate's reason as its message (an
+     * order minimum, unconfirmed terms, a stock shortage).
+     *
+     * @effect money
+     */
+    transition(orderId: string, state: string, options?: Call): Promise<OrderLifecycleRecord>;
+    /**
+     * Cancel the WHOLE order, shipping included. An order cannot be un-cancelled. Needs
+     * `UpdateOrder`. Lines alone are cancelled through `orders.commitEdit`.
+     *
+     * It moves no money. Refused:
+     * - `ORDER_HOLDS_MONEY` (422) while the order has been placed or parked and still holds money:
+     *   use `orders.cancelWithMoney`, which decides what happens to it;
+     * - `ORDER_CANCEL_CREDIT_NOTE_CONFLICT` (409) while an invoice still bills the order, paid or
+     *   not: do what `orders.status(orderId).cancelCreditNote.remedy` says first;
+     * - `ORDER_UNITS_SHIPPED` / `ORDER_HAS_ACTIVE_FULFILLMENT` (422) while a fulfilment holds a
+     *   line; `ORDER_CART_NOT_CANCELLABLE` (422) for a live cart the store may not end;
+     * - `LOCATION_OUT_OF_SCOPE` (422), for a credential restricted to stock locations (an API
+     *   token or app installation with `locationIds`) only: the order's stock is reserved at a
+     *   location outside its restriction, and a cancel releases it there
+     *   (`orders.status(orderId)` answers `CANCEL` with `PERMISSION`);
+     * - core's own refusals (`ORDER_STATE_TRANSITION_ERROR`, `CANCEL_ACTIVE_ORDER_ERROR`,
+     *   `EMPTY_ORDER_LINE_SELECTION_ERROR`) with their reason.
+     *
+     * @effect irreversible
+     */
+    cancel(orderId: string, options?: Call & {
+        reason?: string;
+    }): Promise<OrderLifecycleRecord>;
+}
+export declare const MARK_ORDER_COMPLETED_MUTATION = "\n  mutation MarkOrderCompleted($orderId: ID!) {\n    markOrderCompleted(orderId: $orderId) {\n      \n  id\n  code\n  state\n  customFields {\n    lifecycleStatus\n    paymentStatus\n    fulfillmentStatus\n    returnStatus\n  }\n\n    }\n  }\n";
+export declare const REOPEN_ORDER_MUTATION = "\n  mutation ReopenOrder($orderId: ID!) {\n    reopenOrder(orderId: $orderId) {\n      \n  id\n  code\n  state\n  customFields {\n    lifecycleStatus\n    paymentStatus\n    fulfillmentStatus\n    returnStatus\n  }\n\n    }\n  }\n";
+export declare const MARK_ORDER_PAYMENT_NOT_REQUIRED_MUTATION = "\n  mutation MarkOrderPaymentNotRequired($orderId: ID!, $notRequired: Boolean!) {\n    markOrderPaymentNotRequired(orderId: $orderId, notRequired: $notRequired) {\n      \n  id\n  code\n  state\n  customFields {\n    lifecycleStatus\n    paymentStatus\n    fulfillmentStatus\n    returnStatus\n  }\n\n    }\n  }\n";
+export declare const SET_ORDER_FULFILLMENT_HOLD_MUTATION = "\n  mutation SetOrderFulfillmentHold(\n    $orderId: ID!\n    $onHold: Boolean!\n    $reason: FulfillmentHoldReason\n    $note: String\n  ) {\n    setOrderFulfillmentHold(orderId: $orderId, onHold: $onHold, reason: $reason, note: $note) {\n      \n  id\n  code\n  state\n  customFields {\n    lifecycleStatus\n    paymentStatus\n    fulfillmentStatus\n    returnStatus\n  }\n\n    }\n  }\n";
+export declare const TRANSITION_ORDER_MUTATION = "\n  mutation TransitionOrderToState($id: ID!, $state: String!) {\n    transitionOrderToState(id: $id, state: $state) {\n      __typename\n      ... on Order {\n        \n  id\n  code\n  state\n  customFields {\n    lifecycleStatus\n    paymentStatus\n    fulfillmentStatus\n    returnStatus\n  }\n\n      }\n      ... on OrderStateTransitionError {\n        transitionError\n      }\n      ... on ErrorResult {\n        errorCode\n        message\n      }\n    }\n  }\n";
+export declare const CANCEL_ORDER_MUTATION = "\n  mutation CancelOrder($input: CancelOrderInput!) {\n    cancelOrder(input: $input) {\n      __typename\n      ... on Order {\n        \n  id\n  code\n  state\n  customFields {\n    lifecycleStatus\n    paymentStatus\n    fulfillmentStatus\n    returnStatus\n  }\n\n      }\n      ... on OrderStateTransitionError {\n        transitionError\n      }\n      ... on ErrorResult {\n        errorCode\n        message\n      }\n    }\n  }\n";
+export declare function createOrderLifecycleModule(transport: Transport): OrderLifecycleModule;

package/dist/orders/lifecycle.js

@@ -0,0 +1,158 @@
+/**
+ * The single-order lifecycle writes (headless spec §9.2 `orders`, "holds, cancel/reopen/complete";
+ * W10-25): complete, reopen, waive the payment, hold the fulfilment, move the order to another
+ * state, and cancel it whole.
+ *
+ * Which of them an order allows now, and why not, is `orders.status(orderId).actions`
+ * (`MARK_COMPLETED`, `REOPEN`, `SET_PAYMENT_NOT_REQUIRED`, `SET_FULFILLMENT_HOLD`, `TRANSITION`
+ * with `nextStates`, `CANCEL`): ask it before offering one. Every refusal below is a coded
+ * `PlatformError`; core's own transition refusals carry the gate's reason as their message, never
+ * Vendure's "Cannot transition Order from X to Y" template.
+ */
+import { errorFromErrorResult, isErrorResult } from '@sixtyninecommerce/core';
+const ORDER_FIELDS = /* GraphQL */ `
+  id
+  code
+  state
+  customFields {
+    lifecycleStatus
+    paymentStatus
+    fulfillmentStatus
+    returnStatus
+  }
+`;
+export const MARK_ORDER_COMPLETED_MUTATION = /* GraphQL */ `
+  mutation MarkOrderCompleted($orderId: ID!) {
+    markOrderCompleted(orderId: $orderId) {
+      ${ORDER_FIELDS}
+    }
+  }
+`;
+export const REOPEN_ORDER_MUTATION = /* GraphQL */ `
+  mutation ReopenOrder($orderId: ID!) {
+    reopenOrder(orderId: $orderId) {
+      ${ORDER_FIELDS}
+    }
+  }
+`;
+export const MARK_ORDER_PAYMENT_NOT_REQUIRED_MUTATION = /* GraphQL */ `
+  mutation MarkOrderPaymentNotRequired($orderId: ID!, $notRequired: Boolean!) {
+    markOrderPaymentNotRequired(orderId: $orderId, notRequired: $notRequired) {
+      ${ORDER_FIELDS}
+    }
+  }
+`;
+export const SET_ORDER_FULFILLMENT_HOLD_MUTATION = /* GraphQL */ `
+  mutation SetOrderFulfillmentHold(
+    $orderId: ID!
+    $onHold: Boolean!
+    $reason: FulfillmentHoldReason
+    $note: String
+  ) {
+    setOrderFulfillmentHold(orderId: $orderId, onHold: $onHold, reason: $reason, note: $note) {
+      ${ORDER_FIELDS}
+    }
+  }
+`;
+// The concrete members are selected for their sentences: `ErrorResult.message` is a per-code
+// template, and the refusing gate's reason lives on the concrete type alone.
+export const TRANSITION_ORDER_MUTATION = /* GraphQL */ `
+  mutation TransitionOrderToState($id: ID!, $state: String!) {
+    transitionOrderToState(id: $id, state: $state) {
+      __typename
+      ... on Order {
+        ${ORDER_FIELDS}
+      }
+      ... on OrderStateTransitionError {
+        transitionError
+      }
+      ... on ErrorResult {
+        errorCode
+        message
+      }
+    }
+  }
+`;
+export const CANCEL_ORDER_MUTATION = /* GraphQL */ `
+  mutation CancelOrder($input: CancelOrderInput!) {
+    cancelOrder(input: $input) {
+      __typename
+      ... on Order {
+        ${ORDER_FIELDS}
+      }
+      ... on OrderStateTransitionError {
+        transitionError
+      }
+      ... on ErrorResult {
+        errorCode
+        message
+      }
+    }
+  }
+`;
+function recordOf(order) {
+    const fields = order.customFields ?? {};
+    return {
+        id: order.id,
+        code: order.code,
+        state: order.state,
+        lifecycle: {
+            status: fields.lifecycleStatus ?? null,
+            payment: fields.paymentStatus ?? null,
+            fulfillment: fields.fulfillmentStatus ?? null,
+            return: fields.returnStatus ?? null,
+        },
+    };
+}
+/** The order, or the union member thrown as a coded error carrying the gate's own reason. */
+function orderOrThrow(result) {
+    if (!isErrorResult(result))
+        return recordOf(result);
+    const reason = result.transitionError;
+    const message = typeof reason === 'string' && reason.trim() !== '' ? reason : result.message;
+    throw errorFromErrorResult({ errorCode: result.errorCode, message });
+}
+export function createOrderLifecycleModule(transport) {
+    const write = async (field, query, variables, options) => {
+        const data = await transport.graphql({ api: 'admin', query, variables }, options);
+        return recordOf(data[field]);
+    };
+    return {
+        markCompleted(orderId, options) {
+            return write('markOrderCompleted', MARK_ORDER_COMPLETED_MUTATION, { orderId }, options);
+        },
+        reopen(orderId, options) {
+            return write('reopenOrder', REOPEN_ORDER_MUTATION, { orderId }, options);
+        },
+        setPaymentNotRequired(orderId, notRequired, options) {
+            return write('markOrderPaymentNotRequired', MARK_ORDER_PAYMENT_NOT_REQUIRED_MUTATION, { orderId, notRequired }, options);
+        },
+        setFulfillmentHold(orderId, input, options) {
+            // A release sends neither a reason nor a note: the engine refuses them there.
+            const variables = input.hold
+                ? { orderId, onHold: true, reason: input.reason, note: input.note ?? null }
+                : { orderId, onHold: false };
+            return write('setOrderFulfillmentHold', SET_ORDER_FULFILLMENT_HOLD_MUTATION, variables, options);
+        },
+        async transition(orderId, state, options) {
+            const data = await transport.graphql({ api: 'admin', query: TRANSITION_ORDER_MUTATION, variables: { id: orderId, state } }, options);
+            const result = data.transitionOrderToState;
+            if (!result) {
+                throw errorFromErrorResult({
+                    errorCode: 'ORDER_NOT_FOUND',
+                    message: `This store has no order ${orderId}.`,
+                });
+            }
+            return orderOrThrow(result);
+        },
+        async cancel(orderId, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: CANCEL_ORDER_MUTATION,
+                // `undefined`, never an explicit null: an omitted reason stays off the wire.
+                variables: { input: { orderId, reason: options?.reason, cancelShipping: true } },
+            }, options);
+            return orderOrThrow(data.cancelOrder);
+        },
+    };
+}

package/dist/orders/line-price-preview.d.ts

@@ -224,8 +224,8 @@ export interface OrderLinePricePreviewModule {
      * validated, tax removed) does not show in such a line's figures, so the
      * comparison above does not see it.
      *
-     * The preview does not
-     * predict what a save refuses: a staged one-time discount that the Admin
+     * Apart from the clears listed under the refusals below, the preview does
+     * not predict what a save refuses: a staged one-time discount that the Admin
      * API's `setOrderPriceListDiscounts` would refuse is still priced, and shows
      * no `ONE_TIME` step when the pricing rules skipped it.
      *
@@ -289,6 +289,11 @@ export interface OrderLinePricePreviewModule {
      *   preview does not evaluate (`PreviewLinePriceOverride.basis`).
      * - `PREVIEW_CHANNEL_NOT_ALLOWED` (`PermissionDeniedError`, 403): the call
      *   was made from the default channel instead of the order's own.
+     * - `ORDER_LINE_VARIANT_UNPRICED` (`BusinessRuleError`, 422; absent from an
+     *   engine released before 2026-10-10): `override: null` on a line that
+     *   states a manual price while its variant has no price in the store, as
+     *   the save refuses it; stage the price you want, or set a price for the
+     *   variant in the store first.
      */
     previewLinePrices(orderId: string, lines: PreviewLinePriceLine[], options?: Call & {
         orderDiscount?: PreviewOneTimeDiscount | null;