@sixtyninecommerce/admin 0.8.0 → 0.9.0

package/README.md

@@ -49,6 +49,10 @@ const me = await admin.auth.login('user@example.com', 'secret');
 const tenant = admin.withTenant({ scope: { kind: 'channel', code: me.channels[0]!.code } });
 ```
 
+Each of `me.channels` carries `channelKind` — `'hub'` for an organization's workspace, which is
+never a store, anything else a store — and `organizationId`, the organization a store belongs to or
+whose workspace a hub is (`null` for neither).
+
 **The session object you pass IS where the bearer is stored.** Vendure returns a fresh one on a
 response header and the SDK writes it back into `session.token`, so it must be writable — a plain
 property, or a getter with a setter over your own store. A read-only one is refused at construction
@@ -78,8 +82,14 @@ Treat "signed in" as "`auth.me()` resolved", never as "a token is stored".
 
 `apiTokens.*` needs a human session. The engine strips `ManageApiToken` from every token it
 issues, so a token can never manage tokens — including its own — and `platform.*` refuses a token
-in the SDK before the request leaves the process. Mint and revoke credentials from a signed-in
-session:
+in the SDK before the request leaves the process. A token also never obtains a login that
+outlives it: `pos.devices.pair` (and creating a POS device), creating or re-roling a staff member,
+setting a staff password or login email, and creating or rotating a core API key all answer
+`PermissionDeniedError` with `TOKEN_CREDENTIAL_NOT_ALLOWED` or `TOKEN_API_KEY_NOT_ALLOWED`. A token
+may invite a new staff address with a role within its own permissions, when it carries no
+location restriction (`TOKEN_INVITE_NOT_ALLOWED` otherwise), and send a staff member a password reset (`requestAdministratorPasswordReset`): both mail
+the link to the recipient's own address. Mint and revoke credentials, and pair tills, from a
+signed-in session:
 
 ```ts
 const session: { token?: string } = {};
