@sixtyninecommerce/admin 0.8.0 → 0.10.0

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

@@ -0,0 +1,489 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+import type { OverpaymentOption } from './surcharges.js';
+/**
+ * How a one-time discount is stated. A whole-order discount is `PERCENTAGE` or
+ * `FIXED_AMOUNT`, never `FIXED_PRICE`.
+ */
+export type OrderEditDiscountType = 'PERCENTAGE' | 'FIXED_AMOUNT' | 'FIXED_PRICE';
+/** A manual unit price. */
+export interface OrderEditPriceOverride {
+    /**
+     * Minor units, a whole number of 0 or more, in the LINE's tax basis.
+     * `orders.previewLinePrices` answers a line's basis and converts a price
+     * stated in the other one.
+     */
+    unitPriceOverride: number;
+    priceOverrideReason?: string | null;
+}
+/** A one-time discount: on one line's product, or on the whole order. */
+export interface OrderEditDiscount {
+    discountType: OrderEditDiscountType;
+    /**
+     * A whole number. `PERCENTAGE`: basis points, 1 to 10000. `FIXED_AMOUNT` and
+     * `FIXED_PRICE`: minor units in the store's tax basis.
+     */
+    discountValue: number;
+    /** Kept once for the order's one-time pricing. Left out keeps the stored one. */
+    reason?: string | null;
+    /**
+     * One of the store's discount reasons (`discountReasons`), by code, for THIS
+     * discount. A store that requires a reason refuses a lowered price without
+     * one: the plan answers the blocker `DISCOUNT_REASON_REQUIRED`. See
+     * {@link OrderEditDiff.discountReasonCode} for one that covers the whole edit.
+     */
+    reasonCode?: string | null;
+}
+/** A surcharge, or with a negative price a discount, on the order. */
+export interface OrderEditSurcharge {
+    description: string;
+    /** Minor units, negative for a discount, never 0. */
+    price: number;
+    priceIncludesTax: boolean;
+    /** A percentage from 0 to 100. Left out writes no tax line. */
+    taxRate?: number | null;
+    taxDescription?: string | null;
+}
+/**
+ * The fields of an order address an edit may change. A field that is left out
+ * or `null` keeps what the order has.
+ */
+export interface OrderEditAddressPatch {
+    fullName?: string | null;
+    company?: string | null;
+    streetLine1?: string | null;
+    streetLine2?: string | null;
+    city?: string | null;
+    province?: string | null;
+    postalCode?: string | null;
+    countryCode?: string | null;
+    phoneNumber?: string | null;
+}
+export interface OrderEditAddress {
+    address: OrderEditAddressPatch;
+    /**
+     * Also write the address to the customer's saved addresses: the entry the
+     * order's address came from is updated, or a new one is added. Needs
+     * `UpdateCustomer` or `CreateCustomer` beside `UpdateOrder`; without it the
+     * plan answers the blocker `ORDER_EDIT_PERMISSION_REQUIRED`.
+     */
+    applyToCustomer?: boolean | null;
+    /**
+     * `true`: the address is for this order only and is never offered as a saved
+     * address. `false`: it is not. Left out leaves the order's flag as it is.
+     * Refused together with `applyToCustomer: true`.
+     */
+    markTemporary?: boolean | null;
+}
+/**
+ * What an edit of a placed order should change, as intents. It never names the
+ * operation that carries a change out: the server decides that.
+ *
+ * Every list holds at most 500 entries, and an id appears once per list. A
+ * list that is left out, `null` or empty changes nothing, with one exception:
+ * `couponCodes` is the COMPLETE list the order should end with, so an empty
+ * list removes every coupon and only left out or `null` leaves them alone.
+ *
+ * `orderDiscount` has three states: left out keeps the stored whole-order
+ * discount, `null` removes it, a value sets it. The SDK sends the diff as
+ * given; a key set to `undefined` counts as left out.
+ */
+export interface OrderEditDiff {
+    /** The quantity each named line should have. 0 removes the line. */
+    adjustLines?: Array<{
+        orderLineId: string;
+        quantity: number;
+    }> | null;
+    /**
+     * Items to add, each 1 or more. An item with no stated price joins the line
+     * of its variant when the order has one; with a stated price it is a line of
+     * its own (0 makes it a free line).
+     */
+    addItems?: Array<{
+        productVariantId: string;
+        quantity: number;
+        priceOverride?: OrderEditPriceOverride | null;
+    }> | null;
+    /** A manual unit price per named line. */
+    priceOverrides?: Array<{
+        orderLineId: string;
+    } & OrderEditPriceOverride> | null;
+    /**
+     * The one-time discount of each named line's product. An entry with
+     * `discount` left out or `null` REMOVES that line's one-time discount: an
+     * entry names the line, so there is no "leave it" inside one. Leave a line
+     * out of the list to keep what it has.
+     */
+    lineDiscounts?: Array<{
+        orderLineId: string;
+        discount?: OrderEditDiscount | null;
+    }> | null;
+    /** The whole-order one-time discount. Three states: see {@link OrderEditDiff}. */
+    orderDiscount?: OrderEditDiscount | null;
+    /**
+     * `true` removes the tax, `false` forces the standard rate. Left out or
+     * `null` leaves the order's tax as it is.
+     */
+    removeTax?: boolean | null;
+    addSurcharges?: OrderEditSurcharge[] | null;
+    updateSurcharges?: Array<{
+        surchargeId: string;
+    } & OrderEditSurcharge> | null;
+    removeSurchargeIds?: string[] | null;
+    shippingAddress?: OrderEditAddress | null;
+    billingAddress?: OrderEditAddress | null;
+    /** The complete list of coupon codes the order should end with. */
+    couponCodes?: string[] | null;
+    /** A note for the order's history. A note alone is not a change. */
+    note?: string | null;
+    /**
+     * The warehouse each named line should ship from. `stockLocationId` left out
+     * or `null` clears the line's pick. A pick also moves what the line reserves
+     * now.
+     */
+    preferredLocations?: Array<{
+        orderLineId: string;
+        stockLocationId?: string | null;
+    }> | null;
+    /**
+     * How the stock a named line reserves is split over warehouses. The
+     * quantities must add up to what the line reserves; a row of 0 is dropped. A
+     * split clears the line's pick.
+     */
+    allocationSplits?: Array<{
+        orderLineId: string;
+        allocations: Array<{
+            stockLocationId: string;
+            quantity: number;
+        }>;
+    }> | null;
+    /**
+     * One of the store's discount reasons, by code, for the edit as a whole: it
+     * covers every line whose price a manual unit price or the one-time pricing
+     * lowers and that names no reason of its own (a removed discount included).
+     * A code the store does not have, or deactivated, is the blocker
+     * `DISCOUNT_REASON_UNKNOWN`. A manual unit price lowered through the order
+     * modification (an order money was collected for) is recorded with this reason
+     * but never refused for lacking one.
+     */
+    discountReasonCode?: string | null;
+}
+/**
+ * How one step of an edit is carried out. A plan lists its steps in the order
+ * they run. A string on the wire: an engine newer than this SDK may answer a
+ * kind this list does not have.
+ *
+ * - `CANCEL_LINES`: units are taken off lines by a partial cancellation
+ *   (restocked, no refund).
+ * - `LINE_PRICE_OVERRIDES`: manual unit prices are written on the named lines.
+ * - `ONE_TIME_PRICING`: the order's one-time pricing is written to its
+ *   complete desired state.
+ * - `TAX_REMOVAL`: the remove-tax flag is written and every line is re-taxed.
+ * - `MODIFY_ORDER`: the order is modified through the engine's order
+ *   modification, and returns to the plan's `returnState`.
+ * - `CUSTOMER_ADDRESSES`: the customer's saved addresses and the order's links
+ *   to them are written.
+ * - `SURCHARGE_UPDATE`, `SURCHARGE_REMOVE`, `SURCHARGE_ADD`: one surcharge each.
+ * - `WAREHOUSE_PREFERENCES`, `WAREHOUSE_MOVES`, `WAREHOUSE_SPLITS`: where the
+ *   named lines ship from.
+ */
+export type OrderEditStepKind = 'CANCEL_LINES' | 'LINE_PRICE_OVERRIDES' | 'ONE_TIME_PRICING' | 'TAX_REMOVAL' | 'MODIFY_ORDER' | 'CUSTOMER_ADDRESSES' | 'SURCHARGE_UPDATE' | 'SURCHARGE_REMOVE' | 'SURCHARGE_ADD' | 'WAREHOUSE_PREFERENCES' | 'WAREHOUSE_MOVES' | 'WAREHOUSE_SPLITS' | (string & {});
+export interface OrderEditStep {
+    kind: OrderEditStepKind;
+    /**
+     * What the step is handed: ids, quantities and the values the diff staged.
+     * Its shape follows `kind` and is for showing the step, not a contract to
+     * build on. It holds no id made up while planning, so two plans of the same
+     * edit of an unchanged order state the same input.
+     */
+    input: Record<string, unknown>;
+    /**
+     * The change this step makes to the order's total with tax, in minor units.
+     * `null` for a step the preview did not reach because an earlier one was
+     * refused, and for every step when a blocker was found before any step ran.
+     */
+    moneyEffect: number | null;
+}
+/**
+ * The refund an edit of a paid order ends with: what the edit as a whole takes
+ * off the total and a lowered surcharge does not account for, never more than
+ * the customer would then have paid beyond what the order bills (an order
+ * still owing pays that down first). A plan computes it and never asks a
+ * payment provider for anything.
+ */
+export interface OrderEditRefund {
+    /** The one payment that carries the whole amount. An edit never splits a refund. */
+    paymentId: string;
+    /** Minor units in the order's currency. */
+    amount: number;
+}
+/**
+ * What a lowered or removed surcharge leaves the customer of a PAID order
+ * overpaid by, and the two ways the merchant may settle it: `REFUND` to the
+ * customer's payment, or `ACCOUNT_CREDIT` to their account as unapplied cash.
+ * Ask the merchant, then pass the answer to `commitEdit` as
+ * `overpaymentChoice`. The edit's other cuts (item prices and quantities)
+ * refund automatically, in the plan's `refund`.
+ */
+export interface OrderEditOverpayment {
+    /**
+     * The surcharges' share of what the edit gives back, minor units. Never more
+     * than the edit as a whole adds to what the customer has paid beyond what
+     * the order bills: an order still owing, or one already overpaid before the
+     * edit, gets back only that.
+     */
+    amount: number;
+    currencyCode: string;
+    /** The surcharges the edit lowers or removes. */
+    surchargeIds: string[];
+    /**
+     * Whether `REFUND` is open; when not, `code` is the refusal choosing it would
+     * answer: `REFUND_EXCEEDS_PAYMENT` (no one payment can return this amount
+     * together with the plan's `refund`), `REFUND_METHOD_UNAVAILABLE` (the
+     * payment's method can no longer be reached), `REFUND_PAYMENT_HOLDS_NO_MONEY`,
+     * or `ORDER_OVERPAYMENT_REFUND_UNRECONCILED`.
+     */
+    refund: OverpaymentOption;
+    /**
+     * Whether `ACCOUNT_CREDIT` is open; when not, the account's own refusal:
+     * `AR_LEDGER_NOT_ENABLED`, `AR_ACCOUNT_REQUIRED`, `AR_ACCOUNT_IN_ERP` (the
+     * customer's balance is kept in the ERP: refund only),
+     * `AR_ORDER_ALREADY_INVOICED`, `ACCOUNT_CREDIT_NO_CUSTOMER`,
+     * `ACCOUNT_CREDIT_EXCEEDS_OVERPAYMENT`, `ACCOUNT_CREDIT_NOTHING_OVERPAID`, or
+     * `ORDER_OVERPAYMENT_REFUND_UNRECONCILED`.
+     */
+    accountCredit: OverpaymentOption;
+    /**
+     * The ONE refund the edit ends with when `REFUND` is chosen: this amount and
+     * the plan's `refund` together, on one payment. `null` when `REFUND` is not
+     * open.
+     */
+    refundWhenChosen: OrderEditRefund | null;
+}
+/**
+ * Why an edit cannot be carried out, as a stable code. A string on the wire. A
+ * step the preview saw refused carries the refusing operation's OWN code when
+ * it has one (for example `VARIANT_NOT_FOR_SALE_IN_CURRENCY`, or a core
+ * ErrorResult code such as `INSUFFICIENT_STOCK_ERROR`), and
+ * `ORDER_EDIT_STEP_REFUSED` when it has none.
+ *
+ * - `ORDER_EDIT_NOT_ALLOWED`: the order's state, invoice lock or lifecycle
+ *   does not allow an edit. `details.reasonCode` and `details.state` say which.
+ * - `ORDER_EDIT_NOTHING_TO_CHANGE`: the diff changes nothing the order does
+ *   not already have.
+ * - `ORDER_EDIT_FULFILLED_FLOOR`: a line would go below what its fulfillments
+ *   hold. `details.lines` names each such line.
+ * - `ORDER_EDIT_REFUND_TARGET_MISSING`: the edit lowers the total and no
+ *   payment of the order can be refunded.
+ * - `ORDER_EDIT_REFUND_EXCEEDS_PAYMENT`: the edit lowers the total by more than
+ *   any one payment can still return. `details` has `amount`,
+ *   `largestHeadroom` and `refundable`.
+ * - `ORDER_EDIT_OVERPAYMENT_NOT_SETTLEABLE`: a surcharge is lowered or removed
+ *   on a paid order, and neither a refund nor an account credit can settle
+ *   what that leaves the customer overpaid by. `details` has `amount`,
+ *   `currencyCode`, and `refund` / `accountCredit` with each closed option's
+ *   `code`; the plan's `overpayment` says why in words.
+ * - `ORDER_EDIT_OVERPAYMENT_CHOICE_REQUIRED`: answered only by an engine
+ *   before the overpayment choice: a surcharge lowered or removed on a paid
+ *   order, overpaying the customer by `details.amount`. A current engine
+ *   answers `overpayment` instead, and refuses a `commitEdit` that gives no
+ *   `overpaymentChoice` for it with this code.
+ * - `ORDER_EDIT_PERMISSION_REQUIRED`: the caller may edit the order and lacks
+ *   `details.permission` for another write the edit includes.
+ * - `ORDER_EDIT_STEP_REFUSED`: `details.step` was refused; `message` is the
+ *   refusing operation's own sentence.
+ * - `ORDER_OVERPAYMENT_REFUND_UNRECONCILED`: the edit gives money back while a
+ *   refund on the order has an outcome nobody knows yet (`details.unreconciled`
+ *   names each). Record the provider's answer first
+ *   (`admin.payments.reconcileRefund`).
+ * - `ORDER_EDIT_PAYMENT_STATE_UNREACHABLE`: the edit leaves a paid order owing
+ *   on a payment collected online, so the order must wait for the payment in
+ *   `ArrangingAdditionalPayment`, and either it cannot be moved there from
+ *   `details.fromState`, or the payment could not be recorded once it waits
+ *   there: part of it is an existing surcharge changed or removed
+ *   (`details.outsideModifications`) beside the order's modification, and
+ *   `details.outstanding` and `details.unsettledModifications` would differ.
+ *   When the payment could not be recorded (`details.outsideModifications` is
+ *   set): if the edit's other changes (items, quantities, prices, coupons,
+ *   addresses, tax, an added surcharge) also change the total, save the change or
+ *   removal of the existing surcharges as an edit of its own; if they do not, an
+ *   earlier edit's changes are unpaid: record what the order owes for them first.
+ */
+export type OrderEditBlockerCode = 'ORDER_EDIT_NOT_ALLOWED' | 'ORDER_EDIT_NOTHING_TO_CHANGE' | 'ORDER_EDIT_FULFILLED_FLOOR' | 'ORDER_EDIT_REFUND_TARGET_MISSING' | 'ORDER_EDIT_REFUND_EXCEEDS_PAYMENT' | 'ORDER_EDIT_OVERPAYMENT_CHOICE_REQUIRED' | 'ORDER_EDIT_OVERPAYMENT_NOT_SETTLEABLE' | 'ORDER_EDIT_PERMISSION_REQUIRED' | 'ORDER_EDIT_STEP_REFUSED' | 'ORDER_OVERPAYMENT_REFUND_UNRECONCILED' | 'ORDER_EDIT_PAYMENT_STATE_UNREACHABLE' | (string & {});
+export interface OrderEditBlocker {
+    /** Map this to your own wording. */
+    code: OrderEditBlockerCode;
+    /** The platform's sentence, written for a merchant. */
+    message: string;
+    details: Record<string, unknown> | null;
+}
+/**
+ * Something the merchant should know that does not stop the edit. A string on
+ * the wire.
+ *
+ * - `ORDER_EDIT_TAX_UNCHANGED`: the tax choice already matches the order's tax.
+ * - `ORDER_EDIT_CUSTOMER_ADDRESS_NOT_SAVED`: the order's address is updated,
+ *   and the customer's saved address is not, because the address is incomplete.
+ * - `ORDER_EDIT_PAYMENT_OWED`: the edit raises a paid order's total on a credit
+ *   or manual payment. The order stays paid and the customer owes
+ *   `details.amount`, collected by hand or billed.
+ * - `ORDER_EDIT_ADDITIONAL_PAYMENT_REQUIRED`: the edit raises a paid order's
+ *   total on a payment collected online (a card, a POS terminal, a method the
+ *   store no longer has). The order waits in `ArrangingAdditionalPayment`, and
+ *   cannot ship, until `details.amount` is paid.
+ */
+export type OrderEditNoticeCode = 'ORDER_EDIT_TAX_UNCHANGED' | 'ORDER_EDIT_CUSTOMER_ADDRESS_NOT_SAVED' | 'ORDER_EDIT_PAYMENT_OWED' | 'ORDER_EDIT_ADDITIONAL_PAYMENT_REQUIRED' | (string & {});
+export interface OrderEditNotice {
+    code: OrderEditNoticeCode;
+    message: string;
+    details: Record<string, unknown> | null;
+}
+/** Whether money was collected for the order, which decides how its total may be lowered. */
+export interface OrderEditPayment {
+    collected: boolean;
+    /**
+     * Why it counts as collected: `settled`, `gateway-hold`, or
+     * `unresolved-method` (an authorized payment whose method is no longer on
+     * the store). `null` when nothing was collected.
+     */
+    reason: 'settled' | 'gateway-hold' | 'unresolved-method' | (string & {}) | null;
+    /** The payment method the reason is about, when it has one. */
+    method: string | null;
+}
+export interface OrderEditTaxSummaryLine {
+    description: string;
+    /** A percentage. */
+    taxRate: number;
+    taxBase: number;
+    taxTotal: number;
+}
+/**
+ * The order's totals after the edit, as the pricing engine computes them.
+ * Every figure is minor units in `currencyCode`.
+ */
+export interface OrderEditPreview {
+    currencyCode: string;
+    /** Lines and surcharges, net. */
+    subTotal: number;
+    subTotalWithTax: number;
+    shipping: number;
+    shippingWithTax: number;
+    /** The order's surcharges, net. Already part of `subTotal`. */
+    surcharges: number;
+    surchargesWithTax: number;
+    total: number;
+    totalWithTax: number;
+    taxSummary: OrderEditTaxSummaryLine[];
+    /** The order's total with tax before the edit. */
+    totalWithTaxBefore: number;
+}
+export interface OrderEditPlan {
+    orderId: string;
+    /**
+     * Names this plan of this edit of the order as it stands. `commitEdit` is
+     * handed it and refuses (`ORDER_EDIT_PLAN_CONFLICT`) a plan that moved.
+     */
+    planHash: string;
+    /**
+     * Names the order as the plan read it. It moves when anything a plan depends
+     * on moves, and stays for a change a plan does not read (a note, for one).
+     */
+    orderVersion: string;
+    steps: OrderEditStep[];
+    /**
+     * The refund the edit ends with when nothing is chosen into it: what it
+     * gives back automatically (item prices and quantities cut). With an
+     * `overpayment` settled by `REFUND`, the edit ends with
+     * `overpayment.refundWhenChosen` instead.
+     */
+    refund: OrderEditRefund | null;
+    /**
+     * On a paid order whose edit lowers or removes a surcharge: what that leaves
+     * the customer overpaid by, and how it may be settled. `commitEdit` needs
+     * `overpaymentChoice` for it. `null` when there is nothing to choose.
+     */
+    overpayment: OrderEditOverpayment | null;
+    /**
+     * The state the order is left in: the one it returns to after a
+     * `MODIFY_ORDER` step, or `ArrangingAdditionalPayment` when the edit raises
+     * what the customer of a paid order owes on a payment collected online.
+     * `null` when the order's state does not change.
+     */
+    returnState: string | null;
+    /** Everything that stops this edit from being carried out, as far as running its steps shows. */
+    blockers: OrderEditBlocker[];
+    notices: OrderEditNotice[];
+    payment: OrderEditPayment;
+    /** `null` when a blocker kept the preview from reaching the end. */
+    preview: OrderEditPreview | null;
+}
+/**
+ * Its own document on purpose: `planOrderEdit` exists only on an engine with
+ * the order-edit plan, so on an older one this call alone fails validation and
+ * no other order call does.
+ */
+export declare const PLAN_ORDER_EDIT_QUERY = "\n  query PlanOrderEdit($orderId: ID!, $diff: OrderEditDiffInput!) {\n    planOrderEdit(orderId: $orderId, diff: $diff) {\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        }\n        accountCredit {\n          available\n          code\n          message\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  }\n";
+export interface OrderPlanEditModule {
+    /**
+     * How an edit of a placed order would be carried out, and what the order
+     * would cost after it. Needs `UpdateOrder`, and an engine that serves
+     * `planOrderEdit`.
+     *
+     * State what should change as a `diff` of intents. The server decides the
+     * steps: which changes are a cancellation, which are written directly
+     * because no money was collected, which go through an order modification,
+     * and what is refunded. It then runs those steps in a transaction it always
+     * rolls back, so `preview` holds the pricing engine's own totals and a step
+     * the engine would refuse is found here.
+     *
+     * Nothing is saved, no event is published and no payment provider is
+     * contacted. A store's tax provider app may be asked, as it is for any
+     * re-price. Call it after the merchant stops typing, not on every keystroke.
+     *
+     * Read `blockers` first. It lists every reason the edit cannot be carried
+     * out: it is an answer, not an error, so that a head can show them all beside
+     * the steps. `preview` is `null` when a blocker kept the run from reaching
+     * the end; it is still answered for a plan with no steps (the order as it
+     * is), and beside `ORDER_EDIT_REFUND_EXCEEDS_PAYMENT` and
+     * `ORDER_EDIT_OVERPAYMENT_NOT_SETTLEABLE` (what the edit would cost).
+     *
+     * `steps` are in the order they run, each with its `moneyEffect` on the
+     * order's total with tax. `refund` is what an edit of a paid order returns
+     * to the customer automatically, on the one payment that can carry the
+     * whole amount.
+     *
+     * `overpayment` is set when the edit lowers or removes a surcharge on a paid
+     * order: the merchant chooses, before saving, whether that difference is
+     * refunded to the customer's payment or credited to their account. Show the
+     * amount and both options (a closed one with its `message`), and pass the
+     * answer to `commitEdit` as `overpaymentChoice`.
+     *
+     * While it runs the plan holds the order: another change of the same order
+     * waits for it, and a plan that cannot get the order within a few seconds is
+     * refused with `ORDER_BUSY`. Nothing was read or changed then, so asking
+     * again is safe.
+     *
+     * Keep `planHash` with what you show: `commitEdit` carries the edit out and
+     * names it, so what is saved is what the merchant saw.
+     *
+     * Refusals of the call:
+     * - `ORDER_EDIT_ORDER_NOT_FOUND`, `ORDER_EDIT_LINE_NOT_FOUND`,
+     *   `ORDER_EDIT_SURCHARGE_NOT_FOUND` and `ORDER_EDIT_VARIANT_NOT_FOUND`
+     *   (`NotFoundError`, 404). An order of another store answers like a missing
+     *   one, and so does a line or surcharge of another order and a deleted
+     *   variant. An id that is not a uuid is refused before that with core's
+     *   `ENTITY_NOT_FOUND`, also a `NotFoundError`: branch on the class for
+     *   not-found, not on one code.
+     * - `INVALID_ORDER_EDIT_DIFF` (`ValidationError`, 400), with a message that
+     *   names the field: a quantity or amount out of range, an id given twice in
+     *   one list, a change staged on a line the same diff removes, a
+     *   `FIXED_PRICE` whole-order discount, a surcharge of 0, `applyToCustomer`
+     *   together with `markTemporary: true`, more than 500 entries in a list.
+     * - `ORDER_EDIT_CHANNEL_NOT_ALLOWED` (`PermissionDeniedError`, 403): the call
+     *   was made from the default channel instead of the order's own.
+     * - `ORDER_BUSY` (`ConflictError`, 409): another change of the order was
+     *   still being applied. Ask again.
+     */
+    planEdit(orderId: string, diff: OrderEditDiff, options?: Call): Promise<OrderEditPlan>;
+}
+export declare function createOrderPlanEditModule(transport: Transport): OrderPlanEditModule;