@@ -130,6 +140,87 @@ await admin.apps.approveConsent(installation.id, {
 Omit `grantedPermissions` and the installation keeps exactly what it had — the right default for an
 app that grew an event type or a metafield rather than a permission.
 
+An app may also ask to own **field groups** — `price`, `stock`, `product_details` and
+`customer_details`, each a fixed list of fields the platform defines (`App.declaredFieldOwnership`).
+Grant them by key in `grantedFieldOwnership` on `install` or `approveConsent`; any other value
+(an old `product.price` claim included) is refused with `FIELD_GROUP_INVALID`.
+
+#### Field groups: one owner per group per store
+
+A store hands each field group to **one** owner at a time — an app installation or a personal API
+token (`apiTokens.create({ fieldOwnership })`). While it is owned, other writers are refused it
+(below).
+Every grant, on `install`, `approveConsent`, `apiTokens.create` and `apiTokens.update`, is judged
+by the same rules, and only for the groups it ADDS (a group the owner holds already passes):
+
+| Refusal | Class | When |
+| --- | --- | --- |
+| `FIELD_GROUP_PERMISSION_MISSING` | `BusinessRuleError` | the app or token holds no permission that changes the group (Price and Product details: `UpdateCatalog` or `UpdateProduct`; Stock: one of those, `AdjustStock` or `UpdateStockLocation`; Customer details: `UpdateCustomer`) |
+| `FIELD_GROUP_GRANT_NOT_ALLOWED` | `PermissionDeniedError` | you cannot change that data yourself on the store |
+| `FIELD_GROUP_OWNER_CONFLICT` | `ConflictError` | another app or token owns it here (a suspended app's claim still counts) |
+| `FIELD_GROUP_ERP_SYNCED` | `BusinessRuleError` | Exact Online is connected (it writes all four groups), or the store belongs to an organization (Price and Product details) |
+
+```ts
+const owners = await admin.tenant.fieldGroupOwners();
+// [{ group: 'price', ownerKind: 'app_installation', ownerId, label: 'Acme ERP', appSlug: 'acme-erp', paused: false }]
+const synced = await admin.tenant.fieldGroupSyncSources();
+// [{ group: 'price', source: 'exact', label: 'Exact Online' }, …]
+
+// One click, recorded: the group comes off its owner, audited and announced as
+// `app.field_ownership_changed`. InstallApps for an app's group, ManageApiToken for a token's.
+await admin.apps.releaseFieldGroup({ kind: 'app_installation', id: owners[0].ownerId }, 'price', {
+  idempotencyKey: crypto.randomUUID(),
+});
+```
+
+An approval or a token update that does not name the groups keeps them, but drops a group the new
+permissions can no longer change. An app or token reads what it owns from `auth.whoami()`
+(`fieldOwnership`).
+
+#### Field groups: what an owned group refuses
+
+While an app or API token owns a group on a store, every OTHER writer through the Admin API is
+refused a change of that group's data with `FIELD_GROUP_LOCKED` (`BusinessRuleError`, 422): staff
+(a SuperAdmin included), other apps and tokens, bulk imports and pipelines. The owner's own calls
+pass, and so does a bulk import it submitted. A suspended owner holds nothing until it resumes; an
+installation waiting for consent still holds its groups.
+
+```ts
+try {
+  await admin.catalog.variants.update([{ id, price: 1999, priceBasis: 'gross' }]);
+} catch (error) {
+  if (error instanceof BusinessRuleError && error.code === 'FIELD_GROUP_LOCKED') {
+    // error.details: [{ field: '/input/0/price', code: 'FIELD_GROUP_LOCKED',
+    //   message: 'Prices on this store are managed by the app "Acme ERP". …' }]
+  }
+}
+```
+
+- **An unchanged value passes.** A field sent with the value it already holds is not a change: it
+  is left out of the write, so the owner keeps its "managed by" provenance. Send whole records if
+  you like; only the values you change are judged.
+- **What counts:** updating a group's fields on an existing product, variant, customer or address;
+  deleting a product, variant or customer whose groups are owned; adding, changing or removing a
+  customer's address; linking or unlinking a product's option groups; a stock adjustment, a stock
+  transfer's stock moves, and deleting a location that holds stock.
+- **What never counts:** creating a record; a stock move that follows an order (a sale, a
+  reservation, a fulfilment, a return put back in stock); a shopper editing their own details on
+  the storefront; price lists, visibility, metadata and documents, which are in no group.
+- **Shared rows.** A record several stores hold is one row: its product details, its customer
+  details, and a variant's tax class, cost price and stock settings (tracking, thresholds,
+  backorders). An owner in another store holding the record counts for those too; the refusal
+  names it only as "another store's app" (or API token), and only that owner can change them. The
+  same app installed in both stores is one owner. A variant's prices and stock levels are each
+  store's own, so only this store's owner counts for them.
+- **Customer data your app cannot read.** When your app's customer-data level hides a field, a
+  value you send for it is judged a change even when it equals the stored one: the lock never
+  tells you whether you guessed a value you may not read.
+- **Not refused yet** (a later release): product property values, values a deleted facet, option
+  group or asset takes off products, filter values a collection's rules assign, a store's price
+  written when products are assigned to it, the platform's translation repair, an order import
+  filling a customer's empty fields, an order's address saved into an empty address book, and the
+  warehouse stock feed.
+
 ```ts
 // App side — the app authenticates as itself. No token handling.
 const app = createAdminClient({
@@ -284,7 +375,10 @@ exception — it writes through to the stock location's own field, so omit it to
 alone and pass `null` to clear it. `get()` answers `null` when a stock location has no profile, and
 `delete()` answers `false` when there was none; neither is an error. Refusals arrive as
 `LOCATION_CODE_TAKEN` (`ConflictError`), `INVALID_TIMEZONE` / `INVALID_OPENING_HOURS` /
-`INVALID_ADDRESS` (`ValidationError`) and `LOCATION_NOT_FOUND` (`NotFoundError`).
+`INVALID_ADDRESS` (`ValidationError`) and `LOCATION_NOT_FOUND` (`NotFoundError`). A token or app
+installation restricted with `locationIds` changes or clears the `address` (the location's parcel
+sender) only at a location it holds, `LOCATION_NOT_ALLOWED` (`PermissionDeniedError`) otherwise;
+sending the stored address back unchanged passes.
 
 An API token can be pinned to a set of them, after which it may only send an `x-location` naming
 one of those (`LOCATION_NOT_ALLOWED` otherwise, enforced on the Admin API today):
@@ -305,6 +399,195 @@ caller means, so pass `null` to lift the restriction instead.
 plugins `GET /me` projection still answers `null` for every principal — read `apiTokens.list()` for
 the restriction a token actually carries until that is wired.
 
+### Stock
+
+Stock per location by state, the ledger with the reason each movement was made, and adjustments
+that cannot be made without one. The tenant's `location` is the default place for all three.
+
+```ts
+const counter = admin.withTenant({ location: 'the-stock-location-id' });
+
+const [here] = await counter.stock.position('variant-id');
+// { onHand, allocated, available, incoming, reserved, trackInventory } — integer units
+
+await counter.stock.adjust(
+  { variantId: 'variant-id', delta: -2, reason: 'damaged in transit', referenceDocumentRef: 'DMG-114' },
+  { idempotencyKey: idempotencyKey() },
+);
+
+for await (const movement of await admin.stock.movements('variant-id', { type: 'ADJUSTMENT' })) {
+  console.log(movement.quantity, movement.reason, movement.referenceDocumentRef);
+}
+```
+
+`available` is `onHand − allocated − threshold` (the location's out-of-stock threshold, else the
+variant's), exactly what the allocator can still reserve there, and it is **not** floored: an order
+allowed to backorder shows as a negative figure. `reserved` is what a positive threshold holds back.
+
+`reason` is required on every adjustment and is yours to word — the platform never interprets it.
+A location another store owns is refused with `LOCATION_NOT_IN_CHANNEL`, and a token or app pinned to some locations (`locationIds`) is refused `LOCATION_NOT_ALLOWED` elsewhere and reads only its own when it names none; at a location you share
+with another store, both see the same levels and movements but each only its own reasons. A
+decrease may not take on-hand below zero (`STOCK_WOULD_GO_NEGATIVE`). The adjustment reaches event
+subscribers as `stock.level_changed` (`cause: 'adjustment'`, no reason) and as `stock.adjusted`,
+which carries the reason and reference and is flagged as personal data.
+
+`stock.transfers.*` wraps the stock-transfer module (create → ship → receive → close, or cancel;
+`postConsumption` for a one-location consumption) — its `note` and `cancelReason` stay on the
+transfer. A credential restricted with `locationIds` is refused `LOCATION_NOT_ALLOWED`
+(`PermissionDeniedError`) unless it holds the end the call acts for: the source (whose stock is
+debited) to `create`, `createReturn`, `update`, `ship`, `postConsumption` or `cancel`, the
+destination to `receive`, either end to `close` (the source when the close sends a line back to
+it); it lists, and can `get`, only transfers with an end it holds. Each step reaches event
+subscribers as `stock_transfer.created`, `.shipped`, `.shipment_removed`, `.received`
+(`completed_by`: `receive`, `close`, or `post` for a consumption) and `.cancelled`, which does not
+carry the `cancelReason`: read it with `stock.transfers.cancellation(id)`.
+`stock.allocations.release(orderId)` hands back everything a stuck, unfulfilled order has reserved
+without changing its state.
+
+### Closing a transfer with a shortfall
+
+`close` ends an in-transit transfer as received. A line still short is settled per line: `LOST`
+writes its unaccounted units off, `RETURN_TO_SOURCE` credits them back to the source location
+(they never left, or came back). A line `shortfall` does not name is written off as lost only with
+`acceptShortfallAsLost`; otherwise the close is refused, as it is for a line named twice, a line of
+another transfer or a line with nothing outstanding (`ValidationError`, nothing changed).
+
+```ts
+await admin.stock.transfers.close(transferId, {
+  acceptShortfallAsLost: true, // every line not named below is written off as lost
+  shortfall: [{ lineId, disposition: 'RETURN_TO_SOURCE' }],
+});
+const settled = await admin.stock.transfers.shortfall(transferId); // null if absent
+// { transferId, state, totalLostQuantity, totalReturnedToSourceQuantity,
+//   lines: [{ lineId, variantId, sku, quantity, receivedQuantity, lostQuantity,
+//   returnedToSourceQuantity, outstandingQuantity }, …] }
+```
+
+`shortfall(id)` is its own request and `get` never asks for the returned quantity, so a caller
+ahead of the engine sees only `shortfall(id)` and a `close` with `shortfall` refused.
+
+### Stock transfer returns
+
+Stock sent somewhere temporary (an event, a pop-up) comes back as a **return**: an ordinary
+transfer with its own code, linked to the transfer it reverses. Its source is pinned to that
+transfer's destination, where the goods are; its destination is any other location of the store.
+Each variant is capped at what the transfer received minus its returns that are not cancelled, so
+nothing received means nothing returnable, and what is not returned stays where it is.
+
+```ts
+const links = await admin.stock.transfers.returns(transferId); // ReadStockLocation; null if absent
+// { returnOfTransferId, returnOf, returns: [{ id, code, state, label, sourceLocation,
+//   destinationLocation, createdAt, totalQuantity }, …],
+//   returnableLines: [{ variantId, sku, variantName, receivedQuantity, returnedQuantity,
+//   returnableQuantity }, …] }
+const back = await admin.stock.transfers.createReturn(transferId, {
+  destinationLocationId: warehouseId, // any location of the store but the return's source
+  label: 'Event ABC',
+  lines: [{ variantId, quantity: 12 }], // ≤ returnableQuantity per variant
+});
+await admin.stock.transfers.ship(back.id); // then receive / close / cancel like any transfer
+
+const eventReturns = await admin.stock.transfers.list({ returnOfTransferId: transferId });
+const plainTransfers = await admin.stock.transfers.list({ isReturn: false });
+```
+
+Only a `transfer` (not a consumption, not itself a return) in transit or received can be
+returned (`STOCK_TRANSFER_NOT_RETURNABLE`); a quantity above the cap, or a variant not on the
+transfer, is `RETURN_QUANTITY_EXCEEDS_RECEIVED` (also on an `update` of a return draft's lines),
+and an `update` moving a return's source is `RETURN_SOURCE_LOCKED` — each a
+`BusinessRuleError`. `createReturn` needs `AdjustStock` (or the older `UpdateStockLocation`), like
+every transfer write, and a credential restricted with `locationIds` must hold the return's
+source, which is the original transfer's destination. A cancelled return frees its quantity
+again. `returns(id)` is its own request and `get` / `list` select none of its fields, so a caller
+ahead of the engine sees only `returns`, `createReturn` and a list naming the return filters
+refused.
+
+### Stock transfer parcels
+
+A transfer shipped with MyParcel as N parcels (`ship(id, { fulfillmentHandlerCode: 'myparcel',
+handlerArgs: { parcelCount: 2, … } })`) is booked as N MyParcel shipments, one label and one
+barcode each. The booking happens inside `ship`, one MyParcel call per parcel, so `ship` (like
+`cancel`, which voids every parcel, and `retryMyparcelShipments`) is allowed up to 120 s; a
+`REQUEST_TIMEOUT` or an abort there does not mean the call failed, so read the transfer again
+before repeating it. The labels and barcodes follow in jobs after `ship` returns.
+
+```ts
+const shipment = await admin.stock.transfers.parcels(transferId); // ReadStockLocation
+// { parcelCount: 2, parcels: [{ ordinal: 1, shipmentId, barcode, labelReady, lastError }, …],
+//   trackingCodes, lastError, state, fulfillmentHandlerCode }
+if (shipment?.lastError && shipment.parcels.length < (shipment.parcelCount ?? 1)) {
+  await admin.stock.transfers.retryMyparcelShipments(transferId); // books only what is missing
+} else if (shipment?.parcels.some((parcel) => !parcel.barcode)) {
+  await admin.stock.transfers.labelMyparcelParcels(transferId); // labels only, one job
+}
+const label = await admin.stock.transfers.myparcelLabel(transferId, 'A6'); // one merged PDF
+```
+
+`parcels` lists the parcels BOOKED so far, so it is shorter than `parcelCount` while the booking
+runs or after it stopped part-way; `lastError` then says why, and `retryMyparcelShipments` books
+exactly the missing ones (a parcel MyParcel already holds is adopted, never booked twice). On a
+draft whose shipment was removed, `lastError` names any parcel MyParcel refused to void. Several
+parcels to a destination outside the EU customs union are refused at `ship`
+(`PARCEL_COUNT_NEEDS_CUSTOMS`) before any stock moves. The merged label is printable only while the
+transfer is in transit (`MYPARCEL_LABEL_NOT_AVAILABLE` otherwise).
+
+`labelMyparcelParcels(transferId)` queues one job that labels every booked parcel still missing its
+label or barcode (never asking twice for one that has it) and answers the parcels as they stand;
+read `parcels()` again for the labels. Once every parcel is booked it does what
+`retryMyparcelShipments` does, without the booking step; with a parcel not booked it is refused
+(`MYPARCEL_LABEL_NOT_AVAILABLE`), as it is outside transit.
+
+`unretractedShipments` lists the MyParcel shipments a removed shipment or a cancel could not
+retract: MyParcel deletes only concepts, and keeps a registered label. The same record as a
+fulfillment's (`unretractedShipmentsOfOrder`, below); it survives a re-ship.
+
+### Stock transfer cancellation
+
+`cancel(id, { reason })` cancels a draft, or an in-transit transfer whose units are back on the
+source (less any recorded lost). It voids every MyParcel parcel itself, but nothing reaches
+Hendriks: a transfer exported to Hendriks is cancelled here while its BluJay order still stands.
+
+```ts
+const before = await admin.stock.transfers.cancellation(transferId); // ReadStockLocation
+if (before?.hendriksExport) {
+  // Warn first: after the cancel, Hendriks must be asked to retract this order, or it ships.
+  console.warn(`Ask Hendriks to retract ${before.hendriksExport.bluJayOrderNumber}`);
+}
+await admin.stock.transfers.cancel(transferId, { reason: 'Event called off' });
+const after = await admin.stock.transfers.cancellation(transferId);
+// { state: 'cancelled', cancelledAt, cancelReason, cancelledBy: { id, firstName, lastName },
+//   hendriksExport: { bluJayOrderNumber } | null }
+```
+
+`cancelledBy` is null for a transfer cancelled before the engine recorded who did. `cancellation`
+is its own request and `get` / `list` / `cancel` select none of its fields, so a caller ahead of
+the engine sees only `cancellation` refused.
+
+### Parcel count suggestion
+
+```ts
+const suggestion = await admin.shipping.parcelCountSuggestion({
+  items: [
+    { productVariantId: bottleId, quantity: 6 }, // from one order
+    { productVariantId: whiteId, quantity: 6 },  // from another
+  ],
+  destinationCountryCode: 'CH',
+});
+// { count: 1, resolvable: true, exact: true, destinationRequiresCustoms: true, ... }
+```
+
+How many parcels the **active** channel's parcel-count rule gives a set of variant + quantity items,
+for prefilling a fulfilment: a consolidated group sends the selected items of all its orders. Items
+of one variant are summed. `resolvable: false` (`reason: 'NO_PARCEL_RULE'`) means the store has no
+rule and `count` is 1; `exact: false` means some variants lack the data the rule needs, so `count`
+is a lower bound. `reason` and `warnings` are codes (`UNIT_OVER_MAX_WEIGHT`, `CAPPED`), and new ones
+may appear. The destination is optional and only answers `destinationRequiresCustoms`.
+
+1 to 500 items with a quantity of 1 to 100,000 each, and a two-letter country code; anything else is
+refused before any request with `PARCEL_COUNT_INPUT_INVALID` (`ValidationError`). A variant that is
+unknown, or another store's, is `PARCEL_COUNT_VARIANT_NOT_FOUND` (`NotFoundError`). Needs
+`ReadCatalog` or `ReadFulfillment`.
+
 ### Retention and legal holds
 
 ```ts
@@ -318,10 +601,76 @@ Always the **active** channel — there is no channel argument, which is what le
 token hold its own store and reach no other. `retentionClass` is free text (default `standard`) that
 the platform stores and does not interpret yet. While any hold stands, or `holdUntil` is in the
 future, a hard delete of the store is refused with `RETENTION_HOLD_ACTIVE` (`BusinessRuleError`).
+A named hold also refuses every customer erasure on the store (`customers.erase`); the `holdUntil`
+window alone does not, because an erasure keeps the records the window protects.
 `release()` lifts only the calling principal's own hold: another's is `RETENTION_HOLD_NOT_YOURS`
 (`PermissionDeniedError`) unless you are a SuperAdmin, which releases every hold. A bad class or
 instant is `RETENTION_INPUT_INVALID` (`ValidationError`).
 
+A **sandbox store** (`platform.provisionStore({ sandbox: true })`) bypasses holds: a hold can be
+placed on it, but never stops its hard delete. The bypass leaves an audit row
+(`retention.hold.sandbox_bypass`) naming what it stepped over.
+
+### Transactional emails per event
+
+```ts
+const configs = await admin.tenant.notifications.list();           // one entry per notification event
+await admin.tenant.notifications.update('order_placed', { sender: 'none' });  // your system sends it
+await admin.tenant.notifications.update('order_placed', {
+  enabled: true,
+  recipients: { bcc: [{ type: 'text', value: 'orders@example.com' }] },    // replaces that list only
+});
+```
+
+`sender: 'none'` stops the platform sending that email; your own system sends one in its place from
+the matching platform event, and every dispatch the platform skips is still written to the store's
+email delivery log (status `skipped`, `metadata.skipReason: 'SENDER_NONE'`). Each accepted update
+emits one `notification_config.changed` with the resulting `enabled` and `sender`. Identity emails
+(the `account` category: password reset, magic link, invitation, email change, email and chat
+verification) refuse `none` with `EVENT_ALWAYS_PLATFORM_SENT` (`ValidationError`): they carry a
+one-time credential no platform event carries. Every entry's `replacementEventTypes` names the
+platform events your system sends that email from (`order_placed` → `['order.created']`); where it
+is `null` no emitted event replaces the email and `none` is refused with `NO_REPLACEMENT_EVENT`
+(`ValidationError`), so a store never silently loses an email. An unknown event is `NOTIFICATION_EVENT_NOT_FOUND`
+(`NotFoundError`). `password_reset`, `email_change` and `account_setup` cannot be switched off: each is
+the only way a customer resets a password (or sets the first one on an imported account), confirms
+a new address, or finishes a storefront registration. `enabled: false` on them is refused with
+`EVENT_ALWAYS_ENABLED` (`ValidationError`, the message naming the event's reason), and `list`
+always answers them enabled. `magic_link_login` and `customer_invite` can be switched off. Both methods need `UpdateSettings` and act on the active channel.
+
+The identity emails (the `account` category) and `new_customer` carry sign-in links or codes, and
+one login serves the person in every store, so they go to the account holder alone: their
+`recipients` are fixed (`to` the `customer_email` variable, `cc` and `bcc` empty), `list` answers
+exactly that, and any other list is refused with `IDENTITY_EMAIL_RECIPIENTS_FIXED`
+(`ValidationError`, `details[].field` naming each offending list). Resending what `list` answered
+is accepted.
+
+A store that takes `settings.email` from its organization (`admin.tenant.settingsSources`) sends the
+emails the platform sends for it by the organization's `enabled` and recipients (the platform default
+for an event the organization has none for), and `list` answers what applies. `sender` stays the
+store's own, and an email your system already sends (`sender: 'none'`) keeps the store's own entry
+whole, so the organization never changes what your head must do. `update` refuses any change,
+`sender` included, with `ORGANIZATION_SETTINGS_INHERITED`, or `MANAGED_BY_ORGANIZATION` when the
+organization locked the group (both `BusinessRuleError`, 422); resending an entry unchanged is
+accepted. Override the group to change them. The From address is always the store's own gateway's.
+
+### Parcel rule
+
+```ts
+await admin.shipping.parcelRule.get();   // { channelId, defaultParcelCapacity, maxParcelWeightGrams }
+await admin.shipping.parcelRule.set({ defaultParcelCapacity: 12 });          // 12 items per parcel
+await admin.shipping.parcelRule.set({ maxParcelWeightGrams: 20_000 });       // other key unchanged
+await admin.shipping.parcelRule.set({ defaultParcelCapacity: null });        // no rule: one parcel
+```
+
+How the **active** channel counts parcels for extra-parcel shipping charges. `set` is a patch: a key
+left out is unchanged and `null` clears it. `defaultParcelCapacity` is a whole number from 1 to
+10,000 (a variant may override it); `maxParcelWeightGrams` is 1 to 70,000 grams and only adds
+parcels when variants carry a package weight. A value out of range, or an empty input, is refused
+before any request with `PARCEL_RULE_INVALID` (`ValidationError`); the engine enforces the same
+bounds for every other writer. Writing needs `UpdateChannel`. Pricing reads the rule from the
+engine's channel cache, so another process sees a change once that cache refreshes.
+
 ### Audit
 
 The tenant's own forensic trail. It needs the `ReadAudit` permission, which is deliberately outside
@@ -342,6 +691,74 @@ and the two arrays are meant to be read together. `metadata`, `requestBody` and
 their own key spellings, because they are evidence of what a vendor actually sent. A trace this
 tenant did not touch answers two empty arrays rather than an error.
 
+### Provenance: who changed it last
+
+Every change to a product, a variant or a customer records who made it, per **field group**:
+`price`, `stock`, `product_details` and `customer_details`, the four groups an app can be granted.
+Staff, apps, API keys, imports and shoppers are all recorded, in the change's own transaction.
+
+```ts
+const groups = await admin.provenance.get('VARIANT', variantId);
+for (const group of groups) {
+  // Show "Managed by <name>" only when managedBy is set: an app or key of this store made the
+  // last change of that group. A staff, customer or job change clears it.
+  console.log(group.fieldGroup, group.actor.type, group.managedBy?.label ?? '-', group.writtenAt);
+}
+
+const page = await admin.provenance.list('PRODUCT', productIds); // at most 250 ids; one page
+```
+
+It keeps the **last writer only**, one row per record and group. What changed and when, in order,
+is the platform event log filtered by the record (`GET /event-log?aggregate_type=&aggregate_id=` in
+the plugins service, with `ReadPlatformEvents`).
+
+Only the store you act on: a record the store does not hold, and one it holds with nothing recorded
+since provenance began, both answer no rows (`get` throws `NotFoundError` `ENTITY_NOT_FOUND`). Products
+and variants need `ReadCatalog` or `ReadProduct`, customers `ReadCustomer`. `actor.label` is the
+app's or key's name, a job's `system:<name>`, or a staff member's name for a caller holding
+`ReadAdministrator`; it is never a customer's name. More than 250 ids is refused with
+`PROVENANCE_REQUEST_INVALID` (`ValidationError`).
+
+### Staff: adding a person to a store
+
+`users.ensure` brings a person to exactly the roles you name in the active store, as one call that
+is safe to repeat. Roles are named by store role template (`admin`, `orders`, `warehouse`,
+`catalog`, `content`, `viewer`; the store's `<store code>-<template>` role, created the first time a
+store needs it) or by the id of a role of the store.
+
+```ts
+const { outcome, administrator, invitationSent } = await admin.users.ensure({
+  emailAddress: 'jane@example.com',
+  roles: [{ template: 'orders' }],
+});
+// outcome: 'created'   a new account, invited by email to set a password
+//          'attached'  an existing account: its roles of this store alone replaced, others kept
+//          'restored'  a removed member of this store, brought back and invited again
+//          'unchanged' already exactly these roles here: nothing written, nothing mailed
+
+await admin.users.update({ id: administrator.id, firstName: 'Jane', lastName: 'Doe' });
+```
+
+- **Repeatable.** The same call again answers `unchanged`, so a retry after a lost answer is safe
+  and mails nobody twice. Two calls for one address at once make one account.
+- **One email per real change.** A new account and a restored one are invited; so is an account
+  given its first role in the store. Someone who already works there and only changes role is not
+  mailed.
+- **Your own ceiling.** Adding someone (a restore included), or a template role the store does
+  not have yet, needs `CreateAdministrator`; changing the roles of someone who already works in
+  the store `UpdateAdministrator`. Every role you hand out, and the account you change, must be
+  within your own permissions (`ROLE_CEILING_NOT_ALLOWED`, `ADMINISTRATOR_INVITE_NOT_ALLOWED`,
+  both 403).
+- **API tokens** may only invite a NEW address, with roles within the token's own permissions and
+  no location restriction (`TOKEN_INVITE_NOT_ALLOWED`); repeating an invite the account already
+  satisfies answers `unchanged`.
+- **Stores only.** An organization's workspace is refused (`ORGANIZATION_WORKSPACE_NOT_A_STORE`):
+  its `<code>-admin` role is the organization admin role.
+- A failed invitation email changes nothing (`INVITATION_EMAIL_NOT_SENT`, 422): repeat the call.
+
+`users.update` changes a staff member's names or login email (an API token may not change the
+login email). Roles change through `ensure`.
+
 ### Tenancy
 
 A client with no `tenant.scope` may only call `auth.*` and `channels.byCode()`; every other module
@@ -360,7 +777,7 @@ write is never deduplicated.
 |---|---|
 | `content.forms.upsertBySlug` | yes — the CMS replays the first response for the same key |
 | `seo.redirects.create` | yes — the plugins service does the same |
-| `locations.*`, `tenant.retention.*`, `apiTokens.*` | no — they are Admin API writes |
+| `locations.*`, `catalog.*`, `shipping.*`, `tenant.retention.*`, `tenant.notifications.*`, `apiTokens.*` | no — they are Admin API writes |
 | everything else | no; the key is recorded on the wire and acts on nothing |
 
 Where it is honoured, the same key with a **different** body is refused with 409. This SDK never
@@ -389,11 +806,11 @@ meta.settingsSchemas.ai_bot_defaults;         // …keyed by SETTING name, not c
 
 | Member | What it holds |
 |---|---|
-| `labels` | `orderState`, `returnState`, `returnReason`, `paymentStatus`, `fulfillmentStatus`, `fulfillmentHoldReason`, `subscriptionStatus`, `quoteStatus`, `settlementMethod`, `creditNoteKind`, `auditService`, `auditCategory`, `auditEventOutcome`, `auditCallOutcome` |
+| `labels` | `orderState`, `returnState`, `returnReason`, `paymentStatus`, `fulfillmentStatus`, `fulfillmentHoldReason`, `subscriptionStatus`, `quoteStatus`, `settlementMethod`, `creditNoteKind` (retail), `arCreditNoteKind` (accounts receivable), `auditService`, `auditCategory`, `auditEventOutcome`, `auditCallOutcome`, `notificationSender` |
 | `transitions` | `quote`, `return` (`from` → allowed `to`), `fulfillmentRank` |
 | `permissions` | `catalog`, `groups` (the role-editor grid), `roleTemplates`, `tokenTemplates` |
 | `plugins` | `catalog`, `groupLabels` |
-| `settingsSchemas` | a schema per opaque `Channel.customFields` column (ten today) |
+| `settingsSchemas` | a schema per opaque `Channel.customFields` column (eleven today) |
 
 **Member names are camelCase; the keys inside them are not.** Everything below a member is keyed by
 platform data — `items_received`, `past_due`, `PaymentSettled`, `order_status_rules`, a schema's own
@@ -404,12 +821,21 @@ Three things the settings schemas do not say out loud:
 
 - each describes the **decoded** value, while the column stores `JSON.stringify` of it — so
   validate `JSON.parse(customFields.socialLinks)` and write a string back;
-- a schema states the shape, not every rule. Only four of the ten columns are validated server-side
-  at all — for the other six a bad value is not refused on write, it is dropped or ignored on read,
-  with no error anywhere (each description says which it is). And one rule is inexpressible:
+- a schema states the shape, not every rule. Every column is refused on write when malformed, and
+  each description names the refusal. Six (`social_links`, both exempt-id lists,
+  `order_status_rules`, `order_deposit_policy`, `ai_bot_defaults`) answer `CHANNEL_SETTINGS_INVALID`
+  through `createChannel`/`updateChannel`: a `ValidationError` whose `details[].field` is
+  `customFields.<column>` and whose `details[].code` is the JSON Schema keyword the value broke
+  (`json` when it is not JSON at all), with the place inside the value in the message. Their rule
+  IS the published schema, plus one the schema cannot state: the two exempt-id lists hold at most
+  255 characters of JSON (`maxLength`). An update that sends a column's stored value back
+  unchanged is not judged, so a value stored before the check is still dropped or ignored on read
+  (each description says which). Some rules are inexpressible or looser:
   `shipping_countries` and `tax_exclusive_countries` both refuse `["US","us"]` on write as a
-  duplicate, which `uniqueItems` cannot see. Schema-valid means "worth sending", not "certain to be
-  accepted" — handle the `ValidationError`, and do not skip your own validation;
+  duplicate, which `uniqueItems` cannot see, while `commerce_path_prefix_translations` and
+  `storefront_stock_location_ids` are judged by a check looser than their schema. Schema-valid
+  means "worth sending", not "certain to be accepted" — handle the `ValidationError`, and do not
+  skip your own validation;
 - `transitions` is the state machine, not the whole gate. `return.approved → settled` is a legal
   edge that the service still refuses when the channel requires a receipt first, and
   `quote.approved → converted_to_order` is refused when the projected order misses the channel's
@@ -481,6 +907,157 @@ Read with `ReadSettings` and written with `UpdateSettings` — the same grants t
 `storefrontUrl` itself. A head an app installed (`installationId` set) is managed through that app's
 declarations and is refused here with `HEAD_APP_OWNED`.
 
+### Fulfillment parcels
+
+A fulfillment can ship as several parcels: one carrier shipment and one barcode each.
+
+```ts
+const parcels = await admin.fulfillments.parcelsOfOrder(orderId); // ReadOrder
+const tracking = await admin.fulfillments.parcelTracking(fulfillmentId); // warehouse entitlement
+const label = await admin.fulfillments.myparcelLabel(fulfillmentId, 'A6'); // one merged PDF
+const paid = await admin.fulfillments.chargedParcelCount({ stockLocationId, orderId }); // no ReadOrder
+const asked = await admin.fulfillments.labelMyparcelParcels(fulfillmentId); // UpdateOrder
+// { fulfillmentId, parcels: 2, missing: 1, queued: true }
+const kept = await admin.fulfillments.unretractedShipmentsOfOrder(orderId); // ReadOrder
+// [{ fulfillmentId, shipments: [{ shipmentId, verdict: 'KEPT', billable: true, resolvedAt: null, … }] }]
+```
+
+`parcelTracking().parcelTrackingCodes[i]` is parcel i+1's own barcode, `null` until it has one; the
+whole list is `null` when the carrier bookkeeping could not be read. `parcelsOfOrder()` returns
+the carrier's barcode list only while it starts with the fulfillment's `trackingCode`: a code typed
+at ship replaces `trackingCode` alone, and the list is then stale, so you get `[trackingCode]`.
+
+`labelMyparcelParcels(fulfillmentId, { format? })` acquires the label of every parcel that still
+misses its label or barcode, in one job, and reads each barcode back. `queued: false` means every
+parcel already had both and nothing was queued; `queued: true` means the job was queued, and the
+labels land when it has run, so re-read the fulfillment rather than trusting the answer as the
+outcome. With a `format` it asks again for every parcel's label in that format (the operator's
+request, even beside a ready label). It labels only: a parcel never booked is booked by the
+booking's Retry or a recreate. A refusal throws its coded error (`MYPARCEL_ORDER_NOT_FOUND_ERROR`
+for another store's fulfillment, `MYPARCEL_VALIDATION_ERROR` for a cancelled one or one holding no
+shipment) with the engine's message; a blank id or a format other than `A4`/`A6` is refused
+before any request with `MYPARCEL_LABEL_INPUT_INVALID`.
+
+`unretractedShipmentsOfOrder(orderId)` is, per fulfillment, what a cancel, a recreate or an
+abandoned booking could not retract at MyParcel, which deletes only concepts. Each entry's label
+must not be handed to the carrier. `verdict` is `KEPT` (MyParcel keeps it), `UNREACHABLE` (not
+deleted yet: MyParcel could not be reached, or refused; the engine retries), or `DELETED` /
+`ALREADY_GONE` for an entry a later attempt resolved (`resolvedAt` set; it stays listed).
+`billable` is `true`, `false` or `null`, and `null` means unknown. Times are ISO-8601 UTC. Its own
+request: an engine without the field refuses this call alone.
+
+`chargedParcelCount()` is the parcel count the customer paid shipping for, read from the order's
+"To ship" entry at that warehouse, so the Warehouse role can prefill it. It is a number only while
+that entry holds the whole order — every line, nothing of it in a fulfillment yet — since the
+count was paid for the whole order; otherwise, and for an order not priced per parcel, it is
+`null`. Pass the `includeIneligible`/`routing` the entry you show was read with.
+
+### Cancelling a fulfillment whose delivery charge was paid
+
+Cancelling a fulfillment takes its delivery charge off every order it charged. Where the customer
+had already paid it, the cancel says for EACH such order how the money goes back: a refund to their
+payment, or a credit to their account (offered only where the store keeps the customer's balance
+itself).
+
+```ts
+const { overpayments } = await admin.fulfillments.cancelPreview(fulfillmentId); // UpdateOrder
+// [{ orderId, orderCode, amount: 605, currencyCode: 'EUR',
+//    refund: { available: true, code: null, message: null },
+//    accountCredit: { available: false, code: 'AR_ACCOUNT_REQUIRED', message: '…' } }]
+const { fulfillment, settlements } = await admin.fulfillments.cancel(
+  fulfillmentId,
+  { overpayment: overpayments.map(({ orderId }) => ({ orderId, choice: 'REFUND' })) },
+  { idempotencyKey }
+);
+// settlements: [{ orderId, orderCode, amount: 605, currencyCode: 'EUR', choice: 'REFUND' }]
+```
+
+An order owing money with no choice is refused `FULFILLMENT_CANCEL_OVERPAYMENT_CHOICE_REQUIRED`
+(a `BusinessRuleError`), before anything is written and before the carrier is told; so is core's
+`transitionFulfillmentToState(id, "Cancelled")`, which cannot carry a choice. Neither way open for
+an order is `FULFILLMENT_CANCEL_OVERPAYMENT_NOT_SETTLEABLE`; a closed way chosen anyway answers its
+own refusal (`REFUND_METHOD_UNAVAILABLE`, `AR_ACCOUNT_IN_ERP`, …). The refund or credit is QUEUED
+with the cancel and made right after it commits, so read the order again for the refund itself; if
+it cannot be made, the order's history says so and why. A cancel made with no merchant present (an
+integration's own path) refunds automatically.
+
+### Product feeds
+
+A feed turns the catalogue into the XML a channel hands Google, Meta, TikTok or Pinterest. The
+configuration is the destination, the locale it is built in, and a **rule AST** that decides every
+output field.
+
+```ts
+const feed = await admin.feeds.create({
+  name: 'Google NL',
+  destination: 'google',
+  languageCode: 'nl',
+  country: 'NL',
+  currencyCode: 'EUR',
+  mappingJson: {
+    fields: [
+      {
+        target: 'g:color',
+        rules: [
+          {
+            when: { logic: 'and', conditions: [{ field: 'facet:colour', op: 'not_blank' }] },
+            value: { kind: 'lookup', source: { kind: 'field', field: 'facet:colour' }, tableName: 'colour_map' },
+          },
+        ],
+        transforms: [{ kind: 'truncate', maxLen: 70 }],
+      },
+    ],
+  },
+});
+
+const preview = await admin.feeds.preview({ ...draft, sampleSize: 20 }); // persists NOTHING
+await admin.feeds.regenerate(feed.id);
+const runs = await admin.feeds.runs(feed.id);      // newest first, failed runs included
+const issues = await admin.feeds.issues(feed.id);  // the LATEST successful run's findings
+await admin.feeds.rotateToken(feed.id);            // the old public URL stops resolving
+```
+
+`admin.feeds.destinations()` is the registry a builder offers targets from: per destination a
+`template` of `{ target, required, maxLen?, defaultSource? }`, where `defaultSource` fills a target
+the channel's own mapping left empty.
+
+Four namespaces hang off the same noun, because they are one workflow:
+
+| Namespace | What it holds |
+|---|---|
+| `internalFields` | computed values a mapping references as `internal:<name>`; `position` is server-assigned and a field may only read fields at a strictly LOWER position |
+| `lookupTables` | ordered substitution tables a `{ kind: 'lookup', tableName }` resolves through; first match wins, a miss yields `''`, and `entriesJson` is replaced WHOLESALE |
+| `categoryMappings` | the catalogue mapped onto the Google product taxonomy (`collection` → `facet_value` → `default`, only `approved` rows apply), plus `bulkStatus` for deciding a review queue by id or by confidence |
+| `taxonomy` | ranked search over the vendored Google taxonomy; the one part of this module that is not channel-scoped |
+| `ai` | queue a categorisation pass over the channel's collections, or propose a better `title` mapping for one feed |
+
+**The rule payloads ride verbatim.** `mappingJson`, `filtersJson`, `settingsJson`, `rulesJson`,
+`entriesJson`, `perDestinationJson`, `payloadJson`, `statsJson` and a template's `defaultSource` are
+stored and echoed byte-for-byte, so the AST inside them stays camelCase (`tableName`, `maxLen`,
+`caseInsensitive`, `excludeOutOfStock`) while every DTO around them converts. The same holds for the
+identifier-keyed maps a preview returns — `values` is keyed by feed target (`custom_label_0`),
+`appliedInternal` by internal-field name, `issueCounts` by issue code. Nothing inside any of them is
+renamed; a corrupted `table_name` resolves to the empty string at generation time and reaches a
+merchant as a blank field in a live feed, never as an error.
+
+Rules are compiled before they are written, so a bad one is a `ValidationError` with code
+`INVALID_RULES` whose `details[0].field` is the AST coordinate that failed
+(`mapping.fields[2].rules[0].value.pattern`) — enough to put the message on the rule that caused it.
+Deleting an internal field or a lookup table a rule still references is a `ConflictError`
+(`FIELD_IN_USE` / `TABLE_IN_USE`).
+
+The AI methods split availability two ways on purpose: the READS answer 200 with
+`aiAvailable: false` when the platform has no model configured, so a page can render the hint
+without an error state, while the WRITES refuse with a 409 `AI_UNAVAILABLE` — `isAiUnavailable(error)`
+tells that apart from a model that merely failed, which is worth retrying. Nothing the model
+produces is ever applied on its own: a pass writes `suggested` category mappings for
+`categoryMappings.bulkStatus` to decide, and a title preset is a proposal until
+`ai.acceptSuggestion(id)` merges it through the same compile-before-write path a hand-edited
+mapping takes.
+
+Reads need `ReadCatalog` and writes `UpdateCatalog`, and every route is gated on the
+`product-feeds` entitlement.
+
 ### Tax classes
 
 Tax categories and their rates are **platform-wide**, shared by every store. A tax class is your
@@ -512,6 +1089,338 @@ order, because `delete` is refused with `TAX_CLASS_IN_USE` while variants still
 Read with `ReadSettings` and written with `UpdateSettings` — deliberately not the tax-category
 permissions, which govern the table every store shares.
 
+### Catalog
+
+Products, variants, option groups, facets, collections, assets, storefront visibility and product
+properties, one namespace each (`admin.catalog.*`). Lists are `Page`s over the Admin API's
+`skip/take`; every following page keeps the filter and the per-call tenant.
+
+```ts
+const size = await admin.catalog.options.groups.create({
+  code: 'size',
+  translations: [{ languageCode: 'en', name: 'Size' }],
+  options: [
+    { code: 'm', translations: [{ languageCode: 'en', name: 'M' }] },
+    { code: 'l', translations: [{ languageCode: 'en', name: 'L' }] },
+  ],
+});
+const product = await admin.catalog.products.create({
+  translations: [{ languageCode: 'en', name: 'Linen shirt', slug: 'linen-shirt' }],
+  availabilityState: 'preorder',                  // none | comingSoon | preorder
+  availableFrom: '2026-11-01T09:00:00+01:00',     // an offset is required
+  preorderLimit: 50,
+});
+await admin.catalog.products.addOptionGroup(product.id, size.id);
+await admin.catalog.variants.create([
+  {
+    productId: product.id,
+    sku: 'LS-M',
+    translations: [{ languageCode: 'en', name: 'Linen shirt M' }],
+    optionIds: [size.options[0]!.id],
+    price: 4995,
+    priceBasis: 'gross',                          // must be the store's own basis
+    taxClassKey: 'reduced',                       // the engine sets taxCategoryId from it
+  },
+]);
+await admin.catalog.properties.values.set(product.id, [{ propertyId, value: 'Linen' }]);
+```
+
+- **Prices state their basis.** A price without `priceBasis` is refused (`PRICE_BASIS_REQUIRED`), and
+  a basis other than the store's `pricesIncludeTax` is refused (`PRICE_BASIS_MISMATCH`) rather than
+  converted — the rate that would convert it depends on each order's zone.
+  On read, `price` is always net and `priceWithTax` always gross: a read-modify-write on a gross
+  store starts from `priceWithTax`, never from `price`.
+- **Tax class.** `taxClassKey` on a variant write is resolved by the engine, for the store's own
+  business country (`*` when it names none), into the `taxCategoryId` written in the same
+  transaction. `TAX_CLASS_NOT_FOUND`, `TAX_CLASS_UNMAPPED`, and `INVALID_TAX_CATEGORY_FOR_CLASS`
+  (a `taxCategoryId` that contradicts the class) refuse the whole write. Editing a class's mappings
+  later does not re-price existing variants: write the variant again to pick the new mapping up.
+- **Parcel rule.** A variant's `parcelCapacity` (units per parcel, 1 to 10,000; null uses the
+  store's items per parcel, or 1 per parcel when packing is `separate`) and `parcelPacking` (`shared` | `separate` | `none`) feed the
+  shipping calculator's parcel count. `shared` is stored as null and an unset packing reads as
+  `shared`. Out-of-range values are refused before sending (`INVALID_PARCEL_CAPACITY`,
+  `INVALID_PARCEL_PACKING`).
+- **Not atomic across resources.** A product form is several calls here and they are not one
+  transaction; `products.save()` as one intent operation is a later phase. No catalogue write
+  deduplicates on `idempotencyKey`, except `products.bulk` (below).
+- **Feed identifiers.** A product's `brand` and a variant's `gtin` (custom fields the typed inputs
+  here do not carry; a bulk row's `customFields` does) are judged when a write makes them NEW or
+  CHANGED: a brand over 70 characters or a GTIN that is not 8, 12, 13 or 14 digits (after
+  trimming) is refused `FEED_IDENTIFIER_INVALID` (`ValidationError`, 400), creates included, with
+  `details[].field` an RFC 6901 pointer into the call (`/input/customFields/brand`,
+  `/input/0/customFields/gtin`). A value the record already holds passes unchanged, so an older
+  stored value never blocks a write of the record's other fields.
+- **Deletes** the engine declines (`NOT_DELETED`, at HTTP 200) throw a `ConflictError` named
+  `<RESOURCE>_NOT_DELETED` carrying the engine's reason; `force` exists where the engine has it.
+- Collection membership is derived from the collection's `filters` and recomputed in a background
+  job, so a product appears shortly after the write, not during it.
+
+#### Putting a product in collections
+
+```ts
+// Put the product in Summer, and touch nothing else.
+await admin.catalog.products.setCollections(productId, [summerId], { from: [] });
+// Take it out of Sale only.
+await admin.catalog.products.setCollections(productId, [], { from: [saleId] });
+// A screen listing the product's collections: what the merchant left selected, and what it loaded.
+const result = await admin.catalog.products.setCollections(productId, selectedIds, {
+  from: loadedIds,
+});
+// { added: [...], removed: [...], unchanged: [...], notRemoved: [{ collectionId, reason }] }
+```
+
+- **Hand-picked membership only.** The engine adds the product to the hand-picked list
+  (`product-id-filter`) of each collection it should join, and takes it off the lists of each one it
+  should leave. A collection it is in only through other filters (facet values, names) is never
+  rewritten: it comes back in `notRemoved` with `MEMBER_BY_FILTER`, and the product stays in it.
+- **Safe beside other writers.** One transaction; every collection written is row-locked first, so
+  two products saved into one collection at once both stay listed. Never put a product in a
+  collection with `collections.update` and a filter list you read earlier: that write replaces the
+  list another writer may have just changed.
+- **`from` applies only your change.** With `from`, only the difference between it and the list
+  you send is applied; every other collection stays as it is, including one someone else changed
+  since you read. Without it, the list you send is the WHOLE hand-picked membership: the product
+  leaves every other collection that lists it by hand.
+- **All or nothing**, refused before anything is written: `PRODUCT_COLLECTIONS_INPUT_INVALID`
+  (a collection named twice, more than `MAX_PRODUCT_COLLECTION_IDS`), `PRODUCT_COLLECTION_FILTER_INVALID`
+  (a collection's hand-picked list cannot be read; the message names it), `SHARED_COLLECTION_NOT_ALLOWED`,
+  `MANAGED_BY_ORGANIZATION` (a collection of the store's organization), `ENTITY_NOT_FOUND`.
+- A repeat of a call that went through writes nothing and answers `unchanged`, except that a
+  collection the product stays in through other filters answers `notRemoved` again (also, for a
+  collection with such filters, until its membership job has run). Requires a platform
+  release that serves `setProductCollections`.
+
+#### Many products at once
+
+```ts
+const handle = await admin.catalog.products.bulk(
+  { action: 'DISABLE', productIds: selectedIds }, // ENABLE | DISABLE | DELETE | CLONE, 1 to 50 ids
+  { idempotencyKey } // minted when omitted
+);
+const run = await handle.wait(); // or later: admin.catalog.products.bulkRun(handle.runId)
+for (const item of run.items) {
+  if (item.status === 'FAILED') console.log(item.id, item.code, item.message);
+}
+// a CLONE item's `newId` is the copy
+```
+
+- **A job, answered at once.** The call answers a receipt (`runId`) as soon as the run is queued;
+  `wait()` polls it until it ends and resolves with it whatever the ending. `run.items` holds one
+  outcome per product reached, in the order you named them; `status` is the RUN's (`SUCCEEDED`
+  means every product has an outcome, a `FAILED` one included).
+- **Each product on its own.** Every product goes through its single door (`update` with
+  `enabled`, `delete`, `clone`) in a transaction of its own, so a refused product leaves the others
+  done: another store's product is `ENTITY_NOT_FOUND`, a product another store also holds
+  `SHARED_PRODUCT_NOT_ALLOWED`, one the store's organization holds `MANAGED_BY_ORGANIZATION`, an
+  owned field group `FIELD_GROUP_LOCKED` (a delete takes every group; `enabled` is in none), the
+  external-line carrier `EXTERNAL_LINE_CARRIER_PROTECTED`, a delete core declines
+  `PRODUCT_NOT_DELETED`.
+- **One key, one run.** The same key with the same action and ids answers the same run, so a
+  resubmit never clones twice; another selection under it is `IDEMPOTENCY_CONFLICT`.
+- **No dry run**: the doors' refusals are made under the write, so a rehearsal could not promise
+  the real outcome.
+- **At most `MAX_BULK_PRODUCTS` (50) per run**, each named once (`BULK_ACTION_INPUT_INVALID`,
+  refused before sending too); split a larger selection. Needs the single door's permission for
+  the action (`BULK_ACTION_NOT_ALLOWED` otherwise); reading a run needs `ReadCatalog` or
+  `ReadProduct`, and another store's run is `BULK_ACTION_RUN_NOT_FOUND`. Requires a platform release
+  that serves `bulkProductAction`.
+
+#### Syncing a property's filter values
+
+```ts
+// After renaming a content item (or a product) a filterable property links to:
+const result = await admin.catalog.syncContentFacets(propertyId);
+// { propertyId, items: 12, unresolved: ['…'], fieldFacets: 2 }
+```
+
+- **The engine reads the labels.** A filterable `content_item` or `product` property mirrors each
+  item or product its values name as a filter value. The call gives every one of them its current
+  label: the content item's title (read from the store's content, drafts and archived items
+  included) or the product's name in the request's language. Send nothing but the property id.
+- **Field-level facets follow the saved configuration.** For a `content_item` property saved with
+  fields to filter by, the products' field-facet values follow the items' field values. What the
+  property was saved with decides, never an unsaved form.
+- **One transaction**, labels and field facets together. The labels are read first, so a content
+  system that cannot be read refuses the call (`CMS_REQUEST_FAILED`, try again) before anything
+  changes. Repeating the call is safe: an unchanged label is not written again.
+- `unresolved` names the ids the engine could not label (a removed content item, a product this
+  store does not hold): their filter values keep the label they have.
+- **Nothing runs it automatically yet**: call it after renaming a content item or a product.
+- Refusals: `PROPERTY_NOT_FOUND` (404), `PROPERTY_FACET_SYNC_INVALID` (400, not filterable or
+  another type), `MANAGED_BY_ORGANIZATION` (422, the organization's property),
+  `SHARED_FACET_NOT_ALLOWED` / `SHARED_PRODUCT_NOT_ALLOWED` (403), `CMS_REQUEST_FAILED` and
+  `PROPERTY_SYNC_SOURCE_UNAVAILABLE` (422). Requires a platform release that serves
+  `syncPropertyFacets`.
+
+#### An image's descriptions (alt text)
+
+```ts
+const current = await admin.catalog.assets.descriptions.get(assetId);
+// [{ languageCode: 'en', description: 'A red wine bottle' }, { languageCode: 'nl', … }]
+const saved = await admin.catalog.assets.descriptions.set(assetId, [
+  { languageCode: 'en', description: 'A red wine bottle on a wooden table' },
+  { languageCode: 'nl', description: 'Een fles rode wijn op een houten tafel' },
+]);
+// { assetId, descriptions: [...], altText: 'A red wine bottle on a wooden table' }
+```
+
+- **Two homes, one change.** The content system keeps an image's descriptions per store and
+  language (what a storefront shows as the alt text); the engine keeps one alt text per image,
+  `customFields.altText`, set to the store's default-language description (null when it has
+  none). `set` writes both, or neither: the engine writes the alt text and the content system the
+  descriptions in one engine transaction, the content system last.
+- **The whole set.** `set` takes every description of the image in the store, one per language the
+  store offers. A language left out is removed; leaving out the store's default language clears
+  the alt text. The alt text is ONE value wherever the image is used: another store holding the
+  same image reads the new one.
+- **Safe to repeat.** Both writes set the image to the call's input, so repeating a call converges
+  both stores whatever an earlier attempt left. A `CMS_REQUEST_FAILED` with `outcomeUnknown` (the
+  content system did not answer in time) may have saved the descriptions without the alt text:
+  send the same call again. No idempotency key is needed.
+- **Refused, nothing written:** `CMS_PERMISSION_NOT_ALLOWED` (403: the descriptions need
+  UpdateCmsAsset in the store, besides UpdateCatalog or UpdateAsset), `ENTITY_NOT_FOUND` (an image
+  this store does not hold), `MANAGED_BY_ORGANIZATION` (422: an image the store's organization
+  shares; change it in the workspace), `SHARED_ASSET_NOT_ALLOWED` (403: another store also holds it
+  and you cannot change that store), `ASSET_DESCRIPTIONS_INVALID` (400: a language the store does
+  not offer or named twice, a blank text, more than 500 characters; `details[]` points at each
+  entry), `CMS_REQUEST_FAILED` (422).
+- `get` is the content system's read and can answer a language the store no longer offers; `set`
+  refuses one, so leave it out when you send the set back (it is removed with the rest).
+- Requires a platform release that serves `setAssetDescriptions`; against an older engine `set`
+  fails as `GRAPHQL_VALIDATION_FAILED`.
+
+### Pricing — promotions and coupons at the register
+
+```ts
+// The promotions a register can offer now, for this customer (a Page; the list is whole).
+const offers = await admin.pricing.promotions.active({ customerId, locationId });
+offers.items[0]?.summary; // "If order total is greater than 50.00 EUR: Discount order by 10%"
+
+// A coupon on a Draft order (a back-office draft, or createOrRecover's order left as a Draft).
+const order = await admin.pricing.coupons.apply(orderId, 'SUMMER-7KQ2', { idempotencyKey });
+order.lines[0]?.discounts;           // [{ promotionId, description, amount, amountWithTax, … }]
+order.discounts;                     // the order-level ones
+await admin.pricing.coupons.remove(orderId, 'SUMMER-7KQ2');
+await admin.pricing.discounts(orderId); // the same readout, by id (ReadOrder)
+
+// A till cart (a `pos` token at its location): the same rules, before any tender.
+await admin.pos.sale.applyCouponCode({ orderId: cartId, couponCode: 'SUMMER-7KQ2' });
+```
+
+A code is a promotion's own coupon code or a unique code generated for it; a unique code stands
+in for its promotion's code, so `couponCodes` shows the promotion's code. Every refusal leaves
+the order as it was: `COUPON_INVALID` (unknown here, deactivated, or another store's — one answer
+for all), `COUPON_EXPIRED`, `COUPON_NOT_YET_VALID`, `COUPON_USAGE_EXHAUSTED` (with
+`details.limit`), `COUPON_NOT_APPLICABLE` (valid, but the promotion does not apply to the order as
+it stands), `EXTERNAL_LINE_PROMOTION_UNSUPPORTED`, and `ORDER_NOT_DRAFT` for an order past Draft.
+Surcharges are never touched by a coupon. `promotions.active` judges dates, usage and customer
+groups; conditions on the basket are summarised, not judged.
+
+#### Targeting: where, when, for whom
+
+Three conditions target the sale rather than the basket. Build them with `promotionConditions`,
+which encodes the arguments as the engine stores them:
+
+```ts
+import { promotionConditions } from '@sixtyninecommerce/admin';
+
+await admin.pricing.promotions.create({
+  translations: [{ languageCode: 'en', name: 'Happy hour at the shop' }],
+  enabled: true,
+  conditions: [
+    promotionConditions.sellingLocation([shopLocationId]),
+    promotionConditions.timeWindow({ days: ['mon', 'tue', 'wed', 'thu', 'fri'], from: '17:00', until: '19:00' }),
+  ],
+  actions: [{ code: 'order_percentage_discount', arguments: [{ name: 'discount', value: '15' }] }],
+});
+await admin.pricing.promotions.create({
+  translations: [{ languageCode: 'en', name: 'Welcome' }],
+  enabled: true,
+  conditions: [promotionConditions.firstOrder()],
+  actions: [{ code: 'order_fixed_discount', arguments: [{ name: 'discount', value: '500' }] }],
+  perCustomerUsageLimit: 1,
+});
+
+// Read back for a sale at that shop, now, for this customer:
+const offers = await admin.pricing.promotions.active({ locationId: shopLocationId, customerId });
+offers.items[0]?.summary; // "Sold at Shop Centraal and Monday to Friday, from 17:00 to 19:00 (local time): …"
+```
+
+- **`selling_location`** — the order is sold from one of the locations: a till there, an order
+  `orders.createOrRecover` recorded for it (`location`), or a register that sends the location as
+  `x-location` on the Admin API (the client's `tenant.location`). A web order has no location and
+  never matches. A placed order keeps a location promotion it was placed with.
+- **`time_window`** — days and a local `from`–`until` (until excluded), on the location's profile
+  clock, else the store's. An `until` not after `from` runs past midnight and belongs to the day it
+  opened; `00:00`–`00:00` is all day. The wall clock decides: a window inside the autumn repeated
+  hour is open twice, one inside the spring skipped hour never opens. A cart is judged when it is
+  priced, a placed order at its placement — and one placed with the window keeps it.
+- **`first_order`** — the customer has no earlier placed (not cancelled) order in this store. No
+  customer, or the till's walk-in, never matches. Two carts of a new customer priced before either
+  is placed both match: add `perCustomerUsageLimit: 1` for a hard cap.
+
+`promotions.active` judges all three for the location (`locationId`, else `x-location`; with
+neither a location promotion is left out), now, and `customerId`. `create` / `update` add the
+dashboard's stacking guard when the conditions lack it, so — as in the dashboard — an empty
+`conditions` list is never refused: it creates a promotion that applies to every order (with no
+coupon code, automatically). Refusals: `PROMOTION_CONDITION_INVALID` (an argument the engine
+cannot read; `details` names it), `LOCATION_NOT_IN_CHANNEL`, `LOCATION_NOT_ALLOWED`; and on
+`update` only, `MISSING_CONDITIONS_ERROR` when the input names no `conditions`, the stored
+promotion has none (an imported coupon, a seed) and its coupon code would be gone
+(`couponCode: ''`, or none stored) — send `conditions` (even `[]`) to keep it without a code.
+
+#### Sets: bundles, the nth set, mix and match
+
+Three promotions price a set of lines together. Each is a condition carrying the definition and
+an action of the same code with no arguments; put both on the promotion (the engine refuses one
+without the other):
+
+```ts
+import { promotionActions, promotionConditions } from '@sixtyninecommerce/admin';
+
+// A frame and two lenses for 199.00 (store default currency, store tax basis).
+await admin.pricing.promotions.create({
+  translations: [{ languageCode: 'en', name: 'Complete glasses' }],
+  enabled: true,
+  conditions: [
+    promotionConditions.bundleFixedPrice({
+      components: [
+        { collectionIds: [framesId], quantity: 1 },
+        { collectionIds: [lensesId], quantity: 2 },
+      ],
+      price: 19_900,
+    }),
+  ],
+  actions: [promotionActions.bundleFixedPrice()],
+});
+// Second pair at 50%; 3 socks for 10.00.
+promotionConditions.nthSetPercentage({ components: [{ collectionIds: [framesId], quantity: 1 }], nth: 2, discount: 50 });
+promotionConditions.mixAndMatch({ collectionIds: [socksId], quantity: 3, price: 1_000 });
+
+const { packages } = await admin.pricing.discounts(orderId);
+// [{ promotionId, label: 'Complete glasses', priceWithTax: 19900, lineIds: [...], quantity: 1 }]
+```
+
+- A unit fills a component when it carries ALL its facet values and sits in ANY of its
+  collections. When more units qualify than a set needs, the most valuable ones form the sets
+  (ties by line), so "3 for 10.00" applies to the best three, as a cashier would ring it.
+- The set's discount is spread over its lines in proportion to their value, in exact minor units,
+  as an ordinary promotion discount on the lines: mixed VAT rates each drop by their share, and a
+  returned component refunds its discounted price. A set worth the set price or less stays at
+  list. Lines a caller or staff priced (external, imported, quoted, till or manual prices) never
+  join a set, and a line belongs to one set promotion at a time (the one tested first).
+- Swapping a component for another qualifying one keeps the set; removing one dissolves it.
+- `nth_set_percentage` discounts the cheapest `floor(sets / nth)` sets. "The last one added" is
+  not offered: a quantity change adds units with no time of their own.
+- The set and group `price` is required and above 0: the builders throw `ValidationError`
+  (`PROMOTION_CONDITION_INVALID`) before anything is sent, and the engine refuses it too. To
+  give sets away use `nthSetPercentage` with `discount: 100`.
+- Refusals on `create` / `update`: `PROMOTION_CONDITION_INVALID` (`details.argument` names the
+  argument, `conditions` for a second set condition or a set action without its condition,
+  `actions` for a missing action or a second copy of one; an `update` is judged on the pair it
+  leaves),
+  `FACET_VALUE_NOT_FOUND`, `COLLECTION_NOT_FOUND` (another store's answers the same).
+
 ### Order surcharges
 
 A surcharge is an adjustment on a placed order that is not a line: a delivery charge, a negotiated
@@ -557,6 +1466,602 @@ surcharge with no tax line and lowers the order total — re-send whichever of t
 carry. A `taxClass` is then re-resolved on every write, so the rate that applies now is the one
 stored. All three need `UpdateOrder` and are refused once the order's invoice has been approved.
 
+**On an order the customer has paid**, lowering or removing a charge (or adding a negative one)
+can leave them overpaid. The change is then refused `ORDER_EDIT_OVERPAYMENT_CHOICE_REQUIRED`
+(`BusinessRuleError`), nothing written, until the merchant chooses how to settle it:
+
+```ts
+const preview = await admin.orders.surcharges.preview(orderId, { surchargeId, remove: true });
+// { currencyCode, totalBefore, totalAfter,
+//   overpayment: { amount: 545, currencyCode: 'EUR',
+//                  refund: { available: true, … }, accountCredit: { available: false, code, message } } }
+
+await admin.orders.surcharges.remove(orderId, surchargeId, { overpayment: 'REFUND' });
+await admin.orders.surcharges.update(orderId, surchargeId, input, { overpayment: 'ACCOUNT_CREDIT' });
+```
+
+`REFUND` returns it to the customer's payment, after every write; it is refused
+`REFUND_EXCEEDS_PAYMENT` when no single payment can carry it (refund in parts, one payment at a
+time, then save the change), and `ORDER_OVERPAYMENT_REFUND_ORDER_STATE` on an order in a state core
+does not refund (its message names the way on: settle the payment, or move the order to
+`PaymentSettled`), and `REFUND_METHOD_UNAVAILABLE` when that payment's
+method can no longer be reached. `ACCOUNT_CREDIT` puts it on the customer's account as unapplied cash
+(`payments.accountCredit`); it is open only where `preview` says so, and otherwise refused with the
+account's own code. The amount is what the change ADDS to the overpayment, held to what the
+payments can still hand back: an order still owing gets back only what goes beyond what it owes.
+A refund of unknown outcome on the order refuses such a change
+(`ORDER_OVERPAYMENT_REFUND_UNRECONCILED`) until it is reconciled. A choice sent when nothing is
+owed back is ignored, and the `overpayment` variable is sent (and declared) only when given, so an
+older engine still accepts every call that does not use it.
+
+### Order parcel charge
+
+```ts
+const charge = await admin.orders.parcelCharge(orderId);
+// { orderId, chargedParcelCount: 2, lineIds, fulfillments: [{ id, state, parcelCount, orderIds, orderLineIds }] }
+```
+
+The parcel count a placed order's shipping was charged for (`null` when it was not priced per
+parcel), frozen when it left the cart, and the parcels each fulfilment's pack step recorded. A
+fulfilment can ship several orders of one customer: `orderIds` and `orderLineIds` say which, so do
+not compare its parcels with one order's charge unless it ships that order alone. `null` for an
+order this channel does not have. Needs `ReadOrder` and an engine that serves
+`Order.customFields.chargedParcelCount`; on an older one only this call fails.
+
+### Order line price preview
+
+```ts
+const [stored, added] = await admin.orders.previewLinePrices(
+  orderId,
+  [
+    {
+      lineId,                                      // a line of the order
+      productVariantId: bottleId,
+      quantity: 12,
+      override: { amount: 12100, basis: 'GROSS' }, // stage a manual unit price (see below on basis)
+      oneTimeDiscount: null,                       // clear the stored one-time discount
+    },
+    { productVariantId: glassId, quantity: 6 },    // not on the order yet
+  ],
+  { orderDiscount: { discountType: 'PERCENTAGE', discountValue: 500 } }, // stage 5% off the order
+);
+// stored: { lineId, productVariantId, purchasable: true, notPurchasableCode: null,
+//   chargedUnitPrice: 9500, chargedUnitPriceWithTax: 11495, basis: 'NET', basisKnown: true,
+//   retailBase: 12000, catalogueChanged: false, overrideInert: false, taxProvisional: false,
+//   stacking: [{ source: 'RETAIL', amount: 12000 }, { source: 'OVERRIDE', amount: 10000 },
+//              { source: 'ONE_TIME', amount: 9500 }] }
+
+if (added.purchasable) {
+  show({
+    net: added.chargedUnitPrice,                   // numbers only after this check
+    gross: added.chargedUnitPriceWithTax,
+    // With a tax provider app, the figure that is not in `added.basis` may still move.
+    provisional: added.taxProvisional ? (added.basis === 'NET' ? 'gross' : 'net') : null,
+  });
+} else {
+  explain(added.notPurchasableCode);               // 'VARIANT_NOT_FOR_SALE_IN_CURRENCY', no money
+}
+```
+
+What lines of an order would cost before anything is saved: the pricing engine's own answer for a
+staged manual unit price, one-time discount and quantity, on stored lines and on lines that are not
+on the order yet. One result per line, in the order of `lines`. It is a pure read: nothing is saved,
+no event is published, and no payment or tax provider is contacted. Needs `ReadOrder` and an engine
+that serves `previewOrderLinePrices`; on an older one only this call fails.
+
+The answer is what a re-price of the line gives now: today's catalogue price, price lists, tiers and
+tax. A stored line that a save does not re-price keeps its stored price, so compare
+`chargedUnitPrice` and `chargedUnitPriceWithTax` with the line's own `unitPrice` and
+`unitPriceWithTax` to see whether a re-price would move it (a changed tax driver can move one of
+the two and not the other). Two kinds of stored line keep the tax rate they carry, and their tax is not
+re-evaluated: every line of the order on a store with an active tax provider app (the app is not
+asked), and a line whose variant was moved to another tax category since. A tax driver that changed
+since (a VAT number validated, tax removed) does not show in such a line's figures, so the
+comparison does not see it.
+`catalogueChanged` reports a moved catalogue retail only: a re-price starts from another catalogue
+retail than `retailBase`. For a line a price list priced, the line recorded that retail gross and no
+tax rate of its day, so the two are compared gross: besides a moved catalogue price, a change of the
+rate the catalogue taxes the variant at for this order (the rate of the order's tax zone, the zone
+the order falls in, the variant's tax category) can set it too, while the net catalogue price did
+not move. A changed price list or quantity tier, and a tax driver that changes only the line's own
+tax (a reverse charge, tax removed), can move the previewed figures and leave it `false`, and it is
+always `false` for a list-priced line of an order outside the store's default currency. 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.
+
+Check `purchasable` before reading a price: the result type is a union on it. A variant the store
+does not sell in the order's currency is answered `purchasable: false` with `notPurchasableCode` set
+to `VARIANT_NOT_FOR_SALE_IN_CURRENCY`, every money field `null` (never 0, never a rate-derived
+figure) and an empty `stacking`, unless a price is stated for the line, for example a manual unit
+price. The own lines of an order placed at a recorded exchange rate are not judged; a line that is
+not on the order yet always is.
+
+Every figure is minor units in the order's currency, before promotions. `basis` is the basis the
+engine prices the line in, and the basis a manual unit price must be sent in to the Admin API's
+`applyOrderLinePriceOverrides`: the `OVERRIDE` step of `stacking` is that figure. `stacking` starts
+with a `RETAIL` step at today's catalogue price when the line has one, and its last step is the
+charged unit price in `basis`. `retailBase` is the retail the line was priced at, the base a
+percentage is measured against: a stored line's recorded retail, or today's catalogue price for a
+line that is not on the order yet. It is `null` when a stored line recorded none, and when the line
+has no catalogue price (an externally priced line, or a variant not for sale in the order's currency
+that a stated price makes purchasable). Each line is taxed as a re-price would tax it now, apart
+from the two kinds of stored line named above.
+
+A store with an active tax provider app gets a platform-taxed preview for new lines. There a line of
+the order keeps the rate it carries, but a line that is not on the order yet is taxed at the
+platform's rate: a preview never asks the app, which answers when the line is added.
+`taxProvisional` marks those lines. Their figure in `basis` is firm. The other one (the gross of a
+`NET` line, the net of a `GROSS` line) is derived at the platform's rate and may then differ, so
+show it as provisional. `taxProvisional` is `false` everywhere else, and on a line that is not
+purchasable.
+
+A manual price stated in the line's own `basis` is always accepted. One stated in the other basis is
+converted only at a tax rate the preview evaluated: the rate the platform taxes the line at on the
+order as it is now. Where the preview evaluates no rate it is refused with `INVALID_PREVIEW_INPUT`,
+in a message that names the basis to state it in: on every line, stored or new, of a store with an
+active tax provider app, and on a line of the order whose variant was moved to another tax category
+since. Converted at a rate the line merely carries, the price a head then saves would be taxed at
+whatever rate the order applies on the save. To learn a line's basis first, preview it without an
+`override` and read `basis`.
+
+`override` and `oneTimeDiscount` on a line, and `orderDiscount` in the options, each have three
+states, and the SDK sends them as given: leave the key out to keep what the order has, pass `null`
+to clear it, pass a value to stage it. An `override` is stated in the basis you name, and the engine
+converts it into the line's only where the preview evaluated the line's tax rate (above): the
+example's gross price on a `NET` line is converted on a store the platform taxes, and refused on a
+store with an active tax provider app. A discount value is basis points for `PERCENTAGE` (1 to
+10000), and minor units in the channel's tax basis for `FIXED_AMOUNT` (off each unit) and `FIXED_PRICE`. A
+one-time discount applies to the product variant, so to every line of it. `orderDiscount` is
+`PERCENTAGE` or `FIXED_AMOUNT`.
+
+At least 1 and at most 100 lines per call. Each call prices from the saved order plus what that call
+stages: stage a whole-order discount, and every quantity a collection or facet tier depends on, in
+the same call as the lines they affect. A removed line cannot be staged (a quantity is 1 or more):
+the collection and facet tiers of the other lines still count it at its stored quantity.
+
+Refusals: `PREVIEW_ORDER_NOT_FOUND`, `PREVIEW_ORDER_LINE_NOT_FOUND` and `PREVIEW_VARIANT_NOT_FOUND`
+(`NotFoundError`, 404; an id of another store answers like a missing one), `INVALID_PREVIEW_INPUT`
+(`ValidationError`, 400; it covers `override: null` on an externally priced line, which has no
+catalogue price to fall back to, and an `override` in the other basis on a line whose tax rate the
+preview does not evaluate)
+and, from the default channel, `PREVIEW_CHANNEL_NOT_ALLOWED` (`PermissionDeniedError`, 403). An id
+that is not a uuid is refused before that with core's `ENTITY_NOT_FOUND`, also a `NotFoundError`, so
+branch on the class for not-found.
+
+### Manual prices and one-time discounts on an order
+
+The two doors that save what `previewLinePrices` stages. Both re-price the lines they change and
+re-total the order in one transaction, with no refund, so both refuse an order whose payment was
+collected. Change that one through an order modification: plan it with `orders.planEdit` (which
+saves and refunds nothing), then carry it out through the Admin API's `modifyOrder` directly, which
+issues the refund; this SDK has no method for that step until `orders.commitEdit` ships. Both need
+`UpdateOrder` and take `idempotencyKey`.
+
+```ts
+const reasons = await admin.orders.manualDiscounts.reasons.list(); // the store's codes
+
+// A manual unit price, in the LINE's basis (`basis` from previewLinePrices, or the line's
+// `listPriceIncludesTax` from orders.get). Lines not named keep their price.
+const order = await admin.orders.setLinePrices(
+  orderId,
+  {
+    lines: [
+      { orderLineId, unitPriceOverride: 9500, reasonCode: 'price-match' }, // set, with a reason
+      { orderLineId: otherLineId, unitPriceOverride: null },               // clear: back to the catalogue
+      { orderLineId: thirdLineId, priceOverrideReason: 'Agreed by phone' }, // the note alone
+    ],
+  },
+  { idempotencyKey },
+);
+order.lines[0]?.unitPrice; // the price before promotions, where a manual price shows
+
+// One-time pricing: the COMPLETE state the order should end with, not a change.
+await admin.orders.setOneTimeDiscounts(
+  orderId,
+  {
+    orderDiscount: { discountType: 'PERCENTAGE', discountValue: 500 },  // 5% off every other line
+    lines: [{ orderLineId, discountType: 'FIXED_PRICE', discountValue: 8000, reasonCode: 'loyalty' }],
+    reason: 'Opening offer',                                            // a note, kept once per order
+    reasonCode: 'loyalty',                                              // for every line it lowers
+  },
+  { idempotencyKey: otherKey },
+);
+
+await admin.orders.manualDiscounts.list(orderId); // what each call moved, with its reason
+```
+
+`setLinePrices`: `unitPriceOverride` is minor units, 0 or more, in the line's tax basis (gross when
+its `listPriceIncludesTax`, net otherwise; a line priced in a customer-country tax zone is net on a
+store that prices gross), and the engine takes no basis with it. Left out keeps the price (a
+note-only change), `null` clears it, a number sets it; `priceOverrideReason` left out keeps the
+note, `null` or `''` clears it. A manual price is a layer: the customer's price list and the order's
+one-time discounts apply on top, and a contract's fixed price wins over it. Setting or clearing it
+takes the line out of the exact-price state an imported, quoted or till-priced line arrives in.
+
+`setOneTimeDiscounts` replaces the order's one-time pricing: a live line missing from `lines` loses
+its line discount, and `orderDiscount: null` removes the whole-order one, so send what should stay.
+`discountValue` is basis points for `PERCENTAGE` (1 to 10000), and minor units in the STORE's tax
+basis and the order's currency for `FIXED_AMOUNT` (off each unit, 1 or more) and `FIXED_PRICE` (the
+unit price, 0 or more; never on the whole order). A one-time discount applies to the product
+variant, so a variant on two live lines is refused. `reason` left out or `null` keeps the note,
+`''` clears it.
+
+Both answer the order with the fields of `pricing.discounts(orderId)`. A manual price and a
+one-time discount move a line's `unitPrice` / `unitPriceWithTax` (before promotions); they are not
+promotions, so they never appear in `discounts`.
+
+A line whose price before promotions the call lowers received a manual discount. When the store
+requires a reason (`manualDiscounts.policy`) each such line needs one, from its entry or the call,
+or nothing is written; a raise or a note-only change needs none. Refusals:
+
+- `DISCOUNT_REASON_REQUIRED` (`BusinessRuleError`, 422): a lowered line has no reason. Ask for one.
+- `DISCOUNT_REASON_UNKNOWN` (`BusinessRuleError`, 422): a code sent is not one of the store's
+  active reasons. Checked before anything is written, also when no price falls.
+- `IDEMPOTENCY_CONFLICT` (`ConflictError`, 409): the key was used for another request (the other
+  door included). `IDEMPOTENCY_IN_PROGRESS` (`ConflictError`, 409): the first call is still
+  running.
+- Every other refusal is the engine's `USER_INPUT_ERROR` (`ValidationError`, 400) with a sentence
+  that says what to do: the payment was collected (offline authorizations such as bank transfer or
+  net terms do not count), the order is invoiced, completed or cancelled, the call came from the
+  default channel, the order is not this store's, a line is not on it, cancelled or named twice,
+  and each door's own input rules (a negative price, a line asking for nothing, clearing the price
+  of an externally priced line; a value out of range, a `FIXED_PRICE` whole-order discount, an
+  exactly priced or free line, a discount the pricing rules skipped). These carry no code of their
+  own: branch on the class and show the message.
+
+Under an `idempotencyKey` the first answer is kept for 24 hours and given again to the same
+request without running it: a success (the order, re-read as it is now) and every refusal with a
+4xx status, the `USER_INPUT_ERROR` ones above included. Only a 5xx, 408, 425 or 429 frees the key.
+So after fixing the cause of a refusal (reopening the order, picking a reason), send the corrected
+request under a NEW key; under the old one it is `IDEMPOTENCY_CONFLICT`.
+
+Both need an engine with the discount-reason layer (`discountReasons`); on an older one only these
+two calls fail.
+
+### Reading an order
+
+```ts
+const order = await admin.orders.get(orderId);
+// order.code, order.state, order.totalWithTax, order.lines[0].outstandingAllocations, … | null
+
+const withTerms = await admin.orders.get(orderId, { include: ['paymentTerms', 'priceList'] });
+// withTerms.paymentTerms → { status: 'ASSIGNED', summary: 'Payment due within 30 days', … } | null
+```
+
+One order of the store, or `null` when the store holds no order with that id (another store's order
+answers `null` too). Needs `ReadOrder`.
+
+Money is an integer in minor units of the order's `currencyCode`, with three exceptions that are
+not converted to it: a line's `productVariant.price` and `priceWithTax` are today's catalogue price
+in the currency of the request (the store's default, unless the call names another with
+`tenant.currency`), and a line's `customFields.cost` is in the store's default currency. On an order
+in another currency, do not subtract them from the line's own prices.
+
+`active` is true only for a cart still open to its shopper. A draft, a placed order and a cancelled
+one are not active, and it says nothing about payment.
+
+Without `include` the answer is the order itself, as the engine serves it without any plugin:
+totals, the customer and their address book, the lines (prices, the variant's stock, what each line
+reserves now, how it was priced), surcharges, discounts, payments and refunds, fulfillments, both
+address snapshots, the 50 most recent history entries, the tax summary and the engine's own custom
+fields.
+
+Each name in `include` adds the block one plugin contributes, on the answer and on its type. A read
+that did not include a block has no such field, at runtime or in TypeScript:
+
+| `include` | Adds |
+|---|---|
+| `paymentTerms` | `paymentTerms`, and the order's own override (`customFields.paymentTermsDays`, `paymentConditionCode`) |
+| `deliveryTerms` | `deliveryTerms` |
+| `priceList` | `priceList`: the order's own price list, which is its one-time pricing |
+| `lineAllocations` | `lines[].allocations`: the raw allocation rows. They never decrement; `outstandingAllocations` is what a line reserves now, and needs no include |
+| `fulfillmentDetails` | `fulfillments[].handlerCode`, `handlerName`, `handlerDetails` and `packingSlips` |
+| `vatValidation` | `customer.customFields.vatNumber` and `vatValidationStatus` |
+| `afas` | the AFAS references on the order, its customer and the customer's addresses |
+| `parasut` | the Parasut references on the order and its customer |
+| `myparcel` | `fulfillments[].customFields.myparcel*`: the MyParcel shipment and label state |
+
+`ORDER_INCLUDES` lists them all. A name this version does not know is refused with a
+`ValidationError` (`INVALID_ORDER_INCLUDE`) before anything is asked.
+
+The type follows the options as they are TYPED (`OrderGetAnswer`), and promises only the blocks they
+are sure to hold. A literal list of block names, or `ORDER_INCLUDES`, puts each named block on the
+type. Nothing else promises a block, though the answer still carries it: a list typed
+`OrderInclude[]`, an element that may be one of several blocks (`[block]` for a
+`block: OrderInclude`), and an `include` or options that may be `undefined`. A list that is one of
+several (`wants ? ['paymentTerms'] : []`) answers one of the matching orders; tell them apart with
+`'paymentTerms' in order`.
+
+An app installation below `customerData: full` reads the order with the customer data its level
+withholds blanked: `null`, or an empty value where a field is never null (`""` for a string, `{}`
+for a history entry's `data`). That can be any part of the answer, in the core read and in every
+block: the customer, the addresses, what the buyer typed, and text a carrier, an ERP or a plugin
+composed from the customer's record (a label link, a handler's detail rows, an error, the delivery
+terms in a sentence). The answer then carries `redacted: true`: read every empty value on such an
+order as "not granted", never as "none on record".
+
+Why the order is the way it is (its lock, what may be done to it) is `orders.status`, below, not a
+field of the order.
+
+### Order edit plan
+
+```ts
+const plan = await admin.orders.planEdit(orderId, {
+  adjustLines: [{ orderLineId: bottles, quantity: 6 }],        // was 12
+  addItems: [{ productVariantId: glassId, quantity: 6 }],
+  addSurcharges: [{ description: 'Pallet', price: 2500, priceIncludesTax: true, taxRate: 21 }],
+  shippingAddress: { address: { streetLine1: 'Herengracht 9' }, applyToCustomer: true },
+  note: 'Agreed by phone',
+});
+
+if (plan.blockers.length > 0) {
+  explain(plan.blockers);              // [{ code: 'ORDER_EDIT_FULFILLED_FLOOR', message, details }]
+} else {
+  show({
+    steps: plan.steps,                 // [{ kind: 'MODIFY_ORDER', input, moneyEffect: -4840 }, …]
+    refund: plan.refund,               // { paymentId, amount: 4840 } on a paid order, else null
+    total: plan.preview?.totalWithTax, // the engine's own total after the edit
+    was: plan.preview?.totalWithTaxBefore,
+  });
+  keep(plan.planHash);                 // names what the merchant saw
+}
+```
+
+`planEdit` answers how an edit of a placed order would be carried out and what the order would cost
+after it. You 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, so call it after the merchant
+stops typing rather than on every keystroke. Needs `UpdateOrder`.
+
+Read `blockers` first. They are an answer, not an error, so that a head can show every reason
+beside the steps:
+
+| Code | Meaning |
+|---|---|
+| `ORDER_EDIT_NOT_ALLOWED` | The order's state, invoice lock or lifecycle does not allow an edit (`details.reasonCode`, `details.state`). |
+| `ORDER_EDIT_NOTHING_TO_CHANGE` | The diff changes nothing the order does not already have. A note alone is not a change. |
+| `ORDER_EDIT_FULFILLED_FLOOR` | A line would go below what its fulfillments hold (`details.lines`). |
+| `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.amount`, `largestHeadroom`, `refundable`). An edit never splits a refund over payments. |
+| `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.amount`, and each closed option's `code`; `overpayment` says why in words). |
+| `ORDER_EDIT_OVERPAYMENT_CHOICE_REQUIRED` | Answered only by an engine before the overpayment choice (below): a surcharge lowered or removed on a paid order. A current engine answers `overpayment` instead. |
+| `ORDER_EDIT_PERMISSION_REQUIRED` | The caller may edit the order and lacks `details.permission` for another write the edit includes (the customer's saved addresses). |
+| `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`). 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 that payment in `ArrangingAdditionalPayment`, and either it cannot be moved there from `details.fromState`, or the payment could not be recorded once it waits: part of it is an existing surcharge changed or removed (`details.outsideModifications`) beside the order's modification, so `details.outstanding` ≠ `details.unsettledModifications`. 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. |
+
+A refused step carries the refusing operation's own code when it has one (for example
+`VARIANT_NOT_FOR_SALE_IN_CURRENCY`, or a core code such as `INSUFFICIENT_STOCK_ERROR`), so treat the
+code as an open set and fall back to `message`. `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). `notices` are things the merchant should know that do not stop the edit:
+`ORDER_EDIT_TAX_UNCHANGED`, `ORDER_EDIT_CUSTOMER_ADDRESS_NOT_SAVED`, and, for an edit that raises
+what the customer of a paid order owes, `ORDER_EDIT_PAYMENT_OWED` (a credit or manual payment: the
+order stays paid and `details.amount` is owed, collected by hand or billed) or
+`ORDER_EDIT_ADDITIONAL_PAYMENT_REQUIRED` (a payment collected online, a card or a POS terminal, or a
+method the store no longer has: the order waits in `ArrangingAdditionalPayment`, and cannot ship,
+until `details.amount` is paid).
+
+`steps` are in the order they run, each with its `moneyEffect` on the order's total with tax
+(`null` for a step the run did not reach). A step's `input` is for showing the step; its shape
+follows `kind` and is not a contract to build on. `refund` is what an edit of a paid order returns
+to the customer automatically, on the one payment that can carry the whole amount: what the edit as
+a whole takes off the total (a cut offset by a surcharge raised in the same edit returns only the
+difference), less what a lowered surcharge accounts for, which is `overpayment.amount` (below).
+Neither is ever more than the edit as a whole adds to what the customer has paid beyond what the
+order bills: an order still owing (its total was raised after it was paid) has a cut pay that down
+first, one already overpaid before the edit gets back only what the edit adds, and money moved to
+the customer's account no longer counts as paid. `returnState` is the state the edit leaves the
+order in: the one it returns to after a `MODIFY_ORDER` step, or `ArrangingAdditionalPayment` when
+it waits for a payment.
+
+`overpayment` is set when the edit lowers or removes a surcharge on a paid order. The merchant
+chooses, before saving, how the difference is settled: refunded to the customer's payment, or
+credited to their account as unapplied cash (`payments.accountCredit`). The edit's other cuts
+(item prices and quantities) refund automatically in `refund`; only the surcharge's share asks.
+
+```ts
+// plan.overpayment →
+// { amount: 500, currencyCode: 'EUR', surchargeIds: ['…'],
+//   refund: { available: true, code: null, message: null },
+//   accountCredit: { available: false, code: 'AR_ACCOUNT_IN_ERP', message: '…' },
+//   refundWhenChosen: { paymentId, amount: 1710 } }   // this share and plan.refund, one refund
+```
+
+Show the amount and both options; a closed one keeps its `message`. `REFUND` is closed when no one
+payment can return this share together with `refund` (`REFUND_EXCEEDS_PAYMENT`), when that payment's
+method can no longer be reached (`REFUND_METHOD_UNAVAILABLE`), or while a refund of unknown outcome
+is unreconciled; the order's state never closes it. `ACCOUNT_CREDIT` is closed by the account's own
+answer: a store without the AR ledger, a customer without a credit account, a balance kept in the
+ERP (`AR_ACCOUNT_IN_ERP`: refund only), an order on a live AR invoice, or settled money that cannot
+carry it beside `refund`. When neither is open the plan has the blocker
+`ORDER_EDIT_OVERPAYMENT_NOT_SETTLEABLE`. The plan's hash names the amount, which option is open and
+`refundWhenChosen`, so a plan whose options moved is a stale plan to `commitEdit`.
+
+The diff is sent as given. `orderDiscount` has three states: leave the key out to keep the stored
+whole-order discount, pass `null` to remove it, pass a value to set it. An entry of `lineDiscounts`
+with no `discount` removes that line's one-time discount, so leave a line out of the list to keep
+what it has. `couponCodes` is the complete list the order should end with: an empty list removes
+them all, and only a left-out key leaves them alone. An address is a patch: a field left out keeps
+what the order has. A manual unit price is in the line's own tax basis, which
+`orders.previewLinePrices` answers. Every list holds at most 500 entries.
+
+`planHash` names this plan of this edit of the order as it stands, and `orderVersion` 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). Keep `planHash` with what you show: `commitEdit` carries the
+edit out and is handed it, so what is saved is what the merchant saw.
+
+A store can require a reason for a manual discount. `discountReasonCode` on the diff is the edit's
+reason (one of the store's `discountReasons`, by code): it covers every line whose price a manual
+unit price or the one-time pricing lowers and that names no reason of its own, and a discount in
+`lineDiscounts` or `orderDiscount` can name its own `reasonCode`. Without one, such an edit answers
+the blocker `DISCOUNT_REASON_REQUIRED`; a code the store does not have answers
+`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.
+
+While it runs the plan holds the order, so another change of the same order waits for it. A plan
+that cannot get the order within a few seconds is refused with `ORDER_BUSY` (`ConflictError`, 409):
+nothing was read or changed, so ask again. The SDK does not repeat the call itself.
+
+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), `INVALID_ORDER_EDIT_DIFF` (`ValidationError`, 400, with a message that names the
+field) and, from the default channel, `ORDER_EDIT_CHANNEL_NOT_ALLOWED` (`PermissionDeniedError`,
+403). An id that is not a uuid is refused before that with core's `ENTITY_NOT_FOUND`, also a
+`NotFoundError`, so branch on the class for not-found.
+
+### Committing an order edit
+
+```ts
+const plan = await admin.orders.planEdit(orderId, diff);
+// … show plan.preview and plan.blockers; the merchant saves …
+const saved = await admin.orders.commitEdit(orderId, diff, {
+  expectedPlanHash: plan.planHash,
+  idempotencyKey: attemptKey, // one per attempt to save; re-sent on a retry of that attempt
+  // Only when plan.overpayment is set: the merchant's answer.
+  overpaymentChoice: 'REFUND', // or 'ACCOUNT_CREDIT'
+});
+// saved.order       → { id, code, state, currencyCode, totalWithTax }
+// saved.plan        → the plan that was carried out (its planHash is yours)
+// saved.refund      → { id, state, total, paymentId } | null   (the ONE refund)
+// saved.overpayment → { choice, amount, currencyCode, unappliedCashIds } | null
+```
+
+`commitEdit` carries out the plan of the SAME `diff`, once. The engine runs the plan again inside
+one transaction and keeps that run only when its `planHash` is `expectedPlanHash` and it has no
+blockers: otherwise nothing of the edit is saved. The steps run in the plan's order; the plan's
+refund, if it has one, is made LAST, after every other step, through the platform's refund guard,
+so a payment provider is never asked before everything else has succeeded. Needs `UpdateOrder`.
+
+`idempotencyKey` is required on the wire: one key per attempt to save, re-sent unchanged on a retry
+of that attempt (a timeout, a dropped connection), which then answers what the first call answered
+and does nothing twice. Pass your own: left out, the SDK makes one up and returns it as
+`idempotencyKey` on the result, but on a thrown error only as an untyped property of the error.
+
+| Refusal | Meaning |
+|---|---|
+| `ORDER_EDIT_PLAN_CONFLICT` (`ConflictError`, 409) | The order changed since the plan. Plan again, show the new totals, save under a NEW key. |
+| `ORDER_EDIT_BLOCKED` (`BusinessRuleError`, 422) | The plan has blockers; `error.details` lists them (`code` = the blocker's code). |
+| `ORDER_BUSY` (`ConflictError`, 409) | Another change of the order was being applied. Retry under the same key. |
+| `ORDER_EDIT_OVERPAYMENT_CHOICE_REQUIRED` (`BusinessRuleError`, 422) | The plan has an `overpayment` and no `overpaymentChoice` was given. Ask the merchant, then save under a NEW key (the choice is part of the request). |
+| A closed option's code (`REFUND_EXCEEDS_PAYMENT`, `REFUND_METHOD_UNAVAILABLE`, `AR_ACCOUNT_IN_ERP`, …) | The option chosen is closed, as the plan's `overpayment` names it. |
+| `IDEMPOTENCY_CONFLICT` (409) | The key was used for another request. |
+| `planEdit`'s refusals, and `REFUND_*` | The call is refused as `planEdit` refuses it; the refund guard refused the refund before money moved. |
+
+`IDEMPOTENCY_OUTCOME_UNKNOWN` (`error.outcomeUnknown`): the refund reached the payment provider and
+its answer never came. The edit is NOT saved, the attempt is recorded and reserved on the order, and
+the key answers the same until the provider's answer is recorded (`admin.payments.reconcileRefund`),
+which frees it. Until then an edit that gives money back is blocked
+(`ORDER_OVERPAYMENT_REFUND_UNRECONCILED`). Then plan and save again: a refund recorded as made is not
+made twice.
+
+An edit that raises what the customer of a paid order owes leaves the order in its paid state when
+the order is paid on credit or by hand, and in `ArrangingAdditionalPayment` (it cannot ship until
+the difference is paid) when it is paid online; the plan says which in `returnState` and its
+notices.
+
+With `overpaymentChoice`, the plan's `overpayment` is settled in the same transaction: `REFUND`
+makes `overpayment.refundWhenChosen`, ONE refund of the surcharge's share and the plan's `refund`
+together, last; `ACCOUNT_CREDIT` credits the share to the customer's account first (receipts in
+`saved.overpayment.unappliedCashIds`), then makes the plan's `refund`. A choice sent with a plan
+that has no `overpayment` is ignored. Needs an engine that serves `commitOrderEdit`'s
+`overpaymentChoice` and `OrderEditPlan.overpayment`: deploy the engine before this SDK version.
+
+### Order status
+
+```ts
+const status = await admin.orders.status(orderId);
+// status.lock      → { locked: true, reason: 'INVOICE', lockingInvoice: { id, number, voided } }
+// status.editBlock → { code: 'INVOICE_LOCKED', message } | null
+// status.actions   → [{ action: 'RELEASE_ALLOCATION', eligible: false, allowed: false, reasonCode: 'INVOICE_LOCKED' }, …]
+```
+
+Why an order is the way it is, in one read, so a head does not re-derive it from the order's
+fields. Needs `ReadOrder`. It answers:
+
+- the engine `state` and the four projected `lifecycle` dimensions. `lifecycle.status` is `draft`,
+  `open`, `completed` or `cancelled`. Each dimension is null on an order that predates them, and
+  for a moment on an order just created or changed;
+- the `lock` and the invoice behind it (`IMPORTED` when the source platform had already invoiced
+  it, `UNKNOWN` when the cause is not established);
+- the `editBlock`, with the message every content edit is refused with;
+- whether the Edit Order flow opens (`modifiable`);
+- `deletable`: a deletable state, no invoice lock, and no payment or stock movement on the order;
+- `releasableUnits`, the units a release would free now: the sum of the lines that still hold
+  stock. A line whose ledger nets below zero cancels nothing out. `releaseAllowed` is the order's
+  answer on a release;
+- the `allocationBadge`. `EXPIRED` means the allocation sweeper will cancel the order. An order it
+  leaves alone (placed, holding money, parked, held by a fulfillment) never shows it;
+- the edit block on correcting a fulfillment's quantities (`fulfillmentCorrection`);
+- `sourceFulfilled`: an import the source platform already handed to its own fulfillment provider,
+  on a store that blocks shipping it twice;
+- the `park` and the review `hold`;
+- the app providers the order runs without (`providerFallbacks`);
+- the states a change-status menu lists (`nextStates`, empty on a live cart).
+
+#### Actions
+
+Each of `actions` says whether the ORDER allows it (`eligible`) and whether THIS caller may take it
+now (`allowed`), so a head can show an action greyed out with its reason. `reasonCode` is null
+exactly when `allowed`.
+
+| Action | The write behind it | The caller needs |
+|---|---|---|
+| `MODIFY` | the Edit Order flow: move the order to `Modifying`, `modifyOrder`, move it out again | `UpdateOrder` |
+| `DELETE` | `deleteOrder` | `DeleteOrder` |
+| `RELEASE_ALLOCATION` | `releaseOrderAllocation` | `UpdateOrder`, and every stock location the reservation sits at when the credential is restricted to locations |
+| `CORRECT_FULFILLMENT` | one of two writes, see below | see below |
+| `CANCEL` | `cancelOrder` for the whole order | `UpdateOrder` |
+| `TRANSITION` | `transitionOrderToState` into one of `nextStates` | `UpdateOrder` |
+| `MARK_COMPLETED` | `markOrderCompleted` | `UpdateOrder` |
+| `REOPEN` | `reopenOrder` | `UpdateOrder` |
+
+`MODIFY` says the flow can open from the order's present state, so an order already in `Modifying`
+answers `STATE`.
+
+**`CORRECT_FULFILLMENT` has two writes with different gates.**
+
+| Write | Needs | Works on |
+|---|---|---|
+| `updateFulfillmentLineQuantities` | `UpdateOrder` | any store, any fulfillment of the order |
+| `correctFulfillmentQuantities` | `UpdateFulfillment` or `UpdateOrder` | only a store with the warehouse workspace (`WAREHOUSE_NOT_ENABLED` otherwise). For a caller without `UpdateOrder`, only a fulfillment that ships from a warehouse the caller is assigned to (`LOCATION_OUT_OF_SCOPE` otherwise), and never to lower the ordered quantity (`OFFICE_ONLY`) |
+
+So a caller with `UpdateOrder` is allowed whenever the order is eligible. A caller holding
+`UpdateFulfillment` without `UpdateOrder` is allowed only on a store with the warehouse workspace,
+and only while at least one of this order's fulfillments ships from one of the caller's warehouses.
+That caller must call `correctFulfillmentQuantities`: the other write answers `FORBIDDEN`. An order
+with no fulfillment gives such a caller `PERMISSION`. The answer is about the order: whether one
+given fulfillment can still be corrected is that fulfillment's own state.
+
+#### Reason codes
+
+| `reasonCode` | Meaning |
+|---|---|
+| `INVOICE_LOCKED`, `COMPLETED`, `CANCELLED` | the edit block |
+| `STATE` | the order's state does not allow it |
+| `NOTHING_ALLOCATED` | no line holds stock to release |
+| `HAS_RECORDS` | the order carries a payment or a stock movement, which a delete cannot remove. Cancel a draft, or a shopper's live cart, instead: `CANCEL` is open on it |
+| `NOTHING_TO_CANCEL` | the order's lines hold no unit. Delete an empty draft instead |
+| `SHOPPER_CART` | a live cart, a shopper's or a till's open sale in the cart state: its status is not moved, completed or reopened. `CANCEL` answers it too on a cart with no payment and no stock movement (delete it instead) and on a till's open sale (ended at the till) |
+| `UNITS_SHIPPED` | a shipped or delivered fulfillment holds a line. Those units come back through a return |
+| `ACTIVE_FULFILLMENT` | a fulfillment not yet shipped holds a line. Detach the order from it or correct its quantities first |
+| `PERMISSION` | the order allows it and this caller may not. The only reason about the caller |
+
+Both lists grow, so `action` and `reasonCode` are typed to accept a string this version does not
+name. Treat an unknown one as "not available". `ORDER_STATUS_ACTIONS`, `ORDER_STATUS_REASON_CODES`,
+`ORDER_LOCK_REASONS`, `ORDER_ALLOCATION_BADGES` and `ORDER_EDIT_BLOCK_CODES` are the lists this
+version knows.
+
+An order this store does not hold is a `NotFoundError` (`ENTITY_NOT_FOUND`), the same as a missing
+id. This is a root query of its own, never a field on an order list. It needs an engine that serves
+`orderStatus`; on an older one only this call fails.
+
 ### Payment providers
 
 Onboard the PSP account a store is paid through, place its card terminals, and ask whether it can