package/dist/orders/plan-edit.js

@@ -0,0 +1,93 @@
+/**
+ * Its own document on purpose: `planOrderEdit` exists only on an engine with
+ * the order-edit plan, so on an older one this call alone fails validation and
+ * no other order call does.
+ */
+export const PLAN_ORDER_EDIT_QUERY = /* GraphQL */ `
+  query PlanOrderEdit($orderId: ID!, $diff: OrderEditDiffInput!) {
+    planOrderEdit(orderId: $orderId, diff: $diff) {
+      orderId
+      planHash
+      orderVersion
+      steps {
+        kind
+        input
+        moneyEffect
+      }
+      refund {
+        paymentId
+        amount
+      }
+      overpayment {
+        amount
+        currencyCode
+        surchargeIds
+        refund {
+          available
+          code
+          message
+        }
+        accountCredit {
+          available
+          code
+          message
+        }
+        refundWhenChosen {
+          paymentId
+          amount
+        }
+      }
+      returnState
+      blockers {
+        code
+        message
+        details
+      }
+      notices {
+        code
+        message
+        details
+      }
+      payment {
+        collected
+        reason
+        method
+      }
+      preview {
+        currencyCode
+        subTotal
+        subTotalWithTax
+        shipping
+        shippingWithTax
+        surcharges
+        surchargesWithTax
+        total
+        totalWithTax
+        taxSummary {
+          description
+          taxRate
+          taxBase
+          taxTotal
+        }
+        totalWithTaxBefore
+      }
+    }
+  }
+`;
+export function createOrderPlanEditModule(transport) {
+    return {
+        async planEdit(orderId, diff, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: PLAN_ORDER_EDIT_QUERY,
+                // The diff goes out as given, never normalised: `orderDiscount` left
+                // out, `null` and a value are three different requests to the engine
+                // (keep, remove, set). `JSON.stringify` drops a key that is
+                // `undefined` and keeps a `null`, so a default here would turn
+                // "keep" into "remove".
+                variables: { orderId, diff },
+            }, options);
+            return data.planOrderEdit;
+        },
+    };
+}