@@ -609,6 +2114,46 @@ response carries a link that can be single-use, an idempotency store keeps a res
 and re-serves it, and retrying is safe anyway — a repeat replaces the pending attempt and answers
 with a fresh url and state, which is what a merchant who lost the first link needs.
 
+### Unapplied cash: an overpayment on the customer's account
+
+A customer who paid more than an order bills (a second transfer, an edit that lowered a paid
+order's total) can keep that money on their account instead of having it refunded. It is held
+there as unapplied cash until it pays an invoice or is paid back.
+
+```ts
+// Move what the order holds over what it bills. One receipt per payment it came from.
+const [cash] = await admin.payments.accountCredit.creditOverpayment(
+  { orderId, reason: 'Paid twice by bank transfer' },
+  { idempotencyKey }
+);
+
+await admin.payments.accountCredit.list(customerId);            // oldest first
+await admin.payments.accountCredit.apply({ unappliedCashId: cash.id, invoiceId });
+await admin.payments.accountCredit.refund({ unappliedCashId: cash.id, amount: 500 });
+
+const onAccount = await admin.payments.accountCredit.onOrder(orderId);
+onAccount.creditedToAccount;   // no longer refundable from the order, no longer `overpaid`
+```
+
+**For stores that keep their own accounts-receivable ledger, and customers with a credit account in
+it.** Anywhere else the calls are refused (`AR_LEDGER_NOT_ENABLED`, `AR_ACCOUNT_REQUIRED`, or
+`AR_ACCOUNT_IN_ERP` on a store whose ERP integration is on) and the overpayment is refunded with
+`payments.refund`. An order that is already on an AR invoice is refused too
+(`AR_ORDER_ALREADY_INVOICED`): refund its overpayment.
+
+**It is never a credit note.** Nothing that was billed is credited; the customer's balance simply
+shows the store owes them the money. Applying it to an invoice leaves the balance where it was.
+
+**The money leaves the order.** `payments.refundPosition` takes it off `refundable` and
+`payments.position` stops reporting it as `overpaid`. It goes back to the customer only through
+`accountCredit.refund`, which refunds the payment it came from and follows `payments.refund`'s rules,
+including `IDEMPOTENCY_OUTCOME_UNKNOWN`: the cash then stays on the account, frozen, until
+`payments.reconcileRefund` records the provider's answer.
+
+A customer who still has unapplied cash cannot be erased (`CUSTOMER_HAS_UNAPPLIED_CASH`): pay it back
+or apply it first, and wait for the payout's refund to complete. `accountCredit.list(customerId)`
+shows what is held.
+
 **One connection, every store of the seller.** `UpdatePaymentMethod` in ANY of a seller's stores can
 disconnect and re-connect, which re-points revenue for all of them. That is the same sharing that
 makes onboarding happen once, but it means the permission's blast radius is the seller, not the
@@ -636,9 +2181,20 @@ itself refused, with its own message kept out of the response),
 terminal or a readiness question names another channel's location — the same code the rest of the
 platform uses for that one rule.
 
-`LIVE_CONNECTION_REFUSED` is declared and classified but nothing throws it yet: the rule that a
-sandbox store may hold only a `test` connection needs a way to identify a sandbox store, which
-arrives with the sandbox flag. `readiness.mode` already reports which kind a store holds.
+`LIVE_CONNECTION_REFUSED` (`BusinessRuleError`): a sandbox store may hold only a `test`
+connection, so `startOnboarding`/`completeOnboarding` refuse a provider account that reports
+`live` on one, before any connection is written. The legacy path follows the same rule: a
+Mollie/Stripe key stored on a sandbox's payment method must be a test key (`test_…`,
+`sk_test_…`). `readiness.mode` reports which kind a store holds, and a live connection or legacy
+key seen from a sandbox store (through a shared seller, or a method assigned from elsewhere) reads
+not ready, with the reason as its first blocker.
+
+`LIVE_PAYMENT_REFUSED` (`BusinessRuleError`): the same rule when the store PAYS. A sandbox store
+never moves money through its seller's live account. A card-terminal charge on a live connection
+is refused before the provider is asked, and so is a Stripe payment through the seller's Connect
+account when a live store also trades under that seller. A POS card tender reports it as
+`POS_CARD_PAYMENT_FAILED` with the refusal's sentence, and nothing is recorded on the order. A live
+store on a live connection, and a sandbox on a test one, pay as before.
 
 Reading needs `ReadPaymentMethod`, writing `UpdatePaymentMethod`.
 
@@ -656,7 +2212,7 @@ const invoice = await admin.documents.generate(orderId, 'invoice', {
 });
 
 const data = await admin.documents.data(invoice.id, 'invoice');
-data.numbering;           // { scope: 'channel', scopeId, series, number }
+data.numbering;           // { scope: 'legal_entity' | 'channel', scopeId, series, number }
 data.totals?.totalWithTax; // the figures the PDF printed, in minor units (null on a lump-sum note)
 data.reconciled;          // false when the ORDER moved after the invoice was numbered
 
@@ -664,6 +2220,13 @@ await admin.documents.invoices(orderId);       // a Page; complete today
 await admin.documents.creditNotes(orderId);
 await admin.documents.previewInvoice(orderId, { invoicedOn: '2026-09-18' }); // PDF bytes, nothing stored
 await admin.documents.sendInvoiceEmail({ orderId, recipientsTo: ['ap@buyer.example'] });
+await admin.documents.sendCreditNoteEmail({ creditNoteId, recipientsTo: ['ap@buyer.example'] });
+await admin.documents.creditNoteEmailSends(orderId); // who each credit note was emailed to
+
+// A customer's invoices and credit notes in this store, newest first, paged.
+const page = await admin.documents.forCustomer(customerId, { limit: 10 });
+page.items[0]?.type; // 'invoice' | 'credit-note'; the document is on `invoice` or `creditNote`
+const next = await page.next(); // null on the last page
 ```
 
 **`documentData` is the read to build on.** It returns what the document was numbered with —
@@ -674,9 +2237,138 @@ standard invoice derives its lines from the order, and an order can be modified
 numbered), and `taxSummary` is `null` rather than `[]` on a lump-sum credit note that never stated a
 per-rate split.
 
+**A refused correction says why in a code.** `issuePartialCreditNote` answers `INVOICE_NOT_FOUND`,
+`ORDER_NOT_INVOICED`, `INVOICE_ALREADY_VOIDED`, `INVOICE_CREDIT_EXCEEDS_INVOICE`, the `REFUND_*`
+pre-checks and the others its TSDoc lists, each before any money moves or any number is drawn. Branch
+on `error.code`, never on the sentence. An older engine answered all of them as `USER_INPUT_ERROR`.
+`issueSupplementaryInvoice` codes its refusals the same way (its TSDoc lists them); an older engine
+answered them as `USER_INPUT_ERROR`, or as an uncoded error for the order's state and a store with
+invoicing switched off.
+
 Numbering, the VAT summary and issuer identity stay platform-owned — there is no method that
-allocates a number. `numbering.scope` is modelled for the per-legal-entity series multi-region will
-add, so a consumer reading `scope`/`scopeId` keeps working when it lands.
+allocates a number. `numbering.scope` is `legal_entity` for an invoice or credit note numbered in its
+legal entity's series (shared by every store of that entity; `scopeId` is the entity), and `channel`
+for a store numbering on its own. `issuer` is the one FROZEN when the document was issued: editing the
+legal entity later never changes what an issued document reports or reprints.
+
+#### Planning a correction
+
+An issued invoice is never edited: it is credited, voided, reissued or supplemented. Ask the server
+what a correction would do before anything is written.
+
+```ts
+// Step 1: which outcomes this invoice can take, and the lines a correction starts from.
+const start = await admin.documents.planCorrection({ ledger: 'RETAIL', invoiceId });
+start.outcomes;   // [{ outcome: 'DETAILS_WRONG', available: false, unavailableCode: 'INVOICE_HAS_PARTIAL_CREDITS', … }, …]
+start.prefill;    // { source: 'order', basis: 'gross', lines, seededGross, billedGross, differs }
+
+// Step 2: plan one outcome as the merchant fills it in. Only a plan with an outcome has a
+// refund (`start.refund` is null): its options are what this outcome's amount can go back to.
+const credit: InvoiceCorrectionInput = {
+  ledger: 'RETAIL',
+  invoiceId,
+  outcome: 'OVER_CHARGE',
+  reason: 'Priced 3 bottles at the wrong tier',
+  lines: [{ description: 'Merlot 2021', quantity: 3, unitPrice: 250, unitPriceBasis: 'gross', taxRate: 21 }],
+};
+const draft = await admin.documents.planCorrection(credit);
+draft.refund;     // { amount, available, options: [{ paymentId, refundable }], recommendedPaymentId }
+
+// Step 3: plan it again with the payment the merchant picked: that plan is the one to commit.
+const plan = await admin.documents.planCorrection({
+  ...credit,
+  refundPaymentId: draft.refund?.recommendedPaymentId ?? undefined,
+});
+plan.settlement;  // 'REFUND' (or 'NONE' when no payment was named)
+plan.blockers;    // [] when it can be committed; else [{ code, message, path }]
+plan.lineTotals;  // the issue's own figure (round once at the line)
+plan.documents;   // [{ type: 'CREDIT_NOTE', kind: 'adjustment', documentDate, totals, numbering: { provider, external, ready } }]
+plan.planHash;    // names what the merchant saw
+```
+
+`planCorrection` writes nothing and **never shows or reserves a number**: every issue draws its
+number in its own committed transaction, so a preview that drew one would use it up. A credit note
+follows its invoice's provider: where `numbering.external` is true (an ERP such as AFAS), committing
+the correction books the documents in the ERP, and that cannot be undone from the platform.
+
+The four outcomes are `OVER_CHARGE` (a partial credit note; the invoice stands), `DETAILS_WRONG`
+(a full credit note and a corrected invoice: a reissue when no line changed, a re-bill when one
+did), `SHOULD_NOT_EXIST` (a full credit note; the invoice is voided) and `UNDER_CHARGE` (a
+supplementary invoice). A details correction that changes no address field and no line is refused
+(`INVOICE_CORRECTION_NOTHING_CHANGED`): it would only use up two numbers. A reissue also prints the
+issuer, legal entity, payment terms and PO reference as they stand now (an AR replacement keeps the
+invoice's own payment terms), so one that would print any of them differently from the invoice is a
+change and is planned (an invoice issued before the reference was recorded is never refused on it). Refund options are the
+order's refund position (`payments.refundPosition`), newest payment first; the AR ledger never
+refunds (its credit note credits the customer's account). On a store that keeps the customer's
+account itself, a retail over-charge or void may put the money on the account instead
+(`creditToAccount`, offered in `accountCredit`). Needs `UpdateOrder`. A plan that stages an
+address field other than the country is compared with the order's stored address, so an app below
+`customerData: full` is refused it (`CUSTOMER_DATA_NOT_GRANTED`).
+
+#### Committing a correction
+
+```ts
+const plan = await admin.documents.planCorrection(input);
+// … show plan.documents, plan.refund and plan.blockers; the merchant confirms …
+const done = await admin.documents.commitCorrection(input, {
+  expectedPlanHash: plan.planHash,
+  idempotencyKey: attemptKey, // one per attempt to commit; re-sent on a retry of that attempt
+});
+done.documents;     // [{ ledger, type: 'CREDIT_NOTE', id, number, kind, totalWithTax, issuedOn, numberingProvider }]
+done.refund;        // { id, state, total, paymentId } | null             (with refundPaymentId)
+done.accountCredit; // { amount, currencyCode, unappliedCashIds } | null  (with creditToAccount)
+done.plan;          // the plan that was carried out (its planHash is yours)
+```
+
+`commitCorrection` carries out the plan once. Hand it the SAME `input` you planned and the plan's
+`planHash` as `expectedPlanHash`. The engine plans again under the issuing services' locks and
+issues only when the hash is yours and nothing blocks: otherwise nothing is issued. Every document
+is put to its numbering provider's checks before the first one is numbered. Needs `UpdateOrder`.
+
+**Two paths.** Without a refund, everything is one transaction: the documents, and the account
+credit when there is one. With `refundPaymentId`, the refund comes first, outside any transaction,
+and the credit note follows. A refund the provider confirmed stays, even when the credit note
+cannot follow.
+
+**Account credit.** With `creditToAccount: true` (offered in the plan's `accountCredit`), nothing
+is refunded: the credited amount goes to the customer's account as unapplied cash, one receipt per
+payment it came from (`done.accountCredit.unappliedCashIds`). `admin.payments.accountCredit.apply`
+(the engine's `applyArUnappliedCash`) applies it to an open AR invoice later.
+
+`idempotencyKey`: one key per attempt to commit, re-sent unchanged on a retry of that attempt (a
+timeout, a dropped connection), which then answers what the first call answered and issues nothing
+twice. Pass your own: left out, the SDK makes one up and returns it as `idempotencyKey` on the
+result, but on a thrown error only as an untyped property of the error.
+
+| Refusal | Meaning |
+|---|---|
+| `INVOICE_CORRECTION_PLAN_CONFLICT` (`ConflictError`, 409) | The invoice, its order, the payments, the numbering or the date moved since the plan. Plan again, show the merchant the new plan, commit under a NEW key. |
+| `INVOICE_CORRECTION_BLOCKED` (`BusinessRuleError`, 422) | The plan has blockers, or a numbering provider refused a document before anything was numbered (an ERP's debtor, article or VAT checks). `error.details` lists them (`code` = the blocker's code). |
+| `IDEMPOTENCY_CONFLICT` (409) | The key was used for another request. |
+| `REFUND_REFUSED` (`BusinessRuleError`, 422) | The payment provider, or the engine before it asked the provider, refused the refund; nothing moved. A provider's refusal stays on the payment as a `Failed` refund, which moves the plan: once the payment can take the refund, plan again and commit the new plan under a NEW key. |
+| `planCorrection`'s refusals | The call is refused as `planCorrection` refuses it. |
+
+Nothing is issued on a refusal.
+
+`IDEMPOTENCY_OUTCOME_UNKNOWN` (`error.outcomeUnknown`) is neither success nor refusal, so never
+retry it blind. Either the refund reached the payment provider and its answer never came: no credit
+note was issued, and the key answers the same until the provider's answer is recorded with
+`admin.payments.reconcileRefund`, which frees it; then plan again. Or the refund was made and the
+credit note could not follow: plan again, and the credit note is issued without a refund.
+
+On an ERP-numbered store (`documents[].numberingProvider` is not `platform`), the documents are
+booked in the ERP. They cannot be undone from the platform: correct them there.
+
+`Invoice` and `CreditNote` now say how they were corrected and who numbered them:
+`reversedByCreditNoteId`, `supersededByInvoiceId`, `reissueOfInvoiceId` and `supplementsInvoiceId`
+on an invoice; `reversalOfInvoiceId`, `returnId` and `refundId` on a credit note; `lines` and
+`numberingProvider` on both.
+
+Needs an engine that serves `commitInvoiceCorrection`. The widened `Invoice` and `CreditNote`
+selections (`generate`, `invoices`, `creditNotes`, `issuePartialCreditNote`,
+`issueSupplementaryInvoice`) need an engine that serves those fields (`numberingProvider`, …):
+deploy the engine before this SDK version.
 
 #### Extension blocks
 
@@ -811,6 +2503,742 @@ not currently distinguish a plain retail channel from one where quoting is enabl
 The service caches the manifest 60 s per channel and serves it with an `ETag`, so polling it is
 cheap. `installedApps` is on the wire already and stays empty until the app registry ships.
 
+`sandbox` says whether the store is a sandbox (`platform.provisionStore({ sandbox: true })`):
+test-mode payments only, no ERP or marketing push, left out of platform metrics, purged past retention
+holds. It is `null` when the platform could not read the flag this time — such a manifest is not
+cached — and absent on a platform older than the field. Treat anything but `true` as "not a
+sandbox".
+
+### Plugin entitlements
+
+`admin.tenant.entitlements()` lists the plugins the **active** store may use: its own grants and
+the ones its organization holds for every member store. It reads the same union the engine reads
+when it decides whether a plugin's back-office operations are allowed.
+
+```ts
+const grants = await admin.tenant.entitlements();
+// [{ pluginKey: 'pos', source: 'channel' }, { pluginKey: 'seo', source: 'organization' }]
+
+const showPos = grants.some((grant) => grant.pluginKey === 'pos');
+```
+
+- **Fresh on every call.** A grant switched in Platform → Plugins (or on the organization) answers
+  on the next call, so a head can hide or show a plugin's screens without a reload. Only a store's
+  organization membership is remembered (up to 60 s per server process), so a store that has just
+  joined one may take a minute to list its organization's grants.
+- **`source`:** `channel` for the store's own grant, `organization` for one its organization
+  holds. When both exist the store's own wins, so a key appears once. `source` is typed as the
+  names this SDK knows but carries any string, so a source a newer engine adds reaches you
+  unchanged.
+- **Permission:** `ReadCatalog` or `ReadSettings` on the store; without either the engine answers
+  `FORBIDDEN` (403). There is no channel argument: a store's token reads its own store, and a
+  SuperAdmin reads any store with that store as the tenant.
+- **Use it to hide or show; never treat it as a grant.** The engine checks the grant itself on
+  every operation, so a plugin listed here can still be refused if Platform → Plugins switched it
+  off in between.
+- `tenant.capabilities()` also reports `entitled` per plugin. That answer can be up to 60 s old,
+  and it says whether the plugin is set up as well. Read `entitlements()` when you only need the
+  grant, and need it current.
+
+### Platform — plugin entitlements
+
+`admin.platform.entitlements` is the platform's control plane for which external plugins each store
+may use (Platform → Plugins in the dashboard). Every method needs a human SuperAdmin session — an API
+token or an app credential is refused with `PLATFORM_REQUIRES_SESSION` (403) before anything is sent
+— and none needs a tenant on the client:
+
+```ts
+const entitlements = human.platform.entitlements;
+
+// One store's grants, its organization's included.
+const grants = await entitlements.list(store.id);
+// [{ pluginKey: 'mollie', source: 'channel', connectedAt: '2026-10-07T08:00:00.000Z', … },
+//  { pluginKey: 'seo', source: 'organization', … }]
+
+// Every grant on the platform, e.g. to count each store's connected plugins.
+const all = await entitlements.listAll();
+
+// Connect a plugin for a store (answers its own row), then disconnect it (answers null).
+await entitlements.set(store.id, 'pos', { connected: true, notes: 'contract 2026-114' });
+await entitlements.set(store.id, 'pos', { connected: false });
+```
+
+- **`source`:** `channel` for the store's own grant, `organization` for one its organization holds
+  for every member store and its workspace. When both exist the store's own row wins, so `list`
+  answers a key once. `listAll` repeats an organization grant once per member store and once for
+  the organization's workspace, each under that channel's id (and the organization grant's `id`,
+  so key a row by `channelId` and `pluginKey`). `source` is typed as the names this SDK knows but
+  carries any string.
+- **An organization's grant is changed on the organization**
+  (`platform.organizations.entitlements.set`). Disconnecting a plugin a store holds only through its
+  organization is refused `MANAGED_BY_ORGANIZATION` (422 `BusinessRuleError`). Disconnecting a store's
+  own grant of a plugin its organization also grants answers `null`, and the store keeps the plugin
+  through the organization: `list` then shows it as `source: 'organization'`.
+- **Connecting again** refreshes `connectedAt` and `connectedByUserId`. Omitted `notes` keep the
+  stored ones; `''` clears them. Notes hold at most 512 characters; a longer value fails the write.
+- **Other refusals:** `ORGANIZATION_WORKSPACE_NOT_A_STORE` (422: an organization's workspace holds
+  plugins only through its organization), `USER_INPUT_ERROR` (400 `ValidationError`: the key is not an
+  external plugin of the platform catalog; core plugins such as search and email have no
+  entitlement), `FORBIDDEN` (403: not a SuperAdmin).
+- **The engine does not check that a channel id names a store**, so pass ids read from the
+  platform's channel list.
+- The engine reads the grants on every operation; the plugins service's own gates follow a change
+  within its 60-second entitlement cache.
+
+### Platform — organizations
+
+An organization groups stores that are run together. Its workspace is a channel of its own,
+`org-<code>`, which owns what the organization shares with its member stores. Every method needs
+a human session — an API token or an app credential is refused with `PLATFORM_REQUIRES_SESSION`
+before anything is sent — and a SuperAdmin needs no tenant on the client:
+
+```ts
+const organizations = human.platform.organizations;
+
+const org = await organizations.create({
+  code: 'acme-eu',          // immutable: the workspace channel becomes `org-acme-eu`
+  name: 'Acme Europe',
+  defaultLanguageCode: 'en',
+  defaultCurrencyCode: 'EUR',
+  country: 'NL',            // or both defaultTaxZoneId and defaultShippingZoneId
+});
+
+await organizations.update({ id: org.id, assortmentMode: 'selected' });
+await organizations.getByCode('acme-eu');       // the organization code; null when none has it
+for await (const each of await organizations.list()) console.log(each.code, each.memberCount);
+
+// The organization tier of plugin entitlements: a grant reaches every member store.
+await organizations.entitlements.set({ organizationId: org.id, pluginKey: 'mollie', connected: true });
+await organizations.entitlements.list(org.id);
+
+// Repair: register the workspace in the CMS channel mirror (safe to repeat).
+await organizations.registerWorkspace(org.id);
+```
+
+An organization answers its workspace as `hubChannel { id, code, pricesIncludeTax }`. The tax mode
+is the organization's: every member store enters prices the same way, so it is what a store created
+under the organization starts from (`provisionStore` with `organization` and no `pricesIncludeTax`
+takes it).
+
+`create` registers the workspace channel in the CMS channel mirror once the organization is
+committed; that mirror is what a client scoped to `org-<code>` resolves the channel through. If the
+CMS is unavailable the organization is still created — the failed call is in the audit trail — and
+`registerWorkspace(id)` completes it later. Until then a client scoped to that workspace is refused
+with `CHANNEL_NOT_FOUND` (404) before anything is sent. `registerWorkspace` answers the organization,
+is SuperAdmin-only, and refuses with `ORGANIZATION_NOT_FOUND` / `ORGANIZATION_WORKSPACE_NOT_FOUND`
+(404) or, when the CMS does not confirm it, `ORGANIZATION_WORKSPACE_REGISTRATION_FAILED` (422
+`BusinessRuleError` — retry later).
+
+The writes are Admin API mutations, so an idempotency key deduplicates nothing. `create` is safe
+to repeat anyway: a second create on a taken code is refused with `ORGANIZATION_CODE_TAKEN`
+(`ConflictError`, 409) — read a create whose answer was lost back with `getByCode`. Revoking a
+plugin (`connected: false`) removes only the organization's grant; a store that holds the plugin
+itself keeps it. The plugins service follows a change within its 60-second entitlement cache.
+
+**Member stores.** A store joins an organization with `join`, and `members` lists them:
+
+```ts
+const store = await human.channels.byCode('acme-nl');
+const membership = await organizations.join({
+  organizationCode: 'acme-eu',   // the organization code, not the `org-acme-eu` channel code
+  channelId: store.id,
+  region: 'EMEA',                // optional grouping label
+  keepOwnSettings: true,         // optional: keep this store's own settings instead of inheriting
+});
+const stores = await organizations.members(org.id);   // oldest member first
+```
+
+Joining grants the organization's roles on the store and widens the workspace's currencies and
+languages to include the store's. It is idempotent: joining the organization a store is already in
+answers the same membership (`joinedAt` unchanged), so a join whose answer was lost is safe to
+repeat. An omitted `region` keeps the one a re-join finds; `null` (or `''`) clears it. By default
+the store inherits every settings group the organization shares; `keepOwnSettings: true` makes it
+keep its own values for every group instead (each can be switched to inherit later), and on a
+re-join adds only the groups it does not keep yet: one it inherits unlocked at that moment starts
+from a copy of the organization's values, so nothing changes for its customers. `false` or omitted
+changes nothing it already keeps, and is not sent, so an engine that predates the option still
+accepts the join. A store belongs to one organization at a time, and there is no way to leave yet. `join` is SuperAdmin-only
+and refuses with `ORGANIZATION_MEMBERSHIP_CONFLICT` (409 `ConflictError` — the store belongs to
+another organization), `ORGANIZATION_NOT_FOUND` / `ORGANIZATION_MEMBER_STORE_NOT_FOUND` (404),
+`ORGANIZATION_MEMBER_NOT_A_STORE` (the platform's root channel or a workspace) /
+`ORGANIZATION_MEMBER_STORE_CLOSED` (restore the store first) /
+`ORGANIZATION_TAX_MODE_MISMATCH` (the store's `pricesIncludeTax` differs from the organization's;
+every store of an organization enters prices the same way, judged on a first join) (422
+`BusinessRuleError`), or
+`ORGANIZATION_MEMBER_REGION_INVALID` (400: at most 64 characters, no line breaks). `members` leaves
+out stores that no longer exist, and refuses an unknown id with `ORGANIZATION_NOT_FOUND` (404)
+rather than answering an empty list.
+
+**An organization admin** — the organization's `org-<code>-admin` role, not a SuperAdmin — may call
+`get`, `getByCode`, `list`, `update` and `members` for its own organization, with the workspace
+channel as the tenant:
+
+```ts
+const workspace = human.withTenant({ scope: { kind: 'channel', code: 'org-acme-eu' } });
+const own = await workspace.platform.organizations.getByCode('acme-eu');
+```
+
+The engine decides whose organization it is from the active channel, so anywhere else the call is a
+`PermissionDeniedError` (403): `FORBIDDEN` with no tenant or on a channel where the caller holds no
+`ManageOrganization`, `ORGANIZATION_ACCESS_DENIED` for another organization, whether or not it
+exists. `list` answers only the caller's own. `create`, `registerWorkspace`, `join` and
+`entitlements.*` stay SuperAdmin-only.
+
+**A new store inside an organization:** pass its code to `platform.provisionStore`, and the store
+joins it as the run's last step. An unknown code is `ORGANIZATION_NOT_FOUND` (404) before any run
+exists. Leave `pricesIncludeTax` out and the store takes the organization's mode; a different value
+is `ORGANIZATION_TAX_MODE_MISMATCH` (422 `BusinessRuleError`), also before any run. If only the join
+fails, the store is kept, not rolled back: `wait()` throws
+`PROVISION_RUN_FAILED` saying so, `provisionRun(runId).result` still names the store, and
+`organizations.join` (safe to repeat) finishes the job. A store can also be created under an
+existing legal entity (`legalEntity`, see [Legal entities](#legal-entities)).
+
+```ts
+const store = await human.platform
+  .provisionStore({ ...storeInput, organization: 'acme-eu' }, { idempotencyKey: idempotencyKey() })
+  .then((run) => run.wait());
+```
+
+#### Sharing policy
+
+What an organization shares with its member stores is decided at two gates: the platform (a
+SuperAdmin) **allows** a kind for the organization, and the organization admin **enables** an
+allowed kind and, for the kinds that can be, **locks** it so no member store can override it.
+Every method answers the kind's state after the call; `get` answers every kind the platform can
+share, the ones not allowed included, each with its `name`, `lockable` and `phase` (the
+multi-region phase that makes it take effect — until then it is only a setting). Two kinds,
+`entitlements` and `roles`, are `alwaysOn`: every organization shares them with no policy, so they
+always read `allowed` and `enabled`, never `locked`, and `allow`, `disallow` or `set` on them is
+refused with `ORGANIZATION_SHARING_KIND_ALWAYS_ON` (`BusinessRuleError`, 422).
+
+```ts
+const sharing = human.platform.organizations.sharing;
+
+await sharing.allow({ organizationId: org.id, kind: 'settings.branding' });   // SuperAdmin; starts off
+await sharing.set({ organizationId: org.id, kind: 'settings.branding', enabled: true, locked: true });
+const policy = await sharing.get(org.id);   // [{ kind, name, allowed, enabled, locked, lockable, phase, alwaysOn }, …]
+
+// Switching a locked kind off unlocks it in the same call; then the platform may withdraw it.
+await sharing.set({ organizationId: org.id, kind: 'settings.branding', enabled: false, locked: false });
+await sharing.disallow({ organizationId: org.id, kind: 'settings.branding' });
+```
+
+`allow` and `disallow` are SuperAdmin-only and safe to repeat (allowing an allowed kind keeps what
+the organization set; withdrawing one that is not allowed changes nothing). `get` and `set` also
+answer the organization admin for its own organization, with the workspace channel as the tenant,
+exactly like `get` above. `set` changes only the flags it is given. Refusals: a kind the engine does
+not know is `ORGANIZATION_SHARING_KIND_INVALID` (400); `set` on a kind the platform has not allowed
+is `ORGANIZATION_SHARING_KIND_NOT_ALLOWED` (403); locking a kind that cannot be locked
+(`settings.tax_display` never can) is `ORGANIZATION_SHARING_LOCK_INVALID` (400); any change that
+would leave a kind locked while off is `ORGANIZATION_SHARING_DISABLED_LOCK_INVALID` (400);
+switching off a kind something still depends on is `ORGANIZATION_SHARING_KIND_IN_USE_CONFLICT`
+(409); switching `catalog` on while a member store's `pricesIncludeTax` differs from the
+organization's is `ORGANIZATION_TAX_MODE_MISMATCH` (422, naming the stores); and `disallow` while
+the organization has the kind on is `ORGANIZATION_SHARING_KIND_ENABLED_CONFLICT` (409). While
+`catalog` is on, changing `pricesIncludeTax` on the workspace or a member store is refused with
+`ORGANIZATION_TAX_MODE_LOCKED` (422).
+
+A kind whose `phase` the platform has not released yet reads like any other, but `allow`, and a
+`set` that switches it on or locks it, are refused with `ORGANIZATION_SHARING_KIND_NOT_YET_AVAILABLE`
+(`BusinessRuleError`, 422): no store, worker or dashboard of that release handles it. Nothing is
+queued; allow it again once the platform ships the phase. Switching such a kind off and withdrawing
+it stay open, so a policy written before the gate can always be backed out.
+
+Switching a `settings.*` kind off (locked or not) is never refused for its dependents. It first
+copies the organization's current values into every member store that uses them, in the same
+call: those stores keep them as their own, so their customers see no change, and a store that
+kept its own values keeps them. When the copy cannot be made nothing changes, the kind stays on,
+and `set` is refused (`BusinessRuleError`, 422): `ORGANIZATION_SETTINGS_COPY_FAILED` or
+`ORGANIZATION_SETTINGS_COPY_UNAVAILABLE` (the SEO service could not copy `settings.seo`; try
+again later), or `ORGANIZATION_SETTINGS_NOT_COPIED` (try again). Before a platform release that
+copies, switching a settings kind off leaves those stores on their own earlier values.
+
+When more member stores use the values than one call copies into (25), `set` answers at once
+with the kind still `enabled`, and the switch-off runs in the background: a job copies into the
+stores in batches, then switches the kind off about 35 s after the last copy (a run can read
+`storesDone === storesTotal` and still be `running` meanwhile). Until then every store keeps
+using the organization's values, and any change of that kind (`set`, `disallow`, a store's
+Override or Inherit, the workspace's own edit of those settings) is refused with
+`ORGANIZATION_SETTINGS_SWITCH_OFF_CONFLICT` (`ConflictError`, 409). Withdrawing such a kind is
+therefore: switch it off, wait for the run, then `disallow`. Follow the run with `switchOffs`
+(each settings kind's latest run while it agrees with the kind: a `running` one always, a
+`failed` one while the kind is still on, a `completed` one while it is off, a settled one only
+until the kind's policy changes again; otherwise null) or
+`switchOff(id)`. A `failed` run leaves the kind on; switching
+it off again starts a new run. Both methods need a platform release that runs switch-offs in the
+background; against an older engine they fail as a whole, and `get`/`set` are unaffected.
+
+```ts
+await sharing.set({ organizationId: org.id, kind: 'settings.email', enabled: false });
+const [email] = (await sharing.switchOffs(org.id)).filter((entry) => entry.kind === 'settings.email');
+// email.switchOff → { id, status: 'running', storesDone: 25, storesTotal: 60, errorCode: null, … }
+const run = await sharing.switchOff(email.switchOff.id);   // 'completed' once the kind is off
+```
+
+### Legal entities
+
+A legal entity is the company that issues a store's invoices: its legal name, VAT, UK VAT, EORI and
+registration numbers, registered office and fiscal time zone. One or more stores trade under it. The
+store's own address, country and time zone stay the store's.
+
+The active store's entity is `admin.tenant.legalEntity`:
+
+```ts
+const entity = await admin.tenant.legalEntity.get();
+// { id, legalName, vatNumber, registeredAddressLine1, …, registeredCountry, timezone,
+//   stores: [{ id, code }], storeCount, editable }   — null for a store with none
+
+if (entity?.editable) {
+  await admin.tenant.legalEntity.update({ vatNumber: 'NL123456789B01', registeredCity: 'Utrecht' });
+}
+```
+
+- **Permissions:** reading needs `ReadSettings` on the store. Changing needs `UpdateSeller` on
+  **every** store of the entity, because the entity prints on all of their invoices.
+- **A shared entity:** a store whose entity it shares with stores you don't run reads it with
+  `editable: false`. `stores` lists only the stores you may read, and `storeCount` counts all of
+  them. `update` is then refused with `SHARED_SELLER_NOT_ALLOWED` (403 `PermissionDeniedError`).
+- **What an update writes:** the legal name and the four numbers are copied onto every store of
+  the entity in the same transaction. The registered office and time zone are the entity's alone.
+- **Two requests:** `update` reads the active store's entity first. A store with none is refused
+  with `LEGAL_ENTITY_NOT_FOUND` (404) before anything is written.
+
+The platform list and the SuperAdmin writes are `admin.platform.legalEntities`. Every method needs
+a human session, and a SuperAdmin needs no tenant on the client:
+
+```ts
+const legalEntities = human.platform.legalEntities;
+
+const created = await legalEntities.create({
+  legalName: 'Acme Group B.V.',          // required; never empty
+  registeredCountry: 'NL',               // upper-case ISO 3166-1 alpha-2
+  timezone: 'Europe/Amsterdam',          // IANA
+});
+await legalEntities.update(created.id, { vatNumber: 'NL123456789B01', registeredProvince: null });
+for await (const each of await legalEntities.list({ term: 'acme' })) console.log(each.legalName);
+await legalEntities.get(created.id);     // null when none has that id, or you may read none of its stores
+```
+
+- **`list` and `create`:** SuperAdmin only.
+  - `list` answers every entity with at least one store, by legal name. Pages default to 50.
+  - A `limit` above 100 is refused with `INVALID_LIMIT`, and a bad offset with `INVALID_OFFSET`
+    (400 `ValidationError`).
+  - `term` matches the legal name, name, VAT or registration number as typed.
+- **A new entity has no store,** so it is not listed until a store is created under it, and only a
+  SuperAdmin reads it by id. A store created under it, or moved onto it, takes its legal name and
+  numbers.
+- **`get` and `update` work through every store,** like the tenant module. Anyone but a SuperAdmin
+  needs the permission on every store of the entity (`SHARED_SELLER_NOT_ALLOWED` otherwise).
+- **Field values:** the engine trims every value. `null` or `''` clears a field, except the legal
+  name, which is never cleared (`LEGAL_ENTITY_FIELD_INVALID`). A field left out is kept.
+- **Other refusals:** a country that is not upper-case alpha-2 is `INVALID_COUNTRY_CODE`. A fixed
+  offset or unknown zone is `INVALID_TIMEZONE`. Both are 400 `ValidationError`.
+- **No idempotency key:** the writes are Admin API mutations, so a key deduplicates nothing.
+  `update` is safe to repeat. A `create` whose answer was lost cannot be recovered through this
+  module: the new entity has no store yet, so `list` does not return it, and its id went with the
+  answer. Repeating it makes a second entity, so confirm with the platform operator before retrying
+  a create whose outcome is unknown. Creating the entity WITH its first store avoids this: see
+  below.
+
+These methods need an engine with the legal-entity Admin API (multi-region phase 2, B4). Against an
+older engine the request fails GraphQL validation (`GRAPHQL_VALIDATION_FAILED`).
+
+**A new store under a legal entity** is `platform.provisionStore`. Two ways:
+
+- **A new entity (the default):** send the store's `legalName` (and `vatNumber`,
+  `registrationNumber`) and no `legalEntity`. The run creates the entity with the store and undoes
+  both if it fails, so there is no lost create to recover, and the run's `idempotencyKey` covers it.
+- **An existing entity:** send its id as `legalEntity` and none of the three legal fields. The
+  store takes the entity's legal name and numbers; its address, country and time zone are its own.
+  A run that fails undoes the store and never the entity.
+
+```ts
+const store = await human.platform
+  .provisionStore({ ...storeInputWithoutLegalFields, legalEntity: created.id }, { idempotencyKey: idempotencyKey() })
+  .then((run) => run.wait());
+// store.sellerId === created.id; legalEntities.get(created.id) now lists the store
+```
+
+Refused before any run exists, so nothing is built:
+
+| Code | Error | When |
+| --- | --- | --- |
+| `LEGAL_ENTITY_FIELDS_CONFLICT` | 400 `ValidationError` | `legalName`, `vatNumber` or `registrationNumber` sent with `legalEntity`, even equal to the entity's. Change the entity with `legalEntities.update`. |
+| `LEGAL_ENTITY_NOT_FOUND` | 404 `NotFoundError` | No legal entity has the id. An organization workspace's Seller and the platform's own are not legal entities. |
+| `LEGAL_ENTITY_INCOMPLETE` | 422 `BusinessRuleError` | The entity has no legal name, so the store would have none. Set it with `legalEntities.update` first. |
+| `ORGANIZATIONS_NOT_AVAILABLE` | 400 `ValidationError` | The commerce engine predates legal entities. |
+
+A sandbox store (`sandbox: true`) may be created under an entity that live stores trade under, and
+the other way round. Its invoices and credit notes are numbered on its own sequence with a fixed
+`TEST-` prefix, so they never take a number of the entity's series, and it never pays through the
+entity's live provider accounts (`LIVE_PAYMENT_REFUSED`).
+
+An entity that stops being one between the request and the run (it was deleted meanwhile) fails
+the run at step `seller` before the store exists, and the run ends `compensated`.
+
+#### A legal entity's numbering
+
+The entity's stores share its numbering series: `invoice` and `credit_note`, and `ar_credit_note`
+where B2B credit is installed. A store's invoice, credit note or AR credit note takes the next number
+of the entity's series, whichever store issues it. A sandbox store numbers on its own rows and is not
+one of the series' stores.
+
+```ts
+const numbering = await admin.tenant.legalEntity.numbering.get();
+// { legalEntityId, series: [{ series: 'invoice', configured, prefix, suffix, digits, yearFormat,
+//   yearReset, nextNumber, lastResetYear, invoicingProvider }, …], stores, storeCount, editable }
+
+if (numbering?.editable) {
+  await admin.tenant.legalEntity.numbering.update({ series: 'invoice', prefix: 'ACME-', digits: 6 });
+}
+// The platform's, by id (human session):
+const entityId = created.id; // a legal entity's id, e.g. from legalEntities.create above
+await human.platform.legalEntities.numbering.update(entityId, { series: 'credit_note', yearFormat: 'full' });
+```
+
+- **Permissions:** `get` without an id needs `ReadSettings` on the store; by id, `ReadSettings` on
+  every store of the entity. `update` needs `UpdateSettings` on **every** store of the entity
+  (`SHARED_SELLER_NOT_ALLOWED`, 403). A SuperAdmin passes. The platform methods need the id: a
+  missing or blank one is refused before sending (`LEGAL_ENTITY_ID_REQUIRED`, 400); for the active
+  store's entity use the tenant module.
+- **Format only.** `nextNumber` and `lastResetYear` are read-only: only issuing a document moves
+  them. A field left out is kept, and only the fields that differ from the series count, so on a
+  configured series sending back what you read changes nothing.
+- **What an update writes:** the format on the entity and on every store row of the series, in one
+  transaction, holding the same locks as the allocator (the store rows, then the entity's).
+- **A series not set up yet** (`configured: false`, every field null): a lone numbering store's
+  first document sets it up. With two or more (AR credit notes: two or more that issued), every
+  store's documents are refused with `LEGAL_ENTITY_NUMBERING_UNSET` until an `update` sets the
+  series up, and **any** `update` does, even an empty one or one sending back the nulls you read.
+  The series then continues past every number any store issued, in the format of the one store that
+  issued (or the one format the stores chose, else the defaults) with your change on top. Its
+  invoicing provider and ERP number field are the ones the stores share; stores that differ in
+  either are refused with `LEGAL_ENTITY_NUMBERING_PROVIDERS_DIFFER` (422) until they agree.
+- **Changes that would print a number again** are refused with `NUMBERING_RESTART_WOULD_REPEAT`
+  (422), judged on the result whatever else the save changes; ask the platform operator:
+  - turning the yearly restart on (`yearReset`, or a year format on a series that has it) while the
+    series would then start again at 1 before the next fiscal year: it has issued numbers and has
+    not restarted this year;
+  - taking the year out (`yearFormat: 'none'`) of a series that counts under a yearly restart (it
+    holds a restart year, including one a set-up gave it), or a set-up that would take it out of
+    a store that does.
+- **Other refusals:**
+  - 400 `ValidationError`: `NUMBERING_SERIES_INVALID`; `NUMBERING_YEAR_FORMAT_INVALID` (a year
+    format other than `none`/`short`/`full`); `NUMBERING_DIGITS_INVALID` (3 to 8);
+    `NUMBERING_AFFIX_INVALID` (30 characters at most; no control, invisible-format or line
+    separator characters).
+  - 422 `BusinessRuleError`: `NUMBER_PREFIX_RESERVED` (a prefix starting with `TEST-`, a
+    sandbox's); `NUMBERING_YEAR_FORMAT_UNKNOWN` (setting up a series that restarts yearly over a
+    stored year format the engine does not know).
+  - 404: `ENTITY_NOT_FOUND`, a store with no legal entity.
+- **The store doors** (`updateInvoiceConfig`, `updateCreditNoteNumberingConfig`) refuse a format
+  change to a series a legal entity shares with other stores (`LEGAL_ENTITY_NUMBERING_SHARED`):
+  change it here.
+
+These methods need an engine with the legal-entity numbering API (multi-region phase 2, B6c).
+Against an older engine the request fails GraphQL validation (`GRAPHQL_VALIDATION_FAILED`).
+
+### Settings from an organization
+
+A member store takes each settings group its organization shares (`settings.returns`,
+`settings.branding`, … — `SETTINGS_GROUPS` lists them in catalog order) from the organization,
+unless it keeps its own. `admin.tenant.settingsSources` answers, for the **active** store, where
+each group comes from, and switches one group between the two:
+
+```ts
+const sources = await admin.tenant.settingsSources.list();
+// [{ group, source: 'channel' | 'organization', locked, overridden, inheritable, organizationName, values }, …]
+
+await admin.tenant.settingsSources.override('settings.returns');   // keep this store's own values
+await admin.tenant.settingsSources.inherit('settings.returns');    // back to the organization's
+```
+
+A settings page reads three states off an entry: **managed by the organization** (`locked` — the
+store cannot keep its own), **inherited** (`inheritable && !overridden`) and **overridden**
+(`inheritable && overridden`). Anything else is the store's own setting with no organization behind
+it. `values` holds the group's effective channel custom fields (`null` for `settings.email` and
+`settings.numbering_formats`, whose own reads already answer the effective values), and
+`organizationName` is `null` outside an organization. `group` and `source` are typed as the names
+this SDK knows but carry any string, so a group a newer engine adds reaches you unchanged.
+
+A group's `values` name its images by asset id (`logoAssetId`, `faviconAssetId`, …). While the
+store inherits the group those are its organization's assets, which the store's own library does not
+hold, so `catalog.assets.get(id)` answers `null` for them. `assets(group)` reads them from the channel
+the values come from:
+
+```ts
+const images = await admin.tenant.settingsSources.assets('settings.branding');
+// [{ id, name, type, mimeType, preview, source, … }] — only the assets the group's values name
+```
+
+It answers nothing for a group without images, needs the same permission as `list`, and refuses an
+unknown group with `ORGANIZATION_SETTINGS_GROUP_INVALID`.
+
+`override` starts the store from a copy of the organization's current values, so nothing changes for
+its customers until someone edits them; `inherit` leaves the store's own values stored but unused.
+Both answer the group's state afterwards and are safe to repeat. `list` needs any permission on the
+store; `override` and `inherit` need `UpdateChannel`, or `UpdateSettings` for `settings.email` and
+`settings.numbering_formats`. A SuperAdmin reads any store the same way, with that store as the
+tenant. Refusals: `MANAGED_BY_ORGANIZATION` (422 `BusinessRuleError` — the organization locked the
+group, SuperAdmins included), `ORGANIZATION_SETTINGS_NOT_A_MEMBER` (422 — the store is in no
+organization, or is a workspace), `ORGANIZATION_SETTINGS_GROUP_INVALID` (400 `ValidationError` — a
+group the engine does not know; a blank one is refused before sending). While a store inherits a
+group, `override` it before changing its values. A platform release that guards settings writes
+refuses a write to an inherited group with `ORGANIZATION_SETTINGS_INHERITED` (422); an engine
+without that guard accepts the write, but the group still resolves to the organization's values.
+
+Before an organization admin locks a group for every store, `settingsOverrides` names the stores that
+would lose their own values:
+
+```ts
+const workspace = human.withTenant({ scope: { kind: 'channel', code: 'org-acme-eu' } });
+const overrides = await workspace.platform.organizations.settingsOverrides(org.id);
+// [{ channelId, channelCode, group, overriddenAt: '2026-10-25T00:30:00.000Z' }, …]
+```
+
+It lists every member store keeping its own values, one entry per store and group, whether or not
+the organization shares that group today, ordered by store code. `overriddenAt` is ISO-8601 in UTC,
+exactly as the engine sends it: compare instants with `Date.parse` and format it in the viewer's
+time zone only for display. Callers and refusals are those of `members`: a SuperAdmin with no tenant,
+or the organization admin in its workspace; an unknown id is `ORGANIZATION_NOT_FOUND` (404).
+
+### Variant prices from an organization
+
+A variant an organization shares from its workspace (catalog sharing on) reaches each member store
+with the organization's prices copied in, and a store may change them. `priceSources` answers where
+each price of the **active** store comes from; `revertPrice` takes changed prices back to the
+organization's:
+
+```ts
+const sources = await admin.catalog.variants.priceSources(variantId);
+// [{ currencyCode: 'EUR', price: 2500, source: 'OWN', organizationPrice: 2099, organizationName: 'Acme Europe' },
+//  { currencyCode: 'USD', price: 2508, source: 'CONVERTED', organizationPrice: null, organizationName: 'Acme Europe' }]
+
+await admin.catalog.variants.revertPrice([variantId]);                             // every currency
+await admin.catalog.variants.revertPrice([variantId], { currencyCodes: ['EUR'] }); // EUR only
+```
+
+One entry per currency the store sells, in the store's currency order:
+
+- **`OWN`** — the store's own price: on a variant of its own, or its change of the organization's
+  price, in which case `organizationPrice` shows the price it replaces.
+- **`INHERITED`** — the organization's price, unchanged since it was copied. It follows the
+  organization's later changes.
+- **`CONVERTED`** — nothing stored: the storefront converts the store's EUR price at the store's
+  exchange rate, and `price` is what that answers now. Null when there is no EUR price or rate, or
+  the store marked the currency not for sale for the variant.
+
+`price` and `organizationPrice` are minor units on the **store's** basis — gross on a store with
+`pricesIncludeTax`, net otherwise, the basis a variant write takes. That is not
+`ProductVariant.price`, which reads net everywhere. An organization and its stores enter prices the
+same way, so the two compare directly. A store outside any organization, and a variant of the
+store's own, read `OWN` or `CONVERTED` only, with `organizationPrice` and `organizationName` null.
+`source` is typed as the three names but carries any string, so a source a newer engine adds
+reaches you unchanged. An id the store does not have is `VARIANT_NOT_FOUND` (404 `NotFoundError`).
+
+`revertPrice` makes the prices `INHERITED` again: the organization's stored price, followed from then
+on until the store changes it again (`variants.update`). Without `currencyCodes` it takes every
+currency the store sells and the organization prices, except a currency the store marked not for
+sale for the variant and stores no price in (a stored price sells the currency whatever its mark,
+so it is reverted); an empty list reverts nothing. It is all or nothing, writes one audit row per
+variant (`product_variant.price.revert`, each currency's price before and after) and answers the
+variants as the store sees them. At most `MAX_REVERT_PRICE_VARIANTS` (500) distinct variants per
+call; more is refused before sending. `priceSources` needs `ReadCatalog`; `revertPrice` needs
+`UpdateCatalog` or `UpdateProduct`, what a variant price write needs. Refusals, none of which writes
+anything: `ORGANIZATION_PRICE_LOCAL_VARIANT` (422 `BusinessRuleError` — a variant of the store's
+own, or the organization does not share its catalog), `ORGANIZATION_PRICE_MISSING` (422 — the
+organization stores no price in a currency named, or in any the store sells),
+`ORGANIZATION_PRICE_NOT_REVERTIBLE` (422 — a named currency the store does not sell, or marked not
+for sale for the variant with no price stored in it), `ORGANIZATION_WORKSPACE_NOT_A_STORE` (422 — called in the workspace,
+whose prices are the organization's own), `ORGANIZATION_PRICE_REVERT_INVALID` (400
+`ValidationError` — more than 500 variants) and `ENTITY_NOT_FOUND` (404 — an id the store does not
+have).
+
+### Catalogue from an organization
+
+An organization keeps catalogue rows in its workspace, and its member stores hold them too, kind by
+kind: products, variants, option groups, facets and assets while it shares `catalog`, collections
+while it shares `collections`, customer groups while it shares `customer_groups`. Members also read
+the workspace's property groups on the products they hold. Every catalogue read says whose row it
+is, as the **active** store sees it:
+
+```ts
+const product = await admin.catalog.products.get(productId);
+product.catalogueOwnership;
+// { state: 'SHARED', organizationName: 'Acme Europe', editableHere: false }
+```
+
+- **`LOCAL`** — the store's own row (or, in the workspace, one no member store holds yet).
+  `organizationName` is null.
+- **`SHARED`** — in a member store, a row of its organization's workspace; in the workspace, a row at
+  least one member store holds. `organizationName` names the organization.
+
+`editableHere` says whether the caller may change the row from the active store: it holds the update
+permission there and on every other store holding the row, and the row is not a workspace row read
+from a member store. Show the form read-only while it is false; the engine refuses the write anyway.
+Property groups carry `editableHere` alone, and it means less there: only whether the group is the
+active store's own, whatever the caller's permissions. `catalog.properties.values.get` of a product the store
+holds from its organization answers the workspace's groups and values beside the store's own, with
+`editableHere` false, and a `values.set` changing one of those values is refused whole with
+`MANAGED_BY_ORGANIZATION` (one echoing them unchanged is accepted). `catalog.properties.groups.list`
+answers the store's own groups only. Changing a workspace group or property from the store
+(`properties.groups.update`, `create` in it, `update`, `reorder`, `groups.reorder`, a delete) is
+refused `MANAGED_BY_ORGANIZATION` too. Any other id the store does not own is
+`PROPERTY_GROUP_NOT_FOUND` or `PROPERTY_NOT_FOUND` (404) for `groups.update`, `create`, `update`,
+`reorder` and `groups.reorder` (which moves nothing then), and a delete of one is the
+`ConflictError` `PROPERTY_GROUP_NOT_DELETED` / `PROPERTY_NOT_DELETED`.
+
+A member store's write to a workspace product, variant, collection, facet, asset or option group, or
+one that reaches such a row through a product, a parent collection or an option group, is refused with `MANAGED_BY_ORGANIZATION` (`BusinessRuleError`, 422) for
+everyone, SuperAdmin included, and the message says what to do instead (edit it in the workspace,
+copy the product, create a facet of the store's own, …). Make the change in the workspace:
+
+```ts
+const workspace = admin.withTenant({ scope: { kind: 'channel', code: 'org-acme-eu' } });
+await workspace.catalog.products.update({ id: productId, enabled: false });
+```
+
+What the store adds to a shared row stays its own: its prices (see
+[Variant prices from an organization](#variant-prices-from-an-organization)), its stock at its own
+locations, its own facet values on the product and its own collections under a workspace collection.
+`customers.groups.byExternalKey`, `upsertByExternalKey` and `replaceMembers` answer `catalogueOwnership` too, and
+renaming a workspace group from a member store is refused the same way. A customer group's badge
+reads it by id:
+
+```ts
+const group = await admin.customers.groups.get(groupId);
+// { id, createdAt, updatedAt, name, externalKey, catalogueOwnership }, or null
+```
+
+`groups.get` needs `ReadCustomer` or `ReadCustomerGroup`. It answers `null` for a group the active
+store does not hold (another store's, a deleted one, an unknown id), like every other entity `get`;
+show that as "not found", never as the store's own group. An id that is not a uuid is refused before
+that with core's `ENTITY_NOT_FOUND`, a `NotFoundError`: branch on the class, not the code. `state` is typed as the two
+names but carries any string, so a state a newer engine adds reaches you unchanged. Every product,
+collection, facet, asset and option group read and write answer selects `catalogueOwnership`, as do
+the external-key customer group answers, and every property group answer (`properties.groups.*`,
+`properties.values.get`) selects `editableHere`, so this release needs a platform release that
+serves both; against an older engine those calls fail as a whole and write nothing. `tenant.settingsSources.assets` answers
+`AssetFile` (an `Asset` without `catalogueOwnership`) and keeps working there.
+
+### Which stores offer an organization's products
+
+A member store sells the workspace products it holds. Two switches take one out of a store without
+touching the others: the store **excludes** it itself, or the organization sets its **availability**
+per store from the workspace.
+
+```ts
+// In the member store: off its storefront and out of its carts; its orders keep it.
+const [lamp] = await admin.catalog.products.exclude([productId]);
+lamp.excludedFromStore; // true
+await admin.catalog.products.include([productId]); // offered again
+
+// In the organization's workspace: on or off in member stores, by their channel ids.
+const workspace = admin.withTenant({ scope: { kind: 'channel', code: 'org-acme-eu' } });
+const changes = await workspace.catalog.products.setAvailabilityInStores({
+  productIds: [productId],
+  channelIds: [nlStoreId, deStoreId],
+  available: false,
+});
+// [{ productId, channelId: nlStoreId, action: 'excluded' }, …]
+
+// …and read where each product stands in each store, for a list column or before a toggle.
+const rows = await workspace.catalog.products.availabilityInStores({
+  productIds: [productId, otherProductId],
+  channelIds: [nlStoreId, deStoreId],
+});
+// [{ productId, channelId: nlStoreId, state: 'excluded', localCopyId: null }, …]
+```
+
+`exclude` and `include` act on the **active** store only. An excluded product leaves its storefront
+and cannot be added to its carts, while its orders, returns and invoices keep it, and every product
+read answers `excludedFromStore: true` there (always false for the store's own products and in a
+workspace). Excluding an excluded product, or including one that is not excluded, changes nothing.
+Both are all or nothing, audited, take at most `MAX_STORE_EXCLUSION_PRODUCTS` (500) distinct ids per
+call (more is refused before sending), answer the products as the store sees them, and need
+`UpdateCatalog` or `UpdateProduct`. Refusals: `STORE_EXCLUSION_LOCAL_PRODUCT` (`BusinessRuleError`,
+422 — `exclude` of the store's own product, which it disables or deletes instead),
+`STORE_EXCLUSION_INPUT_INVALID` (`ValidationError`, 400 — too many ids),
+`ORGANIZATION_WORKSPACE_NOT_A_STORE` (422 — called in a workspace, which sells nothing) and
+`ENTITY_NOT_FOUND` (404 — a product the store does not hold, or for `include` neither holds nor
+excludes).
+
+`setAvailabilityInStores` is the organization's Availability toggle, called with its workspace as
+the tenant by an organization admin (`ManageOrganization`) or a SuperAdmin, who also needs
+`UpdateCatalog` in each store named. Off, under the `all` assortment, the product is **excluded** from the store, as
+above. Off, under `selected`, it is **unlinked** from a store that never sold or quoted it, and
+excluded from one that did. On, it is **included** again, or **assigned** to a store that does not
+hold it, its images and variants following within moments. It answers only what changed, sorted by
+store and product; `action` is typed as those four names but carries any string. All or nothing and
+audited, for 1 to `MAX_AVAILABILITY_PRODUCTS` (100) products and 1 to `MAX_AVAILABILITY_STORES`
+(50) stores per call. Refusals: `ORGANIZATION_AVAILABILITY_INPUT_INVALID` (`ValidationError`, 400 —
+no products or stores, too many, or `available` not a boolean; refused before sending too),
+`ORGANIZATION_ACCESS_DENIED` (`PermissionDeniedError`, 403 — the tenant is not a workspace),
+`CHANNEL_ACCESS_DENIED` (403 — a store whose catalogue the caller may not change),
+`ORGANIZATION_CATALOG_NOT_SHARED` (`BusinessRuleError`, 422 — `catalog` sharing is off),
+`ORGANIZATION_PRICE_MISSING` (422 — a store would be offered a variant it has no price for) and
+`ENTITY_NOT_FOUND` (404 — a product that is not the workspace's, or a store that is not a member).
+
+`availabilityInStores` is the toggle's read, behind the same door: called with the workspace as the
+tenant by an organization admin or a SuperAdmin, who also needs `ReadCatalog`, `ReadProduct` or
+`UpdateCatalog` in each store named. It answers one row per product and store, products first, in
+the order named (each distinct id once): `state` is `offered` (the store holds the product and does
+not exclude it; the product's state, not a promise that a variant is buyable there), `excluded`
+(kept for its orders, off its storefront and carts; also a product excluded ahead of the
+organization's fan-out under `all`, not held yet) or `not-held`, typed as those three but carrying
+any string, and `localCopyId` names the store's own local copy of the product, if it has
+one. It answers whether or not the organization shares its products, for 1 to
+`MAX_AVAILABILITY_PRODUCTS` (100) products and 1 to `MAX_AVAILABILITY_STORES` (50) stores per call:
+page a longer list of stores in calls of 50. Refusals: `ORGANIZATION_AVAILABILITY_INPUT_INVALID`
+(400, also before sending), `ORGANIZATION_ACCESS_DENIED` (403), `CHANNEL_ACCESS_DENIED` (403 — a
+store whose catalogue the caller may not read) and `ENTITY_NOT_FOUND` (404). A platform release
+older than this method does not have the query: the request fails GraphQL validation
+(`GRAPHQL_VALIDATION_FAILED`, also a 400 `ValidationError`, told apart by its code).
+
+`excludedFromStore` is selected on every product answer, so this release needs a platform release
+that serves it, as it needs `catalogueOwnership`.
+
+### A store's own copy of an organization's product
+
+A member store that wants to change a product its organization shares makes a **local copy**: its
+own product, replacing the shared one in that store.
+
+```ts
+const { product, original, droppedOrganizationPropertyCount } =
+  await admin.catalog.products.makeLocalCopy(sharedProductId);
+// product: the store's own copy, DISABLED; original: 'excluded' | 'unlinked'
+
+// Choose some SKUs; the rest end in -<store code> (first free).
+await admin.catalog.products.makeLocalCopy(sharedProductId, {
+  skus: [{ productVariantId, sku: 'TEE-NL-M' }],
+});
+```
+
+The copy is a `clone` created disabled, so review it and enable it with `products.update`. It takes
+the store's current prices in every currency (inherited or its own), its not-for-sale marks and
+its price-list entries, and joins only the store's own collections. Its `catalogueOwnership` reads
+`LOCAL`: its product and variant rows, names, prices and properties are the store's own and no
+longer follow the workspace. The workspace's option groups, assets and facet values it still uses
+do follow it (a workspace rename of an option shows on the copy), and stay the workspace's to
+change (`MANAGED_BY_ORGANIZATION` from the store). The organization's property values are
+not copied; `droppedOrganizationPropertyCount` says how many there were, so a form can warn before
+the copy is enabled. The shared product leaves the store in the same transaction: `excluded`
+(`excludedFromStore`) when the store sold or quoted it, and always under the organization's `all`
+assortment, otherwise `unlinked`; `original` says which, typed as the two names but carrying any
+string.
+
+A store keeps at most one live copy of a product: a repeat (a double submit, a retry) is refused,
+never a second copy, with `LOCAL_COPY_ALREADY_EXISTS`, whether the first call excluded or unlinked
+the original. (A platform release older than that answers `ENTITY_NOT_FOUND` after an unlink, the
+store no longer holding the product: there, look for the copy before treating a 404 as a bad id.) Needs `CreateCatalog` (or `CreateProduct`) and `UpdateCatalog` in the store.
+Refusals, none of which writes anything: `LOCAL_COPY_PRODUCT_NOT_SHARED` (`BusinessRuleError`, 422
+— the store's own product; `clone` it instead), `LOCAL_COPY_ALREADY_EXISTS` (`ConflictError`, 409),
+`LOCAL_COPY_SKU_CONFLICT` (409 — a SKU you named is another product's in the store; `error.details`
+names each, its `field` the SKU's place in `skus`, `/skus/<index>/sku`), `LOCAL_COPY_INPUT_INVALID` (`ValidationError`, 400 — `skus` names a variant the store
+does not hold on the product, names one twice, repeats a SKU, or has a blank or overlong one),
+`ORGANIZATION_WORKSPACE_NOT_A_STORE` (422 — called in the workspace) and `ENTITY_NOT_FOUND` (404).
+Requires a platform release that serves `makeLocalCopy`.
+
 ### Errors
 
 One hierarchy, all re-exported from this package so you need no direct dependency on