@sixtyninecommerce/admin 0.11.0 → 0.12.0

package/README.md

@@ -498,6 +498,53 @@ or API key owns the store's Stock.
 `stock.allocations.release(orderId)` hands back everything a stuck, unfulfilled order has reserved
 without changing its state.
 
+What one location holds, and what moved there, a page at a time:
+
+```ts
+const here = await admin.stock.levelsAt(locationId, { search: 'rioja', limit: 25 }); // most on hand first
+here.items[0]; // { variantId, sku, variantName, product: { id, name, featuredAsset }, onHand, allocated, updatedAt }
+for await (const movement of await admin.stock.movementsAt(locationId)) {
+  console.log(movement.type, movement.quantity, movement.sku, movement.order?.code); // newest first
+}
+```
+
+`sort: 'ASC'` lists the fewest on hand first; the engine answers at most 200 levels a page. Both
+need `ReadStockLocation`, and the location must be the store's own: another store's is refused
+`LOCATION_NOT_IN_CHANNEL`, never read. A location several stores share lists only this store's
+variants; there, a variant more than one of them sells also carries the other stores' order
+movements, and the engine fails that ledger page as a whole (`GRAPHQL_ERROR`) rather than leave
+the row out.
+
+### Stock settings
+
+`stock.settings` is the store's stock settings as the engine reads them: whether the storefront
+sees operational stock numbers, which warehouses back the storefront, and the backorder default,
+beside the store's own tracking and threshold and the platform defaults.
+
+```ts
+const settings = await admin.stock.settings.get();
+// { channelId, trackInventory: true, outOfStockThreshold: 0,
+//   defaultTrackInventory: true, defaultOutOfStockThreshold: 0, exposeStockToStorefront: false,
+//   storefrontStockLocations: { mode: 'ALL', locationIds: [], reason: null }, backorderPolicy: 'deny' }
+
+// How a change WOULD read. Writes nothing.
+await admin.stock.settings.preview({ storefrontStockLocationIds: [warehouseId] });
+
+// Only the named fields are written; [] clears the warehouse selection (every warehouse).
+await admin.stock.settings.set({ storefrontStockLocationIds: [warehouseId], backorderPolicy: 'incoming' });
+```
+
+`storefrontStockLocations.mode` is `ALL` (every warehouse), `SUBSET` (only `locationIds`) or
+`MALFORMED`: the stored value cannot be read, the engine sells from every warehouse and logs it,
+and `reason` says why; saving a selection replaces it. The engine's stock maths read a variant's
+own tracking and threshold, else the platform defaults (`defaultTrackInventory`,
+`defaultOutOfStockThreshold`), never the store's `trackInventory` / `outOfStockThreshold`.
+
+Reading needs any administrator permission on the store; `set` needs `UpdateChannel`. Refusals,
+from `preview` and from `set` before anything is written: `CHANNEL_SETTINGS_INVALID`
+(`ValidationError`, `details[]` per field) for a `null` tracking, threshold, flag or policy, a
+policy that is not `deny`, `incoming` or `unlimited`, a blank warehouse id or more than 500.
+
 ### Stock locations
 
 `stock.locations` is the store's stock locations themselves; a location's profile (code, time zone,
@@ -652,6 +699,33 @@ const after = await admin.stock.transfers.cancellation(transferId);
 is its own request and `get` / `list` / `cancel` select none of its fields, so a caller ahead of
 the engine sees only `cancellation` refused.
 
+### Stock transfer shipment, note and numbering
+
+```ts
+// A wrong handler or carrier: back to an editable draft, the units back on the source.
+const draft = await admin.stock.transfers.removeShipment(transferId);
+// A Hendriks export that did not land at ship time (hendriksRemotePath still null).
+const exported = await admin.stock.transfers.retryHendriksExport(transferId);
+// The transfer note (a consumption's: its consumption note) again.
+const noted = await admin.stock.transfers.regeneratePdf(transferId); // noted.pdfStorageKey
+
+const format = await admin.stock.transfers.numbering.get(); // { prefix, suffix, digits, yearFormat, yearReset }
+await admin.stock.transfers.numbering.set({ prefix: 'TR-', digits: 5 }); // a patch
+```
+
+`removeShipment` undoes `ship`: it voids every MyParcel parcel inside the call (allowed up to
+120 s; a `REQUEST_TIMEOUT` does not mean it failed) and clears the handler, carrier, tracking code,
+ETA, parcels and note, keeping the delivery address for the re-ship. It does NOT withdraw a Hendriks
+export or any other 3PL's shipment: retract that at the 3PL. It is refused for a transfer not in
+transit, so a repeat restores nothing twice, and once any unit was received or lost (close or
+cancel instead). `retryHendriksExport` uploads the export once: a transfer already exported, not
+shipped with Hendriks, or not in transit is refused, and so is a store without Hendriks set up
+(that one with no code yet: it arrives as a `GRAPHQL_ERROR`, and nothing is uploaded).
+`regeneratePdf` is refused for a draft. The numbering `get` answers the format the store's next
+code takes (its organization's while it inherits `settings.numbering_formats`; the counter is
+always the store's own); `set` writes the store's own row and answers it, so read `get` again
+for the format in use. An unknown `yearFormat` is refused `NUMBERING_YEAR_FORMAT_INVALID`.
+
 ### Parcel count suggestion
 
 ```ts
@@ -779,6 +853,36 @@ buyer's name, email and addresses. A credential below `customerData: full` gets
 `redacted: true`. An unsaved `style` value `set` would refuse is drawn with the renderer's fallback,
 not refused.
 
+### Email templates
+
+```ts
+const { templateTypes, blockTypes } = await admin.tenant.emailTemplates.catalog();
+const t = await admin.tenant.emailTemplates.getByType('order_confirmation'); // or null
+await admin.tenant.emailTemplates.setSubject('order_confirmation', 'nl', [
+  { type: 'text', value: 'Bestelling ' },
+  { type: 'var', key: 'order_code' },                             // a variable of the type
+]);
+const b = await admin.tenant.emailTemplates.blocks.add('order_confirmation', { type: 'heading' });
+await admin.tenant.emailTemplates.blocks.setContent(b.id, 'nl', { text: [{ type: 'text', value: 'Bedankt' }] });
+await admin.tenant.emailTemplates.blocks.update(b.id, { config: { ...b.config, level: 3 } });
+await admin.tenant.emailTemplates.blocks.reorder('order_confirmation', [b.id, ...t!.blocks.map((x) => x.id)]);
+await admin.tenant.emailTemplates.blocks.remove(b.id);                // its texts go with it
+```
+
+A template's body is a list of blocks (the engine's "chips"): each has a `config` shared by every
+language and one `content` per language. `setSubject`, `blocks.add` and `blocks.reorder` address the
+template by TYPE and look it up first (two requests), for the reason `preview` does; the block
+methods go by block id. `blocks.add` puts a block at the end unless given a `position`.
+`blocks.reorder` takes EVERY block of the template once (`EMAIL_CHIP_ORDER_INVALID` names the one
+left out, repeated or foreign); `blocks.update` replaces the whole `config`. A subject part is text
+with its `value` or a variable with its `key` (`EMAIL_SUBJECT_INVALID`), a config or content must be
+a JSON object (`EMAIL_CHIP_CONFIG_INVALID`, `EMAIL_CHIP_CONTENT_INVALID`), and a language code must
+be one (`EMAIL_LANGUAGE_CODE_INVALID`); all `ValidationError`, 400. A block or template the store
+does not hold is `ENTITY_NOT_FOUND`, an unknown type `EMAIL_TEMPLATE_NOT_FOUND` (`NotFoundError`).
+While the store takes `settings.email` from its organization every write is refused
+(`ORGANIZATION_SETTINGS_INHERITED` / `MANAGED_BY_ORGANIZATION`, 422). Reads need `ReadSettings`,
+writes `UpdateSettings`; `blocks.remove` is `@effect destructive`.
+
 ### Shipping methods
 
 ```ts
@@ -812,6 +916,40 @@ withdraws it from every one (orders already placed keep their shipping line). Bo
 of those stores. `create` refuses `ORGANIZATION_WORKSPACE_NOT_A_STORE` (`BusinessRuleError`) in an
 organization's workspace, and `create` / `update` refuse `PLUGIN_ACCESS_DENIED`
 (`PermissionDeniedError`) for a handler, checker or calculator of a plugin the store does not hold.
+A `weight-zone-shipping-calculator` must name one of the store's rate tables (below) in its
+`shippingZoneConfigId`, or `create` / `update` refuse `SHIPPING_ZONE_CONFIG_NOT_FOUND`
+(`NotFoundError`) with `details[0].field` on the argument (`/input/calculator/arguments/<i>/value`):
+empty or left out (`required`), or not one of the store's table ids (`enum`, another store's included).
+An `update` that sends no calculator is not judged.
+
+### Ship-to countries
+
+`shipping.shipToCountries` is the list of countries the store ships to, as checkout applies it:
+the storefront offers only these (`availableCountries`), and an order addressed anywhere else
+cannot be placed.
+
+```ts
+const view = await admin.shipping.shipToCountries.get();
+// { gate: 'SUBSET', reason: null, selected: ['NL', 'TR'], served: ['NL'], unservable: ['TR'],
+//   options: [{ code: 'NL', name: 'Netherlands', enabled: true }, …, { code: 'TR', name: 'TR', enabled: false }] }
+
+// How a list WOULD read. Writes nothing.
+await admin.shipping.shipToCountries.preview(['NL', 'BE']);
+
+// Codes are trimmed, upper-cased and de-duplicated; [] means every enabled country.
+await admin.shipping.shipToCountries.set(['nl', 'BE']);
+```
+
+`gate` is `ALL` (no list: every enabled country), `SUBSET` (only `selected`) or `MALFORMED`: the
+stored value cannot be read, checkout offers every enabled country and logs it, and `reason` says
+why; saving a list replaces it. An empty list never means "ships nowhere". `served` is exactly
+what the storefront offers. `unservable` lists selected codes that are not enabled countries: they
+are stored, but no shopper can choose them until a platform administrator enables the country.
+
+Reading needs any administrator permission on the store; `set` needs `UpdateChannel`. `preview`
+and `set` refuse `SHIP_TO_COUNTRIES_INVALID` (`ValidationError`, one `details[]` entry per
+offending entry, `field` = `countryCodes.<index>`) for an entry that is not a two-letter ISO-3166
+code, or for more than 300 entries; `set` writes nothing then.
 
 ### Weight-zone rate tables
 
@@ -838,6 +976,30 @@ with the table, named in the message) and `ENTITY_NOT_FOUND`. A delete the engin
 `NOT_DELETED` (the store has no such table) is `SHIPPING_ZONE_CONFIG_NOT_DELETED`
 (`ConflictError`). Reads need `ReadSettings`, writes `UpdateSettings`.
 
+```ts
+const zones = admin.shipping.rateTables.zones;
+const z = await zones.create(t.id, { name: 'Randstad', type: 'domestic' }); // after the last zone
+await zones.setMembers(z.id, [{ postalCodeFrom: '1000', postalCodeTo: '1099' }]);
+await zones.setRates(z.id, [
+  { minWeightGrams: 0, maxWeightGrams: 5000, price: 695, currencyCode: 'EUR' },    // €6.95
+  { minWeightGrams: 0, maxWeightGrams: 5000, price: 120000, currencyCode: 'JPY' }, // ¥1,200
+]);
+await zones.update(z.id, { name: 'Holland' });                 // a patch
+await zones.reorder(t.id, [eu.id, z.id]);                      // every zone of the table, once
+await zones.delete(z.id);
+```
+
+A zone matches by `type`: `domestic` by its members' postal-code prefix ranges, `international`
+by country; zones are tried in position order and the first match prices the order. A rate price
+is in hundredths of its currency for EVERY currency, as the platform stores all money (¥1,200 is
+`120000`). `setMembers` and `setRates` replace the zone's whole set in one transaction: a refused
+save keeps the previous one. Refusals: `SHIPPING_ZONE_INPUT_INVALID` with one detail per problem
+(`/rates/1/maxWeightGrams` `overlap`, `/members/0/countryCode` `not`, `/zoneIds` `required` for a
+reorder that leaves a zone out), `SHIPPING_ZONE_POSITION_TAKEN` (`ConflictError`),
+`SHIPPING_ZONE_IN_USE` (`BusinessRuleError`: the last zone of a table a method prices with) and
+`ENTITY_NOT_FOUND`; a zone delete answered `NOT_DELETED` is `SHIPPING_ZONE_NOT_DELETED`
+(`ConflictError`). `setRates` is `@effect money`: it changes what customers pay for shipping.
+
 ### Parcel rule
 
 ```ts
@@ -946,6 +1108,87 @@ await admin.shipping.myparcel.senders.set({ stockLocationId, address, isDefault:
   `ReadStockLocation` and `senders.set` `UpdateStockLocation`. Another store is configured with
   `admin.withTenant(...)`, as above.
 
+### MyParcel shipments and labels
+
+```ts
+await admin.shipping.myparcel.shipments.get(shipmentId);
+// { id, referenceIdentifier, barcode, status, carrierId, created, modified, linkConsumerPortal },
+// read live from MyParcel; null when MyParcel no longer holds a shipment the store records
+
+await admin.shipping.myparcel.labels.status([shipmentId], 'A6'); // { status: 'pending' | 'ready' }
+const label = await admin.shipping.myparcel.labels.download(shipmentId, 'A4');
+// { format, contentType: 'application/pdf', filename, bytes: Uint8Array }
+await admin.shipping.myparcel.labels.request({ fulfillmentId, shipmentId, format: 'A4' });
+// { status: 'pending' }: queued, the label lands when the job has run
+```
+
+- **Asking for a label buys it.** MyParcel registers a shipment it still holds as a concept on the
+  first call that asks for its label (any of the three `labels` methods) and bills the store for
+  it; a registered label cannot be deleted through MyParcel's API. All three are tagged
+  `@effect money`. None takes an idempotency key: a repeated `request` queues another request for
+  the same parcel.
+- **Only the store's own shipments.** A shipment no fulfillment or stock transfer of the store
+  holds (another store's on a shared MyParcel account, a missing id) is `ENTITY_NOT_FOUND`
+  (`NotFoundError`), refused before MyParcel is asked. A store whose MyParcel set-up was removed
+  after booking is refused `MYPARCEL_NOT_CONFIGURED_ERROR` (`BusinessRuleError`, 422) by
+  `shipments.get`, `labels.status` and `labels.download` (an older engine failed it uncoded,
+  `GRAPHQL_ERROR` 500).
+- **`status` is a readiness signal, never a link**: a link MyParcel mints expires within hours.
+  Give someone the label with `download` (one shipment) or `admin.fulfillments.myparcelLabel`
+  (every parcel of a fulfillment merged into one PDF). `status` and `download` are allowed up to
+  55s (`MYPARCEL_LABEL_TIMEOUT_MS`): the engine retries a slow MyParcel past the default timeout.
+  Poll `status` with a back-off; each call is a request to MyParcel.
+- **`request` refusals**, with nothing queued: `MYPARCEL_NOT_CONFIGURED_ERROR` (no set-up, or
+  MyParcel switched off), `ENTITY_NOT_FOUND` (`NotFoundError`: another store's or a missing
+  fulfillment), `MYPARCEL_VALIDATION_ERROR` with `details[].field` (a cancelled fulfillment, or a
+  shipment it does not hold), `MYPARCEL_DECRYPTION_FAILED_ERROR`. A blank id, a shipment id that
+  is not a positive integer or a format other than `A4`/`A6` is refused before any request
+  (`MYPARCEL_LABEL_INPUT_INVALID`, `ValidationError`) by every `labels` method.
+- **Permissions:** `shipments.get`, `labels.status` and `labels.download` need `ReadOrder`;
+  `labels.request` `UpdateOrder`. A store without the MyParcel plugin is refused
+  `PLUGIN_ACCESS_DENIED` on the `labels` methods, and on `shipments.get` for any shipment none of
+  its fulfillments holds (never for a SuperAdmin).
+
+### MyParcel shipment form, repairs and return labels
+
+```ts
+await admin.shipping.myparcel.carrierCapabilities();
+// [{ carrierId, name, packageTypes, deliveryTypes, countries, supportedOptions, supportsPickup, constraints }]
+await admin.shipping.myparcel.deliveryOptions({ postalCode: '1012 LG', countryCode: 'NL', carrierId: 1 });
+// { deliveryOptions: [{ deliveryType, date, startTime, endTime, price: { amount, currency } | null }],
+//   pickupOptions: [{ locationCode, locationName, street, number, …, carrierId, distance }] }
+
+await admin.shipping.myparcel.shipments.recreate({ fulfillmentId, handlerArguments: [{ name: 'carrier', value: '1' }] });
+await admin.shipping.myparcel.shipments.import({ fulfillmentId, shipmentId: 4812345 });
+// both: { shipmentId, labelFormat }
+await admin.shipping.myparcel.returns.create({ parentShipmentId, carrier: 1, name, email });
+// { shipmentId }
+```
+
+- **Reads.** `carrierCapabilities` is the engine's static carrier table (no MyParcel call,
+  `ReadSettings`). `deliveryOptions` asks MyParcel live with the store's key (`ReadOrder`): a quote,
+  in minor units, nothing booked. A blank postal code is refused before any request
+  (`INVALID_INPUT`); a store with no set-up is `MYPARCEL_NOT_CONFIGURED_ERROR`.
+- **The three writes bill the store at MyParcel** and are tagged `@effect money`: `recreate` books
+  new shipments (and the label job registers them), `import` asks for the imported shipment's label,
+  and `returns.create` makes a return shipment MyParcel e-mails to the customer. None takes an
+  idempotency key: a repeated `returns.create` makes another return; a repeated `import` is refused
+  (the fulfillment then holds a shipment); a repeated `recreate` books again while the first set is
+  still a concept, and is refused once MyParcel has registered it.
+- **Refusals name their fields.** Every union member that carries a field list
+  (`MyparcelInvalidRecipientError.missingFields`, `MyparcelInvalidSenderError.fields`,
+  `MyparcelPickupLocationInvalidError.fields`, `MyparcelValidationError.errors`) lands in
+  `details[]`, one `{ field, code, message }` per field, so a form can mark each: a recipient
+  without a house number is `MYPARCEL_INVALID_RECIPIENT_ERROR` with `details[0].field:
+  'streetLine1'`. `MYPARCEL_SHIPMENT_ALREADY_ATTACHED_ERROR` is an import of a shipment another
+  fulfillment or transfer holds. `recreate` and `import` onto a fulfillment that does not ship
+  with MyParcel (a manual one) are `MYPARCEL_VALIDATION_ERROR` with `details[0].field:
+  'fulfillmentId'`, and `returns.create` while MyParcel is switched off is
+  `MYPARCEL_NOT_CONFIGURED_ERROR`, both before MyParcel is asked. Another store's fulfillment or
+  shipment is `ENTITY_NOT_FOUND`, before MyParcel is asked. Malformed ids, arguments or a blank name/e-mail are refused before any
+  request (`INVALID_INPUT`, the field in `details[]`).
+- **Permissions:** `recreate`, `import` and `returns.create` need `UpdateOrder`.
+
 ### Fulfillment profiles
 
 ```ts
@@ -1088,7 +1331,7 @@ write is never deduplicated.
 
 | Write | Deduplicated? |
 |---|---|
-| `content.forms.upsertBySlug` | yes — the CMS replays the first response for the same key |
+| `content.forms.create`, `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.*`, `pickups.*`, `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 |
@@ -1340,6 +1583,39 @@ that entry holds the whole order — every line, nothing of it in a fulfillment
 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.
 
+### Moving a fulfillment, and the 3PL label hand-off
+
+```ts
+await admin.fulfillments.transition(fulfillmentId, 'Shipped');
+// { id, state: 'Shipped', nextStates: ['Delivered', 'Cancelled'] }
+await admin.fulfillments.resendLabelHandoff(fulfillmentId);
+// 'QUEUED' | 'NOT_READY' | 'DISABLED' | 'NO_RECIPIENT' | 'UNAVAILABLE'
+```
+
+`transition` moves a fulfillment through the store's own fulfillment process (the order page's
+"Mark as Shipped/Delivered"), so the order's state and whatever the store does on a shipped or
+delivered fulfillment follow: the customer's shipped e-mail, and, when the order's last lines
+ship on a store with Exact Online's "fulfilled" auto-push, the order's push to the ERP. A move
+into `Cancelled` is a cancel: the fulfillment's delivery charge comes off what its orders bill,
+and it is refused while the customer PAID that charge (`FULFILLMENT_CANCEL_OVERPAYMENT_CHOICE_REQUIRED`):
+`cancel` (below) takes the choice of how the money goes back. Tagged `@effect money` for that
+strongest move.
+
+A refused move answers the refusing step's OWN code, which core carries only as a `[CODE]` prefix
+on its text, with the text after it as the message: `ORDER_NOT_COVERED` (an order not paid in
+full on a store that requires it; `coverage` and `allowUncovered` above), `ORDER_ON_HOLD`,
+`BOOKING_REQUIRED`, … — classed as the warehouse API classes the same code. Any other refusal is
+`FULFILLMENT_STATE_TRANSITION_ERROR` (`BusinessRuleError`) in the step's words. Both carry the
+move on `error.extensions` (`fromState`, `toState`, `transitionError`, `errorCode`). Another
+store's fulfillment is `NotFoundError`; a blank id or state is `FULFILLMENT_TRANSITION_INVALID`
+before any request. No idempotency key: a repeated move that went through is refused as an edge
+the process no longer has.
+
+`resendLabelHandoff` e-mails the fulfillment's ready MyParcel label to the store's 3PL recipient
+again (`@effect irreversible`). Only `QUEUED` sent anything; the other outcomes say why not (no
+ready label, the notification switched off or without a recipient, no e-mail delivery). A repeat
+sends it again.
+
 ### Cancelling a fulfillment whose delivery charge was paid
 
 Cancelling a fulfillment takes its delivery charge off every order it charged. Where the customer
@@ -1675,6 +1951,38 @@ server picks them itself.
 Reading needs `ReadTaxCategory`, `ReadTaxRate`, `ReadCountry` and `ReadZone`, which every store
 role holds.
 
+### Price display: who sees prices with or without tax
+
+A store's price-display policy decides, per shopper, whether prices are shown incl. or excl. tax:
+a customer shipping to a listed country sees excl. tax (and is TAXED by that country's zone: the
+list changes what customers are charged), then B2B and trade customers follow `b2b` unless it is
+`inherit`, then everyone follows `default` unless it is `channel` (the store's "prices include
+tax"). The engine answers who sees what; the same rule decides the storefront's prices and the
+prices an order's emails, receipts and invoices show its customer.
+
+```ts
+const view = await admin.tax.displayPolicy.get();
+// { default: 'channel', b2b: 'net', countries: ['US'], pricesIncludeTax: true,
+//   audiences: [{ audience: 'VISITOR', mode: 'GROSS', countryCode: null, dependsOnStore: false }, …] }
+
+// Before saving: who a change WOULD show what. Writes nothing.
+const draft = await admin.tax.displayPolicy.preview({ ...view, b2b: 'gross' });
+
+await admin.tax.displayPolicy.set({ default: 'channel', b2b: 'gross', countries: [] });
+```
+
+`audiences` lists the visitor, the retail customer, the B2B or trade customer and, while a country
+is listed, a customer in the first one. In an organization's workspace an answer that falls back
+to "prices include tax" is `mode: null, dependsOnStore: true`: each member store keeps its own. A
+store that inherits the policy from its organization reads the organization's.
+
+Reading needs any administrator permission on the store; `set` needs `UpdateChannel`. Refusals:
+`CHANNEL_SETTINGS_INVALID` (`ValidationError`, `details[]` per field) from `preview`, and from
+`set` before anything is written, for a choice that is not exactly one of the values, a country
+code that is not two letters, a country listed twice or more than 300;
+`ORGANIZATION_SETTINGS_INHERITED` / `MANAGED_BY_ORGANIZATION` (`BusinessRuleError`) from `set`
+while the organization's policy applies.
+
 ### Content types, fields and page values
 
 A content type is what the CMS calls a collection (blog posts, FAQs, a team page): its fields
@@ -1755,11 +2063,14 @@ const labels = await admin.content.items.lookup(referencedIds);
 - Writes answer the item's row (`status`, `slug`, `path`, …) without its values: read them back
   with `get`. `update` writes only the members and value slugs it is given.
 - `publish` refuses an item whose required field is empty (`ValidationError`, naming the
-  fields); `bulkSetStatus` does not check them. `bulkSetStatus` and `bulkDelete` answer how many
-  items they changed, skipping ids that are not live items of the type.
+  fields). `bulkSetStatus` applies the same rule to each item and reports each on its own:
+  `results` holds `{ id, status: 'OK' | 'FAILED', code, message }` per id named, so a refused item
+  (`VALIDATION_ERROR`) keeps its status while the others change, and an id that is not a live
+  item of the type is `NOT_FOUND`. `bulkDelete` answers how many items it removed, skipping ids
+  that are not live items of the type.
 - `lookup(ids)` and `lookupWithFields(ids, fieldSlugs)` take any number of ids (sent in the
   CMS's batches of 50) and answer the ids that resolved, in the order given, each once (an
-  unknown id is simply absent; one that is not a UUID fails the whole call, `INVALID_DATA`). A
+  unknown id, or one that is not a UUID, is simply absent). A
   credential holding `ReadCmsContent`, `UpdateCatalog` or `UpdateProduct` resolves every status;
   any other resolves published items only.
 - Reads need no permission, but only a `ReadCmsContent` holder is served drafts and archived
@@ -1796,8 +2107,8 @@ const fetched = await admin.content.assets.uploadFromUrl({ url: 'https://example
   never listed, and an upload lands under the store's own storage prefix (`storageKey`,
   `{store code}/content/…`), which the platform chooses.
 - `list` pages by offset with `Page.total`, newest first; it filters by `folderId` (`null`: no
-  folder), a MIME type prefix (`image/`) and a full-text `search` (relevance order; the CMS then
-  matches `mimeType` exactly and ignores `folderId: null`).
+  folder), a MIME type prefix (`image/`) and a full-text `search` (relevance order, with the same
+  two filters).
 - `upload` sends `multipart/form-data` through the CMS (the transport's `RestCall.multipart`); a
   file without a name is refused before sending (`ASSET_FILE_NAME_REQUIRED`). The CMS refuses a
   type it does not accept or a file over its size limit (`ValidationError`, 400), and a body over
@@ -1814,6 +2125,126 @@ const fetched = await admin.content.assets.uploadFromUrl({ url: 'https://example
   `update` and `folders.update` `UpdateCmsAsset`; `delete` and `folders.delete` `DeleteCmsAsset`.
   No write is deduplicated by an `idempotencyKey`.
 
+### Navigation menus and content strings
+
+A store's navigation menus (a header, a footer column) and its content strings: translatable pieces of
+storefront copy read by key (`cart.empty`, `footer.copyright`).
+
+```ts
+const footer = await admin.content.menus.create({
+  name: 'Footer',
+  slug: 'footer',
+  metadata: { heading: 'Visit us', imageAlt: 'Our shop' },  // stored verbatim
+});
+const shop = await admin.content.menus.items.create(footer.id, {
+  itemType: 'heading',
+  translations: [{ languageCode: 'nl', label: 'Winkel' }],
+});
+await admin.content.menus.items.create(footer.id, {
+  itemType: 'internal',
+  url: '/sale',
+  parentId: shop.id,                                   // nested under the heading
+  translations: [{ languageCode: 'nl', label: 'Uitverkoop' }],
+});
+await admin.content.menus.items.update(footer.id, shop.id, { position: 2 });
+const menu = await admin.content.menus.getBySlug('footer'); // what a storefront renders
+
+await admin.content.strings.create({
+  key: 'cart.empty',
+  values: [{ languageCode: 'en', value: 'Your cart is empty' }],
+});
+await admin.content.strings.import([
+  { key: 'cart.checkout_button', values: [{ languageCode: 'nl', value: 'Afrekenen' }] },
+]);
+const all = await admin.content.strings.export();     // { 'cart.empty': { en: '…' }, … }
+```
+
+- `menus.list` pages by offset with `Page.total`, newest first or by `sort` (`name`, `created_at`,
+  `updated_at`, `-` for descending), each menu with its `itemCount`; `search` matches the name.
+  `menus.get` and `getBySlug` answer every live item as a FLAT `items` list: build the tree from
+  each item's `parentId`.
+- A menu's and an item's `metadata` are stored verbatim and never case-converted.
+- `items.create` and `items.update` answer the item as stored, with its translations. A `parentId`
+  must be a live item of the same menu, never the item itself or one of its children
+  (`ValidationError`, `MENU_ITEM_PARENT_INVALID`). A changed `position` shifts the siblings in
+  between. A move to another parent is not renumbered correctly (the new parent's children can
+  end up sharing a number, and the old parent keeps a gap): read the menu again and set each
+  sibling's `position` after it. `items.delete` leaves the item's children in the menu, naming the removed item as their
+  parent: move or delete them first.
+- `strings.list` answers every string with its values in key order, a page at a time by offset; a
+  `search` matches keys, descriptions and values. `strings.update` writes the languages it names
+  and keeps the others: there is no way to remove one language's value. `import` creates missing
+  keys and writes the values it names, all or nothing; `export` answers the whole store as one
+  `key → language → value` map, keys exactly as stored.
+- Reads need no permission (storefronts read the same routes). Menu writes need `CreateCmsMenu`,
+  `UpdateCmsMenu` or `DeleteCmsMenu`, content-string writes `CreateCmsContent`, `UpdateCmsContent`
+  or `DeleteCmsContent`, as each method's TSDoc says. `menus.delete`, `menus.items.delete` and
+  `strings.delete` are `@effect destructive`.
+- Refusals: `NotFoundError` (404) for a menu, item or string this store does not have,
+  `ConflictError` (409) for a taken slug or key, `ValidationError` (400) for refused input
+  (`VALIDATION_FAILED` with `details[]`). No write is deduplicated by an `idempotencyKey`.
+
+### Forms, fields and submissions
+
+A store's forms (a contact form, a newsletter sign-up), the fields a visitor fills in, and what
+visitors submitted.
+
+```ts
+const contact = await admin.content.forms.create(
+  {
+    name: 'Contact',
+    slug: 'contact',                                   // lowercase words joined by hyphens
+    notificationEmails: 'team@example.com',
+    settings: { sendConfirmationEmail: true },         // stored verbatim
+    translations: [{ languageCode: 'nl', title: 'Neem contact op' }],
+  },
+  { idempotencyKey: crypto.randomUUID() }
+);
+await admin.content.forms.fields.create(contact.id, {
+  name: 'First name',
+  slug: 'first_name',                                  // words joined by UNDERSCORES
+  fieldType: 'text',
+  isRequired: true,
+  validation: { max_length: 80 },
+  translations: [{ languageCode: 'nl', label: 'Voornaam' }],
+});
+const { fieldTypes, slugRules } = await admin.content.forms.fieldTypes();
+
+for await (const submission of await admin.content.forms.submissions.list(contact.id)) {
+  console.log(submission.createdAt, submission.data.first_name); // answers keyed as stored
+}
+```
+
+- `forms.list` pages by offset with `Page.total`, newest first or by `sort` (`name`,
+  `created_at`, `updated_at`, `-` for descending), each form with its `submissionCount`; `search`
+  matches the name. `get` and `getBySlug` answer the form with its translations and its fields,
+  REMOVED fields included with their `removedAt`, so the answers older submissions hold under a
+  removed field's slug can still be labelled.
+- `references` and `reference` answer forms as id, name and slug for ANY caller (what a
+  storefront reads): a content editor without `ReadCmsForm` can still name and pick the form a
+  page shows, where `list` and `get` refuse with `AdminProjectionError`.
+- A form's `settings` and a field's `config` and `validation` are stored verbatim and never
+  case-converted. `update` replaces each bag whole; `null` clears it.
+- `fields.update` writes what it names: a new `position` moves no other field, so give each field
+  its number to reorder a form. `fields.delete` removes the field from the form; submissions keep
+  what they answered under it.
+- **Submissions are personal data.** `data` keeps each answer under the field slug exactly as
+  stored (`first_name`, never `firstName`), and `ipAddress` / `userAgent` identify the visitor's
+  device. An app installation below `customerData: full` is refused (`PermissionDeniedError`,
+  `CUSTOMER_DATA_NOT_GRANTED`); staff and personal API tokens need `ReadCmsForm`.
+  `submissions.list` walks by the CMS's cursor without `after` (each submission once, even while
+  visitors submit), and `after: offsetCursor(n)` opens a table's page by offset.
+  `submissions.delete` removes a submission from every read, but the CMS keeps the row: it is not
+  an erasure.
+- Permissions: reads `ReadCmsForm` (anyone else is answered the storefront projection, refused
+  with `AdminProjectionError`); writes `CreateCmsForm`, `UpdateCmsForm` or `DeleteCmsForm`, as each
+  method's TSDoc says. `forms.delete`, `fields.delete` and `submissions.delete` are
+  `@effect destructive`.
+- Refusals: `NotFoundError` (404) for a form, field or submission this store does not have,
+  `ConflictError` (409) for a taken slug (a form's in the store, a field's in its form),
+  `ValidationError` (400) for refused input (`VALIDATION_FAILED` with `details[]`). `create` and
+  `upsertBySlug` honour an `idempotencyKey`; the other writes are not deduplicated.
+
 ### Catalog
 
 Products, variants, option groups, facets, collections, assets, storefront visibility, product
@@ -2098,13 +2529,41 @@ const result = await admin.catalog.syncContentFacets(propertyId);
   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.
+- **Automatic for published content items.** When a PUBLISHED content item is edited,
+  published or unpublished, the platform syncs the properties naming it by itself within about a
+  minute (`syncContentItemFacets` below). Call `syncContentFacets` after renaming a draft or
+  archived item (nothing is announced for one until it is published), after renaming a product,
+  or to sync one property at once.
 - 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`.
 
+#### Syncing the filter values that name some content items
+
+```ts
+// After importing or editing content items yourself:
+const result = await admin.catalog.syncContentItemFacets([itemId1, itemId2]);
+// { synced: [{ propertyId, items: 12, unresolved: [], fieldFacets: 0 }],
+//   skipped: [{ propertyId, code: 'MANAGED_BY_ORGANIZATION', message: '…' }], changed: true }
+```
+
+- **Every property naming one of the items.** Each filterable `content_item` property of the store
+  whose values name at least one of the items is synced as `syncContentFacets` syncs it. The
+  platform calls this by itself for the items a change to a PUBLISHED item touched.
+- **A property's refusal skips that property alone.** It is reported in `skipped` with its code
+  (`MANAGED_BY_ORGANIZATION` for the organization workspace's property, which is synced in the
+  workspace) and nothing of it is written; the others are synced. `changed` says whether
+  anything was written at all.
+- **All or nothing otherwise.** Every label is read first and the writes are one transaction, so a
+  content system that cannot be read (`CMS_REQUEST_FAILED`, 422, try again) or any other failure
+  writes nothing. Repeating the call is safe.
+- At most `MAX_CONTENT_ITEM_FACET_SYNC_IDS` (500) different ids per call, repeats counted once
+  (`CONTENT_ITEM_IDS_INVALID`, 400, checked before sending too); an id that is not a uuid is
+  `ENTITY_NOT_FOUND` (404). Needs `UpdateCatalog`. `@effect write`. Requires a platform release
+  that serves `syncContentItemFacets`.
+
 #### A property's field-level facets
 
 ```ts
@@ -2269,6 +2728,11 @@ await r.groups.reorder(groups.map((g) => g.id).reverse());
   or facet value: any other is refused `RECOMMENDATION_SOURCE_NOT_FOUND` (404), another store's
   exactly like an unknown id, and the storefront never draws from another store's collection or
   facet value, a rule stored before that refusal included.
+- **`maxItems`** is a whole number from 1 to 50 (`RECOMMENDATION_MAX_ITEMS_RANGE`). Any other value
+  on `groups.create`, or sent on `groups.update`, is refused `RECOMMENDATION_MAX_ITEMS_INVALID`
+  (`ValidationError`, 400, `details[0].field` `/input/maxItems`) before anything is sent; the
+  platform refuses it with the same code and detail. An update that leaves `maxItems` out is not
+  judged, so a group stored outside the range before the rule stays editable.
 - **`reorder`** numbers the ids given `0, 1, 2…`; an id the store (or, for entries, the group) does
   not hold is skipped without a word, and a row left out keeps its position: name them all.
 - **`manual.set`** replaces the product's picks in one group (`[]` clears them); the product itself
@@ -2320,6 +2784,13 @@ await r.attributes.reorder([fit.id, ...others]);
   history's texts, the moderation log's reasons and AI analysis), and `customerDisplayName` too
   below `identity`; each such record carries `redacted: true`. A `search` below `full` is refused
   `CUSTOMER_DATA_NOT_GRANTED` (403).
+- **Publishing needs `full`**: approving a review (`moderate`, or `bulkModerate` with `APPROVED`)
+  and `reply.set` publish under the store's name next to text a caller below `full` reads
+  blanked, so below `customerData: full` they are refused `CUSTOMER_DATA_NOT_GRANTED`
+  (`PermissionDeniedError`, 403; `bulkModerate` reports it `FAILED` on each review and changes
+  none). Rejecting, flagging, re-opening and `reply.remove` stay open at every level. A staff
+  session and a personal API token act at `full`. Releases before this rule let any `UpdateCatalog`
+  holder approve.
 - **`list`** pages by the offset cursor, `limit` 1 to 50 (`INVALID_PAGE_SIZE` otherwise, before
   sending: the engine answers no more). `search` matches the title or the text.
 - **`reply.remove` and `attributes.delete`** are `@effect destructive`. A deleted attribute's
@@ -2338,6 +2809,83 @@ await r.attributes.reorder([fit.id, ...others]);
   vendure-server first). The rest is served by every release; an older one answers each not-found
   and a taken slug as `USER_INPUT_ERROR` and takes another store's collection in `setCollections`.
 
+#### Documents: a product's downloads
+
+```ts
+const d = admin.catalog.documents;
+// A universal document: ONE translation, no language, naming the file (an asset of the library).
+const sheet = await d.create({
+  productId,
+  visibility: 'PUBLIC', // or 'AUTHENTICATED', or 'CUSTOMER_GROUP' with customerGroupIds
+  isLocalized: false,
+  translations: [{ title: 'Data sheet', assetId: pdfAssetId }],
+});
+// A localized one: one translation per language, at least one naming a file.
+await d.update(sheet.id, {
+  isLocalized: true,
+  translations: [
+    { languageCode: 'en', title: 'Data sheet', assetId: pdfEnId },
+    { languageCode: 'nl', title: 'Productblad', assetId: pdfNlId },
+  ],
+});
+const documents = await d.list(productId); // in their order
+await d.reorder(productId, documents.map((x) => x.id).reverse());
+await d.delete(sheet.id); // @effect destructive; the file stays in the library
+```
+
+- **`update`** changes only what it names; `translations` and `customerGroupIds`, when sent,
+  replace the document's. A `CUSTOMER_GROUP` document needs at least one of the store's own groups.
+- **Refusals**: the plugin's `USER_INPUT_ERROR` (`ValidationError`, 400) in its words for a product
+  or document the store does not have and for a translation set that breaks the rules; a customer
+  group of another store is `ENTITY_NOT_FOUND` (404); `delete` of a document the store does not
+  have is `PRODUCT_DOCUMENT_NOT_FOUND` (`NotFoundError`, 404, raised by the SDK: the engine answers
+  `false`); a new translation in a language the store does not offer is
+  `TRANSLATION_LANGUAGE_NOT_OFFERED` (400). `list` needs `ReadCatalog`, writes `UpdateCatalog`.
+  No release gate.
+
+#### SEO metadata: a product's head, share cards and AI directives; the coverage list
+
+```ts
+const m = admin.catalog.metadata;
+const meta = await m.get(productId); // null until the product has any
+// Only the fields named change; a translation is written per language.
+await m.upsert(productId, {
+  metaRobotsUnavailableAfter: '2026-12-31T23:59:00+01:00', // an offset is required
+  translations: [{ languageCode: 'nl', seoTitle: 'Linnen overhemd | Winkel', seoDescription: null }],
+});
+// The SEO coverage list: products missing a Dutch meta title, filtered BEFORE paging.
+const missing = await m.coverage({ languageCode: 'nl', filter: 'MISSING_TITLE', limit: 25 });
+missing.total; // every product missing one, across all pages
+// Save many at once: each product on its own, in its own transaction (ruling G117).
+const outcomes = await m.bulkUpsert(
+  missing.items.map((row) => ({
+    productId: row.productId,
+    input: { translations: [{ languageCode: 'nl', seoTitle: `${row.name} | Winkel` }] },
+  }))
+);
+const failed = outcomes.filter((o) => o.status !== 'OK'); // [{ productId, status, code, message }]
+```
+
+- **`coverage`** lists the store's products, name first, never a deleted one, each with its own
+  meta title and description in `languageCode` (no fallback to another language). `MISSING_TITLE`
+  and `MISSING_DESCRIPTION` keep those whose value there is null or empty; `term` matches the
+  name. Pages are full and `total` counts the filter and the term.
+- **`bulkUpsert`** takes 1 to 200 products, each named once (`BULK_ACTION_INPUT_INVALID`, 400,
+  before sending). A refused product is `FAILED` with the door's code (`ENTITY_NOT_FOUND`,
+  `PRODUCT_METADATA_INPUT_INVALID`, …) and changes nothing; the others still go through; a fault is
+  `INTERNAL_SERVER_ERROR` (logged by the engine). Not keyed: a repeat writes again.
+- **`delete`** (`@effect destructive`) removes the product's metadata in this store; the
+  storefront falls back to the product's own name and description.
+- **Refusals**: an input that breaks a rule is `PRODUCT_METADATA_INPUT_INVALID`
+  (`ValidationError`, 400) with one `details` entry per failure (`field`
+  `/input/translations/0/seoTitle`, `code` `INVALID_FIELD_LENGTH`); `upsert` of a product the
+  store does not hold is `ENTITY_NOT_FOUND` (404); an unavailable-after instant without an offset
+  is `INVALID_DATETIME` (400, before sending). `get` and `coverage` need `ReadCatalog`, writes
+  `UpdateCatalog`.
+- **Release**: `coverage` and `bulkUpsert` need a platform release with them (deploy
+  vendure-server first: an older one refuses the document). On an older release `upsert` answers
+  a validation failure as an uncoded `INTERNAL_SERVER_ERROR` and accepts another store's product.
+
 ### Pricing — promotions and coupons at the register
 
 ```ts
@@ -2567,7 +3115,9 @@ const assigned = await admin.pricing.priceLists.list({
 `forCustomer` answers the lists that apply to a customer of the store now, ranked by the
 engine with the function its own pricing uses: contracts first, then assigned to the customer,
 through one of their groups, to every customer (`assignmentType` `customer`, `group`,
-`channel`), then higher priority first. Only enabled lists inside their date window count, and
+`channel`), then higher priority first. Lists of one standing (same contract flag, assignment and
+priority) are tried together for each line, and the lower price wins there, an equal price going to
+the lower list id; `forCustomer` lists them by id. Only enabled lists inside their date window count, and
 every list of the store is considered; an order's one-time discount never appears (read it as
 `Order.priceList`). Each list comes with its first `entriesTake` entries (1 to 100, 100 when
 omitted), labelled as `entries.list` labels them, `entries.total`, and its order rules. A customer
@@ -2986,6 +3536,41 @@ 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.
 
+### An order's money rows
+
+```ts
+const view = await admin.orders.moneyView(orderId); // the store's basis; or { basis: 'GROSS' | 'NET' | 'CUSTOMER' }
+// view.basis → 'NET'; view.goodsAdjustments → [{ key, description: 'Welcome 10% Discount', amount: -4340, taxRate: null }]
+// view.subtotal, view.shipping, view.shippingAdjustments, view.taxes → [{ taxRate: 9, base: 11669, amount: 1050 }, …]
+// view.rounding, view.total, view.balance → { paid, giftCard, storeCredit, credited, stillToPay }
+```
+
+The order's money as rows the ENGINE builds from the order's own figures, in one basis, adding up
+exactly to its own totals: print them as they come and the order page, an email and an invoice
+cannot disagree by a cent. Never re-derive a row or convert one into the other basis yourself: ask
+for that basis. Needs `ReadOrder`.
+
+- **What adds up.** `Σ lines[].amount + Σ goodsAdjustments + Σ surcharges = subtotal`;
+  `Σ shipping + Σ shippingAdjustments = shippingTotal`; on `GROSS` `subtotal + shippingTotal +
+  (rounding ?? 0) = total`; on `NET` `subtotal + shippingTotal + taxTotal + (rounding ?? 0) =
+  total`; `Σ taxes = taxTotal`. `reconciles` is false only when the order's stored totals disagree
+  with its own rows.
+- **Units.** `lines[].unitAmount` is answered only in the basis the line was priced in, where it
+  multiplies out to the line; in the other basis it is `null`: show the line total alone.
+- **VAT.** One row per rate. On a `GROSS` view (`taxIncluded`) the rows are inside the total: label
+  them as included, never as an addition.
+- **Rounding.** A staff rounding is one row (`rounding`) just above the total; `total` is what the
+  order bills, `totalBeforeRounding` the total before it.
+- **What is paid.** `balance.stillToPay` is money not received yet: a promised bank transfer or
+  net-terms payment still counts. It does not read the B2B account ledger yet, so for an order a
+  live account invoice bills (`orders.status`: `lock.lockingInvoice.ledger === 'AR'`), do not show
+  it.
+- **Stored only.** It reads the order as stored, so it cannot preview an edit.
+
+Refused before sending: `INVALID_ORDER_MONEY_BASIS` (`ValidationError`). An order the store does not
+hold: `ORDER_NOT_FOUND` (`NotFoundError`). An engine before `Order.moneyView` refuses the document as
+`ValidationError` `GRAPHQL_VALIDATION_FAILED` (400): fall back to the order's own figures.
+
 ### Listing orders
 
 ```ts
@@ -3459,6 +4044,16 @@ refuse is found here. Nothing is saved, no event is published and no payment pro
 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`.
 
+Print the edit's money from `preview.moneyView` (the order after the edit) and
+`preview.moneyViewBefore`, the same rows `orders.moneyView` answers and the order page prints once
+the edit is saved: each promotion, fee, shipping line, VAT rate and staff rounding its own row,
+adding up exactly. Pass `{ moneyBasis: 'GROSS' | 'NET' | 'CUSTOMER' }` for another basis than the
+store's (a switch of basis plans again: the rows are read inside the run). The difference is
+`preview.totalDifference`, the billable totals' difference; `totalWithTax - totalWithTaxBefore`
+leaves a staff rounding out. The view's `balance` is the payments before the plan's `refund`. An
+engine before these fields answers them `null`, and `commitEdit`'s plan never carries them (read
+the saved order's `moneyView`).
+
 Read `blockers` first. They are an answer, not an error, so that a head can show every reason
 beside the steps:
 
@@ -4426,12 +5021,28 @@ refusal is thrown as a coded error, including the ones the Admin API answers as
 | `PAYMENT_SETTLE_DECLINED` / `PAYMENT_CANCEL_DECLINED` (422) | The provider said no; the message is its reason |
 | `PAYMENT_STATE_TRANSITION_ERROR` (422) | The payment is not `Authorized` (settled, cancelled or declined already) |
 | `ORDER_CANCELLED_PAYMENT_CONFLICT` (409) | The order is cancelled, and a cancelled order is never paid: cancel the payment instead |
+| `PAYMENT_CAPTURE_EXCEEDS_BILLED` (422) | The order's credit notes lowered what it bills, and this capture would take more: the provider can only capture the payment in full, other payments already cover the bill, or the order's only invoice was cancelled. The message names the credit notes and what to ask for instead |
 | `PAYMENT_SETTLE_CONFLICT` / `PAYMENT_CANCEL_CONFLICT` (409) | The payment moved meanwhile, or a capture of it may have reached the provider; read it again |
 | `IDEMPOTENCY_OUTCOME_UNKNOWN` (409, `outcomeUnknown`) | A capture reached the provider and its answer was lost: every capture is refused for 24 hours, then one would ask the provider again, so check the payment with the provider first and never retry blind |
 | `ENTITY_NOT_FOUND` (404) | No payment of an order of this store has that id |
 
 A settled payment is never voided: its money was taken, so it goes back with `payments.refund`.
 
+On an order whose credit notes lowered what it bills, a capture takes only what the order still
+bills without that payment. A promise whose money moves by hand (bank transfer, invoice, net terms)
+is recorded at that amount: `settle` answers the payment with the lower `amount`, and the rest of
+the promise is dropped. A payment its provider can only capture in full is refused
+`PAYMENT_CAPTURE_EXCEEDS_BILLED`. Ask first, to show staff what the press will do:
+
+```ts
+const preview = await admin.payments.settlePreview(paymentId); // ReadOrder; writes nothing
+// { authorized: 208093, records: 147414, creditNoted: 60679, creditNotes: ['CN-00012'], refusal: null }
+```
+
+`refusal` carries the `{ code, message }` that `settle` would throw now. The capture still judges
+again (and the provider may still decline it). An engine without `settlePreview` answers a GraphQL
+validation error: treat it as "no preview" and let `settle` decide.
+
 ### Refunding an invoiced order
 
 A refund of an order with a live invoice needs a credit note saying what the money was for, so
@@ -4477,13 +5088,31 @@ covered`: a refund that went back with its credit note is owed by nobody, and an
 a credit note owes only what is left. Show `owed` as what the customer still owes.
 
 `outstanding` keeps its meaning: what the payments are short of the order's total, the figure
-`payments.record` caps a payment at and the settle measures. `overpaid` stays measured against
+`payments.record` caps a payment at. `overpaid` stays measured against
 `total`, so money a credit note gave back without a refund never reads as an overpayment. Only the
 retail invoices count; an order billed on the accounts-receivable ledger owes what its account
 says (both fields read 0 / `outstanding` there). The cancel-with-money preview and answer carry
 both on their `position` too. Against an engine that does not serve them yet, these reads send
 their document again without them, so both are absent: read `owed ?? outstanding`.
 
+An order paid down to what its invoice bills net of its credit notes is PAID. `payable` is what
+its settled money must reach: `total` less what a live invoice's credit notes took off.
+`orders.settle`, the staff move into `PaymentSettled` and the platform's own settlement measure it,
+and a payment that pays the order down to it settles the order (a held one waits for
+`orders.settle`, which is how staff accept it):
+
+```ts
+// 125.14 parked, 20.00 credited without a refund, 105.14 paid:
+// { total: 12514, creditNoted: 2000, owed: 0, payable: 10514, settled: 10514, outstanding: 2000, … }
+await admin.orders.settle(orderId); // settles and places it
+```
+
+An order whose only invoice was cancelled with nothing in its place reads `creditNoted: total`
+and `owed: 0` but `payable: total`: it takes no more money and counts as paid only once it is
+invoiced again or cancelled. `order.settlement_completed` then carries `credit_noted`, so
+`total_settled + credit_noted >= billable_total_with_tax`. An engine without `payable` gets the
+read again without it: read `payable ?? total`.
+
 ### Accounts receivable: credit, AR documents and AR payments
 
 A store that keeps its own accounts-receivable ledger (B2B credit switched on) invoices customers
@@ -4884,15 +5513,31 @@ language answers each call `GRAPHQL_VALIDATION_FAILED`.
 
 **What a cashier may do without a manager** (engine sprint 18): each staff member carries a set of
 grants (`POS_STAFF_GRANTS`: `manual_price`, `discount`, `custom_item_over_limit`, `refund`,
-`discard_held_sale`, `paid_out`, `no_sale`, `safe_drop`, `float_adjust`). A cashier holding one does
-that action on the till on their own sign-in; without it a manager approves, as before. A manager
-may do all of them, whatever is stored. Closing a drawer above the store's variance threshold, an
-approval for a colleague and unpairing a till stay a manager's. The engine judges every action.
+`discard_held_sale`, `paid_out`, `no_sale`, `safe_drop`, `float_adjust`, `return_items`,
+`void_sale`, `no_receipt_return`, `online_return`, `manage_card_terminal`, `discount_over_limit`,
+`view_reports`). A cashier holding one does that action on the till on their own sign-in; without
+it a manager approves, as before. A manager may do all of them, whatever is stored. Closing a
+drawer above the store's variance threshold, an approval for a colleague and unpairing a till stay
+a manager's. The engine judges every action.
+
+`view_reports` (engine POS programme PR 15) refuses no action: it decides what the till's day
+report (`posTillDayReport`, the till's Reports tab) shows. Without it the engine answers the day's
+counts only, every money figure `null` with `withheldReason: view_reports`, until a manager
+approves showing them; a manager holds it by role. `view_reports` governs the day report only. A
+store that wants cashiers to see no money at all sets `blindCount`: the drawer's X report, its
+movement list and the close follow the store's blind count alone.
+
+`discount_over_limit` is EXPLICIT (`POS_EXPLICIT_STAFF_GRANTS`): it lets a till discount the
+person authorises (their own, or one they approve as a manager) go past the store's discount limit,
+and a manager holds it only when it is stored, like a cashier. It opens no door: a cashier still
+needs `discount` to give a discount at all. `knownGrants()` answers the grants the engine can store
+(its own `PosStaffGrant` values), so a caller deployed ahead of the engine offers only those.
 
 ```ts
 await admin.pos.staff.setGrants(alex.id, ['refund', 'paid_out']);   // replaces the whole set
 const { grants } = (await admin.pos.staff.grants(alex.id)) ?? { grants: [] };
 const everyone = await admin.pos.staff.listGrants();                 // id, role, grants per member
+const offered = await admin.pos.staff.knownGrants();                 // the engine's own values
 ```
 
 `setGrants` sends the list as given; the engine stores it deduplicated in its own order and writes
@@ -5254,6 +5899,24 @@ is sent (`ValidationError`, `POS_DEVICE_KIND_INVALID`, the engine's own code for
 `lock` and `unlock` answer `device.kind`; `list` and `revoke` do not, where a device is a till
 unless the fleet says otherwise. Creating a device needs a human session (`pair`'s rule).
 
+**A code for a store reviewer** works 30 days instead of 10 minutes (`validity`, engine
+`emre/pos-reviewer-pairing`), for Apple's or Google's reviewer, who installs the app days after it
+was submitted:
+
+```ts
+const { code, expiresAt } = await admin.pos.devices.pair(reviewTill.id, { validity: 'APP_REVIEW' });
+```
+
+It is still claimed once, by one tablet, and a new code of either validity replaces the device's
+unclaimed one, so issue one per reviewer device and a fresh one per submission. Only a platform
+SuperAdmin may issue one (it is the demo store's tool): anyone else is refused
+`POS_PAIRING_REVIEW_CODE_NOT_ALLOWED` (`PermissionDeniedError`). `pair` without
+`validity` is a `STANDARD` code on any engine; a call that names one (`POS_PAIRING_CODE_VALIDITIES`:
+`STANDARD`, `APP_REVIEW`) needs an engine that has it (an older one refuses the document, and the
+SDK raises a 400 `ValidationError`, `BAD_REQUEST`), and any other value is refused before anything
+is sent (`ValidationError`, `POS_PAIRING_CODE_VALIDITY_INVALID`). The location rule and the till
+ceiling apply as to every code.
+
 **Setting a till up** reads it and assigns where it sells, which drawer it opens and which card
 terminal it charges:
 
@@ -5289,6 +5952,14 @@ location `POS_LOCATION_MISMATCH` and a retired one `POS_REGISTER_INACTIVE` (both
   or not one word (`POS_MOLLIE_TERMINAL_ID_INVALID`, `ValidationError`); `clearTerminal` takes the
   terminal off.
 
+From engine `pos-device-move-refuses-open-drawer`, `assignLocation` and `assignRegister` refuse to
+change a device's location or register while it has an open drawer: `POS_DEVICE_SESSION_OPEN`
+(`BusinessRuleError`, the engine's sentence naming the drawer's register), and nothing changes. The
+drawer stays on the register it opened on, so a move would sell the new location's stock into the
+old place's cash. Close the drawer first (at the till, or `sessions.close` /
+`sessions.closeUncounted`; `sessions.openForDevice(deviceId)` reads it), then move the device. A
+call naming the location and register the device already holds still answers the device.
+
 An older engine keeps a moved device's register, stores any terminal text and fails the
 `registerId` move and `clearTerminal` at validation. The engine does not ask Mollie about a
 terminal id: take it from `terminals.list()`. A display takes no terminal
@@ -5331,16 +6002,31 @@ staff session reads the switch.
 **The engine records each offline sale once**, at the prices the till charged, into the drawer it
 was rung in, when the till is back; the till's replay is its own door and no SDK method sends it.
 A sale it records with something to look at is `needs_review` (`price_changed`, `not_fulfilled`,
-`cashier_changed`, `policy_off`, `over_cap`, `sold_at_suspect`); one it cannot record is `refused`
+`cashier_changed`, `policy_off`, `over_cap`, `sold_at_suspect`, `cashier_unverified`: the cashier
+the till names was not signed in, or had not unlocked it offline, on that till when it sold;
+`item_gone_stand_in` and `stock_short_stand_in`: a gone item or a shortfall recorded on a stand-in
+line; `total_corrected`: the order's total corrected to the cash taken; `rounding_as_rung`: settled
+with the rounding the till applied); one it cannot record is `refused`
 (`item_gone`, `drawer_closed`, `currency_changed`, `prices_exclude_tax`, `out_of_stock`,
-`gift_card`, `total_mismatch`, `rounding_mismatch`) and only its row exists. More may come: show an unknown
+`gift_card`, `total_mismatch`, `rounding_mismatch`, `price_over_limit`: a till price further below the
+store's than its discount limit, which a manager who may go past the limit can record again) and only
+its row exists. More may come: show an unknown
 status or reason as it is (`POS_OFFLINE_SALE_REASONS` lists today's). **`offlineSales.list`** pages
 through them newest first: `filter: 'open'` (the default) or `'all'`, `deviceId`, `limit` at most
-100 (50 by default); a location-restricted caller sees its own tills only. **`resolve`** marks one
+100 (50 by default); a location-restricted caller sees its own tills only; each row names who
+recorded it again (`recordedAgainAt`, `recordedAgainByUserName`; an engine before POS polish PR 6
+refuses those fields once, and the list then asks without them). **`resolve`** marks one
 handled with what was done (1 to 500 characters); nothing is recorded again, so fix the order, the
 stock or the drawer first. The same note again answers it unchanged; refused
 `POS_OFFLINE_NOTE_INVALID` (`ValidationError`), `POS_OFFLINE_SALE_NOT_FOUND` (`NotFoundError`, a
 `recorded` sale included) and `POS_OFFLINE_SALE_RESOLVED` (`BusinessRuleError`, another note).
+**`recordAgain`** (an engine with POS polish PR 6) records a `refused` sale again the way the till's
+replay does, into its own drawer while open, else the open drawer `registerSessionId` names, and
+answers it with `recordedAgainAt` and `recordedAgainByUserName`; refused again it stays `refused`
+with its new reasons. It needs `CreateOrder` too; refused `POS_OFFLINE_SALE_NOT_FOUND`
+(`NotFoundError`), `POS_OFFLINE_SALE_DRAWER_INVALID` (`ValidationError`,
+`extensions.registerSessionId`) and `LOCATION_NOT_ALLOWED` (`PermissionDeniedError`: the drawer
+stands at a location a restricted caller may not act at).
 **`devices.offlineSalesToReview`** is the fleet's count per device, its own document: `fleet` never
 selects it and keeps answering an engine before 45. The queue and the counts need `UpdateSettings`
 or `ManagePosDevices`. Each call is a document of its own: an engine before 45 answers it
@@ -5809,6 +6495,11 @@ await geo.countries.update(be.id, { enabled: false });
 - **Other refused deletes** answer `TAX_CATEGORY_NOT_DELETED`, `TAX_RATE_NOT_DELETED` or
   `ZONE_NOT_DELETED` (409 `ConflictError`) with the engine's reason: a zone is refused while a
   store uses it as its default tax or shipping zone, or a tax rate prices in it.
+- **A rate is a percentage from 0 to 100**, both included. A value outside it is refused
+  `TAX_RATE_VALUE_INVALID` (400 `ValidationError`) before anything is sent, and by the engine for
+  any other caller, with the same sentence and `details[0].field` `/input/value` (`code`
+  `minimum` or `maximum`). Only a value you send is judged: a rate stored outside the range
+  before the bound existed can still be renamed or switched off.
 - **A rate keeps its customer group.** The engine cannot take a group off a rate (it ignores a
   null group and keeps the stored one), so `rates.update` refuses `customerGroupId: null` with
   `INVALID_TAX_RATE_INPUT` instead of answering success. Create a rate without a group and delete
@@ -6344,6 +7035,44 @@ exactly as the engine sends it: compare instants with `Date.parse` and format it
 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).
 
+### Pre-order dates that follow the purchase orders
+
+A variant's availability date (`availableFrom`, the end of a `preorder` or `comingSoon` state) can
+follow the purchase orders instead of the date staff set: with `incoming` it is kept equal to the
+earliest FUTURE day a supplier confirmed for an open purchase order into the store's storefront
+warehouses, recomputed whenever a purchase order of the variant is confirmed, revised, received or
+cancelled (purchase-orders spec §8.12.3).
+
+```ts
+const now = await admin.catalog.variants.availableFromSource(variantId);
+// { productVariantId, source: 'manual', availableFrom: '2026-11-04T23:00:00.000Z',
+//   confirmedIncomingOn: '2026-11-05', sharedAcrossLegalEntities: false }
+
+await admin.catalog.variants.setAvailableFromSource(variantId, 'incoming', { idempotencyKey });
+await admin.catalog.variants.setAvailableFromSource(variantId, 'manual');
+```
+
+- `confirmedIncomingOn` is the day `incoming` follows, read whatever the source; `null` means no
+  confirmed purchase order, and the date then keeps its last value.
+- The day becomes the instant local midnight begins in the store's time zone. The date only takes
+  effect under a variant state other than `inherit`.
+- `source` is typed as the two names but carries any string a newer engine adds.
+
+Both need the Purchasing plugin on the store (`PLUGIN_ACCESS_DENIED`, 403). The read needs
+`ReadCatalog` or `ReadProduct`; the switch needs `UpdateCatalog` or `UpdateProduct` on every store
+holding the variant. Refusals, none of which writes anything:
+
+- `AVAILABLE_FROM_SOURCE_INVALID` (400 `ValidationError`): a source other than `manual` or
+  `incoming`, refused before sending.
+- `PURCHASING_NOT_ENABLED` (422): `incoming` while purchasing is off for the legal entity.
+- `AVAILABLE_FROM_SOURCE_SHARED_VARIANT` (422): `incoming` for a variant stores of more than one
+  legal entity, or an organization, hold (`sharedAcrossLegalEntities`).
+- `PURCHASING_VARIANT_NOT_FOUND` / `ENTITY_NOT_FOUND` (404): a variant this store does not have.
+
+The two are documents of their own, never fields of the variant reads, so `variants.get` and
+`list` keep working against an older engine. They need a vendure-server release with purchase
+orders step 5.3: deploy it first.
+
 ### Variant prices from an organization
 
 A variant an organization shares from its workspace (catalog sharing on) reaches each member store
@@ -6780,8 +7509,8 @@ await exact.webhooks.sync();
 await exact.disconnect();                                  // true, or false when the store had no row
 ```
 
-The store's Exact Online settings tab. The sync runs, the logs and the shipping-method mapping
-follow in their own modules.
+The store's Exact Online settings tab. Its inbound sync, its shipping-method mapping and its
+connection logs are below.
 
 - **`config.update` takes one object; the wire keeps the engine's inline arguments.** A key left
   out keeps the stored value; `autoPush` and `customerSync` replace their whole setting (`null`:
@@ -6807,6 +7536,249 @@ follow in their own modules.
   `config.get` and `disconnect` (`PLUGIN_ACCESS_DENIED`, 403; never a SuperAdmin). A SuperAdmin head
   acts on another store through `admin.withTenant(...)`.
 
+### Exact Online sync, shipping methods and connection logs
+
+```ts
+const exact = admin.integrations.exactOnline;
+
+await exact.sync.logs({ entity: 'items', limit: 5 }); // the newest runs (1-100), not a page
+await exact.sync.health();                            // how each area last ran: customers, catalogue, orders
+await exact.sync.runCatalogue();                      // "Sync now": queued, answers true (@effect money)
+await exact.sync.runCustomers();
+await exact.sync.runPriceLists();                     // false: one is already queued
+await exact.sync.reimportPictures();                  // how many pictures were marked
+await exact.sync.cursors();
+await exact.sync.resetCursor('items');                // the next sweep re-reads the stream
+await exact.warehouseLinks();                         // stock locations and their Exact warehouse
+
+const { mappings, exact: catalogue } = await exact.shipping.methods();
+await exact.shipping.runSync();                       // refresh the Exact catalogue, re-apply activated rates
+await exact.shipping.import(exactShippingMethodId);   // activate one in checkout, from Exact's rate
+await exact.shipping.setMapping({ vendureShippingMethodId, exactShippingMethodId }); // null clears
+await exact.shipping.convertToMapping({ exactShippingMethodId, vendureShippingMethodId });
+await exact.shipping.retireImported(exactShippingMethodId);
+
+for await (const call of await exact.connectionLogs.calls({ outcome: 'failed' })) {
+  console.log(call.occurredAt, call.operation, call.statusCode);
+}
+await exact.connectionLogs.events({ dateFrom: '2026-10-01T00:00:00+02:00' });
+const csv = await exact.connectionLogs.export('calls', {
+  dateFrom: '2026-10-01T00:00:00+02:00',
+  dateTo: '2026-10-14T23:59:59.999+02:00',
+});
+```
+
+- **A run is queued, never awaited.** `runCatalogue` (catalogue, customers, sales and purchase
+  orders), `runCustomers`, `runPriceLists` and `reimportPictures` answer once the work is on the
+  worker's queue; its outcome is a `sync.logs` row. They overwrite what Exact owns (prices
+  customers pay, stock, product and customer details, price lists and terms) and are tagged
+  `@effect irreversible`, as is `shipping.runSync` (it re-applies Exact's rates to activated
+  methods; a merchant's rename stays). `runCatalogue` is `@effect money`: its order import books
+  Exact's sales orders as placed orders with a settled payment. The runs are refused
+  `FIELD_GROUP_LOCKED` (422; the sentence names each owner and where to release it) while an
+  app or API token owns a field group of the store: Exact writes all four. A store that is not
+  connected is NOT refused: its run fails on the worker.
+- **`sync.logs` is the newest N, not a page.** `limit` is a whole number from 1 to
+  `EXACT_ONLINE_SYNC_LOG_LIMIT` (100) and is refused otherwise, before sending
+  (`INVALID_EXACT_ONLINE_INPUT`, 400), rather than answered short.
+- **The shipping methods.** A method Exact defines reaches checkout only through `import` or a
+  mapping. `convertToMapping` and `retireImported` soft-delete the method Exact created
+  (`@effect destructive`) and need `DeleteSettings` or `DeleteShippingMethod`; their refusals are
+  `USER_INPUT_ERROR` (400). `import` and `setMapping` refusals (not connected, not active in the
+  catalogue, no rate, mapped elsewhere) are not coded yet: `GRAPHQL_ERROR` (500).
+  `setMapping` refuses a missing or blank `exactShippingMethodId` before sending: the engine
+  would read either as null and clear the mapping; only an explicit `null` clears.
+- **The connection logs** are the store's own audit rows for Exact (`AuditCall`, `AuditEvent`),
+  newest first, paged by cursor. Pass dates with an offset: the service pins only a bare
+  `dateTo` (to the end of that UTC day) and reads any other zone-less value in its database's
+  session time zone. `export` answers the CSV text of a range of at most 366 days (both dates required;
+  `VALIDATION_ERROR`, 400, otherwise) and waits up to `EXACT_ONLINE_LOG_EXPORT_TIMEOUT_MS`
+  (120 s). An app below `customerData: full` reads the rows with every customer-data field null,
+  and may not search with `q`.
+- **Permissions:** reads `ReadSettings`; runs, `resetCursor`, `shipping.runSync`, `import` and
+  `setMapping` `UpdateSettings`. A store without the Exact Online plugin is refused
+  (`PLUGIN_ACCESS_DENIED`, 403; the connection logs `PermissionDeniedError`).
+
+### Exact Online terms, and the customer, order and product cards
+
+```ts
+const exact = admin.integrations.exactOnline;
+
+await exact.terms.paymentConditions();   // the ACTIVE conditions mirrored from the division
+await exact.terms.paymentDiagnostics();  // how far the customers' conditions reach
+await exact.terms.paymentDryRun();       // live read of Exact, writes nothing
+await exact.terms.incoterms();
+await exact.terms.deliveryDiagnostics();
+await exact.terms.deliveryDryRun();      // live read of Exact, writes nothing
+
+await exact.customers.paymentTerms(customerId);  // null when Exact holds none
+await exact.customers.deliveryTerms(customerId); // null when Exact holds none
+await exact.customers.priceList(customerId);     // status: assigned | pending | none | unlinked
+
+const state = await exact.orders.state(orderId); // origin: 'pushed' | 'imported' | null
+await exact.orders.syncState(orderId);           // null for an order never imported
+const pushed = await exact.orders.push(orderId); // @effect irreversible; refusal: success false
+await exact.orders.reprice(orderId);             // @effect money: re-split VAT at Exact's rates
+await exact.orders.repriceAll();                 // every imported order, counts
+await exact.orders.runSync();                    // queue the inbound order sync (@effect money)
+await exact.orders.runBackfill();                // reset the cursor and re-read the history
+
+await exact.products.status(productId);          // null for a product the store does not hold
+
+await admin.customers.deliveryTerms(customerId); // the provider-neutral terms an order takes
+```
+
+- **The dry runs read Exact live** and write nothing, here or in Exact, also while
+  synchronization is off. A store that is not connected is refused
+  `EXACT_ONLINE_NOT_CONNECTED` (`BusinessRuleError`, 422) before Exact is asked; a read Exact
+  refuses is named in `resources` (`complete: false`), not thrown. Every other read here is a
+  local read of what the sync last wrote.
+- **The customer cards answer the engine's spelling**: `status`, `classification` and
+  `deliveryAdvice` are lowercase (`assigned`, `single_due_date`, `complete_order`), unlike the
+  uppercase enums of `customers.credit.paymentTerms` and `customers.deliveryTerms`. They are read
+  on any store, with or without the plugin.
+- **`orders.push` writes a sales order into the store's Exact division** and cannot be undone from
+  the platform. It is write-once: an order already in Exact answers `alreadyPushed: true` and
+  writes nothing. A refusal (guest order, lines not linked to an Exact item, a sandbox store, no
+  active connection, another division's link, or Exact's own) is `success: false` with `error` (and
+  `errorCode` when it has one), not a throw. A sales order that came out different from the order
+  answers its differences in `warnings`. The engine takes no idempotency key for it yet. An engine
+  that predates `warnings` refuses the document unread; `push` and `state` then send it once more
+  without the field and answer `warnings: null` (push) or `[]` (state).
+- **`orders.reprice` and `repriceAll` change what an imported order bills**: each line's VAT is
+  re-split at the rate Exact's sales order holds, the gross total unchanged. Exact is the source
+  of truth for an Exact store's figures; nothing here recomputes them on the platform's side.
+- **The order runs are queued** and refused `FIELD_GROUP_LOCKED` (422) while an app or API token
+  owns a field group of the store. A missing order, customer or product id is refused before
+  sending (`INVALID_EXACT_ONLINE_INPUT`, 400).
+- **Permissions:** the terms `ReadSettings`; the customer cards and `customers.deliveryTerms`
+  `ReadCustomer`; `orders.state` and `syncState` `ReadOrder`; `push` and `reprice` `UpdateOrder`;
+  `repriceAll` and the runs `UpdateSettings`; `products.status` `ReadCatalog` or `ReadProduct`. A
+  store without the Exact Online plugin is refused the terms and the order methods
+  (`PLUGIN_ACCESS_DENIED`, 403).
+
+### Data pipelines
+
+A pipeline imports from, or exports to, another system over one of the store's connections, by
+hand or on a schedule. It is created by committing a set-up (below); its runs and their logs are
+read and driven through `runs` (next section).
+
+```ts
+const pipelines = admin.integrations.pipelines;
+
+for await (const pipeline of await pipelines.list({ direction: 'export' })) {
+  console.log(pipeline.name, pipeline.scheduleType, pipeline.timezone, pipeline.isActive);
+}
+const pipeline = await pipelines.get(id); // null when the store has none with that id
+
+await pipelines.update(id, { scheduleType: 'daily', timezone: 'Europe/Amsterdam' });
+await pipelines.update(id, { scheduleType: 'custom', cronExpression: '*/30 * * * *' });
+await pipelines.update(id, { config: { triggerFilter: { toState: 'PaymentSettled' } } });
+await pipelines.update(id, { isActive: false }); // pause: the schedule stops
+await pipelines.delete(id);
+```
+
+- **A schedule is a wall-clock time in the pipeline's own `timezone`:** `daily` runs at 03:00
+  there, `weekly` on Mondays at 03:00, `custom` on its cron, through the zone's daylight saving
+  changes. A set-up starts with the store's zone; a pipeline made before zones were asked for
+  holds `UTC`.
+- **Pausing** (`isActive: false`) unregisters the schedule, and a commerce plugin's export through
+  the pipeline (Hendriks) is refused until it is resumed. A run started by hand still works.
+- **An export's filter has one vocabulary**, the orders reader's: the key `toState` and the order
+  states. A save naming anything else is refused, because an unhonoured key would export every
+  order and an impossible value none: `PIPELINE_EXPORT_FILTER_UNSUPPORTED`, `_BLANK` or
+  `_VALUE_UNKNOWN` (`ValidationError`, 400, `details[].field` `triggerFilter`). `config` is merged
+  over the stored settings at the top level; `triggerFilter: {}` removes the filter.
+- A `custom` schedule with no cron is `PIPELINE_CRON_REQUIRED`, and one the scheduler can never run
+  (`0 0 31 4 *`) `PIPELINE_CRON_NEVER_FIRES`; both save nothing.
+- `delete` unregisters the schedule and removes the pipeline from the list, and cancels its runs
+  that have not ended: a queued or paused one at once, a running one after the batch it is
+  working on, so nothing more is imported or sent. Each says so in its `errorMessage`. Its past
+  runs and logs stay (`runs.get` still reads them).
+- Reads need `ReadCatalog`, writes `UpdateCatalog`. Another store's pipeline is not found (`get`
+  answers `null`). An organization workspace may only pause (`ORGANIZATION_WORKSPACE_NOT_A_STORE`
+  otherwise).
+
+### Data pipeline runs
+
+```ts
+const runs = admin.integrations.pipelines.runs;
+
+const run = await runs.start(pipelineId); // `pending`; { syncPolicy?, collectionAssignments? }
+const now = await runs.get(run.id); // null when the store has none with that id
+console.log(now?.status, now?.progress.orders?.exported, now?.errorMessage);
+
+for await (const past of await runs.list(pipelineId)) console.log(past.status, past.startedAt);
+
+await runs.pause(run.id); // at the next batch boundary
+await runs.resume(run.id);
+await runs.cancel(run.id); // a running or paused run; what it did stays done
+
+const errors = await runs.logs(run.id, { entityType: 'orders', result: 'errored', limit: 50 });
+console.log(errors.total, errors.items.map((log) => [log.sourceId, log.message]));
+```
+
+- **Pause and cancel act at the next batch boundary:** the batch in flight finishes and is
+  recorded. Only a `running` run pauses; a `running` or `paused` one cancels; a queued (`pending`)
+  one is refused `PIPELINE_RUN_NOT_STARTED`, and a run in any other state
+  `PIPELINE_RUN_ALREADY_ENDED`, `PIPELINE_RUN_NOT_RUNNING` or `PIPELINE_RUN_NOT_PAUSED` (all
+  `ConflictError`, 409). A run of another store is `PIPELINE_RUN_NOT_FOUND`.
+- **A run of a deleted pipeline is cancelled** (`pipelines.delete`): `status` `cancelled`,
+  `errorMessage` "The pipeline was deleted, so this run stopped after the batch it was working on.
+  Nothing more was sent." (or "...while this run was waiting to start..." / "...was paused...").
+- **The logs filter by `entityType` and `result`** (`created`, `updated`, `skipped`, `errored`,
+  `exported`), newest first, with `total`. There is no log level: a record's outcome is its
+  `result`.
+- **`start` is not idempotent**: each call queues another run. An export run sends orders to the
+  other system, which cannot be taken back (`@effect irreversible`, as `resume`).
+- **A run is also a job** with the same id: `admin.jobs.list()` indexes the runs it has not seen,
+  and `admin.jobs.wait(run.id)` then waits for one to end.
+- `start` and `resume` refuse a client whose channel token is no longer the store's
+  (`PIPELINE_CHANNEL_TOKEN_MISMATCH`, 403: the store was renamed; build a client with the new
+  token), and an organization workspace (`ORGANIZATION_WORKSPACE_NOT_A_STORE`). Reads need
+  `ReadCatalog`, the rest `UpdateCatalog`.
+
+### Following a run or a discovery live
+
+```ts
+const pipelines = admin.integrations.pipelines;
+const controller = new AbortController();
+
+for await (const event of pipelines.runs.watch(run.id, { signal: controller.signal })) {
+  // 'progress' while it works; then one of 'complete' | 'error' | 'cancelled' | 'paused', and the loop ends
+  console.log(event.type, event.phase, event.entityType, event.message, event.progress?.orders);
+}
+
+const discovery = await pipelines.discoveries.start(connectionId); // `pending`
+for await (const event of pipelines.discoveries.watch(discovery.id)) {
+  console.log(event.type, event.phase, `${event.percent}%`, event.message); // ends on 'complete' | 'error'
+}
+const read = await pipelines.discoveries.get(discovery.id); // null when the store has none
+const maps = await pipelines.discoveries.schemaMaps(discovery.id); // one per kind of record
+```
+
+- **`watch` ends on the job's terminal event**, which is yielded, never thrown: a failed run is an
+  `error` event whose `message` is the reason. A job that had already ended answers its ended state
+  at once; a queued run says nothing until it starts. A resumed run is watched again.
+- **A dropped connection is reopened** (at most `maxReconnects` times in a row, default 5;
+  `onReconnect` is told each time), so a deploy or a proxy timeout does not end the loop. A refusal
+  is never retried: another store's (or a deleted) run or discovery is a `NotFoundError` (404
+  `PIPELINE_RUN_NOT_FOUND` / `PIPELINE_DISCOVERY_NOT_FOUND`, before the stream opens; an older
+  plugins service refuses inside the opened stream, `PROGRESS_STREAM_REFUSED`, an
+  `UpstreamError`), and a missing `ReadCatalog` is a
+  `PermissionDeniedError` (403). Once the reopens are spent the loop throws
+  `PROGRESS_STREAM_CLOSED` or `PROGRESS_STREAM_STALLED` (no data for `idleTimeoutMs`, 45 s by
+  default); the job itself carries on, so read it with `runs.get` / `discoveries.get`. `signal`
+  ends it with `REQUEST_ABORTED`.
+- **The counts are the stream's.** A run cancelled by its pipeline's deletion ends the stream at
+  once while the batch in flight may still finish; `runs.get` reads the final counts.
+- An id that is not a run's or a discovery's id is refused `PROGRESS_STREAM_ID_INVALID` before
+  anything is sent: the streams are a closed set of kinds in `@sixtyninecommerce/core`, never a
+  path.
+- `discoveries.start` samples the source again on every call (a fixed-schema connector answers at
+  once; any other asks the AI, cached 24 hours for an unchanged source). An import set-up starts
+  its own (`drafts.discover`). It needs `UpdateCatalog`; the reads and `watch` need `ReadCatalog`.
+
 ### Data pipeline set-ups (drafts)
 
 An import or export set-up is kept on the server while the merchant works through it, so it can be
@@ -6927,6 +7899,58 @@ await pipelines.connections.delete(connection.id);
 - `siteAnalysis`, `publicCredentials` and a probe's `entityCounts` (keyed by the source's own
   entity names, `product_brand` too) keep their keys exactly (`PIPELINE_CONNECTION_PRESERVE_KEYS`).
 
+### Bulk price import
+
+Variant prices from a CSV, JSON or XML document, matched by SKU in the store: a dry run first,
+then the rows to write. Every method needs `UpdateCatalog` or `UpdateProduct`.
+
+```ts
+const prices = admin.integrations.priceImport;
+
+const document = { format: 'csv', content: await file.text(), fileTaxMode: 'inclusive' } as const;
+const preview = await prices.preview(document);   // nothing written
+preview.summary;                                    // { total, updated, unchanged, notFound, … }
+for (const row of preview.results) {
+  row.rowNumber; row.sku; row.status;               // 'updated' | 'unchanged' | 'not_found' | …
+  row.oldPrice; row.newPrice;                       // minor units, in the store's tax mode
+}
+
+const chosen = preview.results.filter((r) => r.status === 'updated').map((r) => r.rowNumber);
+const written = await prices.run({ ...document, selectedRows: chosen });
+written.summary.updated; written.summary.errored;   // a failed row does not undo the others
+
+// Any supplier file, converted by the platform's AI provider into a document `preview` accepts:
+const { conversionId } = await prices.convert({ file });       // .xlsx, .pdf, .docx, .csv, …
+const converted = await prices.follow(conversionId, {
+  signal,                                                       // abort to stop the conversion
+  onProgress: ({ step, message }) => console.log(step, message),
+});
+await prices.preview({ format: 'json', content: converted.document, fileTaxMode: converted.fileTaxMode });
+```
+
+- **`preview` writes nothing; `run` writes what customers pay and cannot be undone** except by
+  importing each row's `oldPrice` again. A timeout after `run` was sent does not say whether the
+  prices were written: `preview` the same document (rows already at their new price read
+  `unchanged`) before repeating.
+- **`selectedRows`** names rows by `rowNumber`: a CSV row's line (the header is line 1), a JSON
+  or XML entry's position. Left out, every `updated` row is written; `[]` writes nothing. Two selected rows setting one SKU and currency are refused whole,
+  `PRICE_IMPORT_SELECTION_CONFLICT` (`BusinessRuleError`, 422, one `details[]` entry per pair).
+- **A document that cannot be read is refused whole** (`PRICE_IMPORT_FORMAT_ERROR`,
+  `BusinessRuleError`, 422) and nothing is written; `details[]` name each problem (`field`:
+  `header`, `document` or `row N`). A row whose content is wrong is reported `invalid` instead,
+  and the rest still apply. At most 5,000 data rows.
+- **`fileTaxMode`** says whether the amounts include tax. Left out, they are read in the store's
+  own mode; given and different, each is converted at its variant's rate (`taxConverted`).
+- **The AI conversion writes nothing.** `convert` uploads the file (refused before sending
+  without a name: `PRICE_IMPORT_FILE_NAME_REQUIRED`); `follow` runs it, 30 seconds to 3 minutes,
+  and resolves the converted document with what was read (`interpretation`, `warnings`,
+  `fileTaxMode` and whether it was read from the file, `taxModeReason`). Its refusals keep their
+  codes (`AI_IMPORT_NO_PRICES_FOUND`, `AI_IMPORT_NOT_FOUND`, `AI_IMPORT_BUSY`, …; the TSDoc maps
+  each to its class); none is retryable, because an upload is read once: convert the file again.
+  An upload belongs to the store it was sent to, so follow it with the same client.
+- An assistant should ask before `run`, never before `preview` (`@effect irreversible` and
+  `read`).
+
 ### Searching the store
 
 One call finds products, orders, customers and content items matching a term: each type's best
@@ -7045,6 +8069,88 @@ products (`MAX_VARIANT_FIND_PRODUCTS`); more distinct ids than `take`. A search
 `admin.reports.popularVariants({ take, sinceDays })` answers its ranked variants in the same
 shape (plus `productId`), so a "popular" list needs no second read.
 
+### SEO: redirects, settings and automation
+
+```ts
+// Redirects: a page at a time, or every one.
+for await (const redirect of await admin.seo.redirects.list({ limit: 200 })) {
+  redirect; // { id, oldPath, newPath, statusCode, source: 'manual' | 'import' | 'auto', … }
+}
+await admin.seo.redirects.create({ oldPath: '/old-page', newPath: '/new-page' }); // 301
+const result = await admin.seo.redirects.import([
+  { oldPath: '/product/old', newPath: '/product/new' },
+  { oldPath: '/sale', newPath: 'https://outlet.example.com/', statusCode: 302 },
+]);
+// { created: 1, updated: 1, rejected: [{ index, oldPath, message }] }
+const nginx = await admin.seo.redirects.exportNginx(); // two `map` blocks, as text
+
+// The channel settings and the SEO defaults (Admin API).
+const settings = await admin.seo.settings.get();
+// { channelId, defaultLanguageCode, availableLanguageCodes, storefrontUrl,
+//   urlLocaleStrategy: 'path-prefix', urlLocalePrefixDefault: false,
+//   twitterHandle, defaultOgImageId, aiBotDefaults: { GPTBot: 'deny' }, llmsTxtEnabled,
+//   robotsTxtCustom,
+//   defaultsSource: { source: 'organization', locked: false, inheritable: true,
+//                     overridden: false, organizationName: 'Vinvin Group', effective: { … } } }
+await admin.seo.settings.set({ urlLocaleStrategy: 'subdomain' });
+await admin.seo.settings.set({ aiBotDefaults: { GPTBot: 'deny', ClaudeBot: 'allow' } });
+
+// The automation (plugins service).
+const config = await admin.seo.config.get();
+// { autoRedirectsEnabled, indexnowEnabled, indexnowKey, crawlSchedule: 'weekly', crawlMaxPages,
+//   crawlRatePerSec, cruxEnabled, gscConnected, gscPropertyUrl, gscConnectedAt,
+//   source, locked, overridden, inheritable, organizationName }
+await admin.seo.config.set({ autoRedirectsEnabled: false });
+const { key } = await admin.seo.config.rotateIndexnowKey();
+```
+
+SEO of the **active** store, in three parts.
+
+**Redirects** (`seo.redirects`) are what the store's old URLs answer. Storefronts read them live
+from the public redirect map (`createRedirectMiddleware` in `@sixtyninecommerce/client/next`), so a
+write reaches the site within a few minutes, with no deployment. Each rule is one exact source path
+to a path or an `https://` URL, with 301 (the default), 302, 303, 307 or 308. A malformed path, a
+self-redirect or another status is a `ValidationError`; a source the store already redirects, a
+loop or a chain past the hop limit a `ConflictError`. `import` adds or updates up to 5,000 rules
+(`REDIRECT_IMPORT_MAX_ROWS`) in one call, matched on the source path, and judges each row on its
+own: a bad row is answered in `rejected` by its index (with the service's sentence; there is no
+code per row yet) and the rest still land, in order, so a loop split across two rows is refused on
+the second. More rows, or none, is `REDIRECT_IMPORT_INVALID` before anything is sent: send a large
+file in chunks. `exportNginx` answers the rules as two Nginx `map` blocks (`$redirect_uri` and
+`$redirect_status` on `$uri`) for a site not on the storefront SDK. Every redirect method needs
+`UpdateChannel`; in an organization's workspace `create`, `update` and `import` are refused with
+`ORGANIZATION_WORKSPACE_NOT_A_STORE` (`BusinessRuleError`), `delete` never is. `delete` is the one
+destructive method.
+
+**Settings** (`seo.settings`) are Channel custom fields: the storefront URL and how languages show
+in its URLs (`URL_LOCALE_STRATEGIES`), always the store's own, and the SEO defaults (share card, AI
+crawlers, `llms.txt`, `robots.txt`), which are the `settings.seo` group. `get` answers the store's
+OWN values and `defaultsSource`: whether storefronts get them or the organization's
+(`defaultsSource.effective` is what they get). `set` is a patch: a key left out is unchanged, `null`
+clears it, and `aiBotDefaults` is an object the SDK encodes for the column (pass the map, never its
+JSON). The read-only keys `get` answers are ignored, so `set({ ...settings, … })` works. Refused
+before any request with `SEO_SETTINGS_INVALID` (`ValidationError`): an empty patch, a key that is not
+a setting, a bot map that is not an object. The engine refuses a directive other than `allow` or
+`deny` (`CHANNEL_SETTINGS_INVALID`, `details[].field` `customFields.aiBotDefaults`), another locale
+strategy (`USER_INPUT_ERROR`), a changed default the organization decides
+(`MANAGED_BY_ORGANIZATION` / `ORGANIZATION_SETTINGS_INHERITED`, `BusinessRuleError`; sending the
+stored value back passes) and a storefront URL for a workspace (`ORGANIZATION_WORKSPACE_NOT_A_STORE`).
+Writing needs `UpdateChannel`.
+
+**Automation** (`seo.config`) lives on the plugins service and needs the store's `seo` plugin:
+automatic redirects on URL changes, IndexNow, Core Web Vitals and the audit schedule
+(`SEO_CRAWL_SCHEDULES`; 10 to 5,000 pages at 1 to 10 a second). Its keys are the service's wire
+names camelised, as the meta catalog's `seo` schema publishes them (`indexnow_enabled` →
+`indexnowEnabled`). The switches are part of `settings.seo`, so `get` answers the effective ones with
+where they come from, and `set` refuses a change the organization decides
+(`MANAGED_BY_ORGANIZATION` / `ORGANIZATION_SETTINGS_INHERITED`; in the workspace, during a switch-off,
+`ORGANIZATION_SETTINGS_SWITCH_OFF_CONFLICT`, a `ConflictError`). Refused before any request with
+`SEO_CONFIG_INVALID`: an empty patch, a key that is not a switch, a null. A value out of range is
+the service's `VALIDATION_FAILED`. `rotateIndexnowKey` voids the old key at once (destructive): the
+store's `/<key>.txt` serves the new one; it is the store's own, never refused for an inheriting
+store, but refused in a workspace (`ORGANIZATION_WORKSPACE_NOT_A_STORE`). `get` needs
+`ReadSettings`, the writes `UpdateSettings`.
+
 ### Purchasing
 
 Buying stock from suppliers, per legal entity. The submodules so far are the legal entity's
@@ -7052,7 +8158,8 @@ purchasing settings with its document numbering, its suppliers with their contac
 ([Suppliers](#suppliers)), its purchase orders with their lines
 ([Purchase orders](#purchase-orders)), its reorder rules and suggestions
 ([Replenishment](#replenishment)), and what needs attention with who its alert emails go to
-([Alerts](#alerts)); receipts and returns join `admin.purchasing` as the engine ships them.
+([Alerts](#alerts)), its goods receipts ([Receipts](#receipts)) and its returns of goods to
+suppliers ([Returns](#returns)).
 
 ```ts
 const settings = await admin.purchasing.settings.get();
@@ -7667,7 +8774,8 @@ cards), and who its three alert emails go to.
 ```ts
 const summary = await admin.purchasing.alerts.summary();
 // { localDay: '2026-10-13', awaitingApproval: 2, overdueLines: 5, overdueOrders: 3, attentionOrders: 4,
-//   reorderSuggestions: 14, newReorderSuggestions: 3 }   — or null while purchasing is off
+//   reorderSuggestions: 14, newReorderSuggestions: 3, backordersReadyLines: 2,
+//   backordersReadyOrders: 1 }   — or null while purchasing is off
 
 const who = await admin.purchasing.alerts.recipients.list();
 // [{ alert: 'purchase_order_approval_requested', permission: 'ApprovePurchaseOrder', emails: [],
@@ -7689,12 +8797,16 @@ await admin.purchasing.alerts.recipients.update([{ alert: 'purchase_order_lines_
   confirmed day, else the requested one) is before `localDay`, today in the legal entity's time
   zone, and the orders holding them. `attentionOrders` counts each order awaiting approval or
   overdue once. `reorderSuggestions`/`newReorderSuggestions`: the last compute's listed
-  suggestions and the new ones among them. `summary` answers `null` while purchasing is not
-  switched on, and needs `ReadPurchaseOrder`.
+  suggestions and the new ones among them. `backordersReadyLines`/`backordersReadyOrders`: the
+  ACTIVE store's backordered order lines that stock on hand can ship now, and the orders holding
+  them (`backorders.ready()`, below). Against an engine before step 3.6 the SDK asks once more
+  without those two and answers them `null`; the other counts are unchanged.
+  `summary` answers `null` while purchasing is not switched on, and needs `ReadPurchaseOrder`.
 - **The alerts**, each an email under Management → Notifications (switched on, templates and
   sender there): `purchase_order_approval_requested` (an order or a revision waits for approval;
   default recipients the holders of `ApprovePurchaseOrder`), `purchase_order_lines_overdue` (the
-  daily overdue digest at 08:00 in the legal entity's time zone; `UpdatePurchaseOrder`) and
+  daily overdue digest at 08:00 in the legal entity's time zone; `ReceivePurchaseOrder`, the
+  staff who take the goods in; `UpdatePurchaseOrder` on an engine before step 3.6) and
   `reorder_suggestions_digest` (the new reorder suggestions, daily or on Mondays at 08:00 as the
   settings' `reorderDigest` says; `CreatePurchaseOrder`). The holders are the administrators of
   the legal entity's stores holding the permission; a platform administrator and an API
@@ -7709,6 +8821,372 @@ await admin.purchasing.alerts.recipients.update([{ alert: 'purchase_order_lines_
   purchases (`HUB_HAS_NO_PURCHASING`, `LEGAL_ENTITY_REQUIRED`, 422). An engine before step 4.3
   fails the request GraphQL validation (`GRAPHQL_VALIDATION_FAILED`).
 
+#### Backorders ready to ship
+
+What received goods let the store ship: its open backordered order lines that stock on hand can
+cover now, oldest order first.
+
+```ts
+const ready = await admin.purchasing.backorders.ready({ limit: 50 });
+// items: [{ orderId, orderCode: 'ORD-1042', orderState: 'PaymentSettled',
+//   orderPlacedAt: '2026-10-01T10:00:00.000Z', orderLineId, productVariantId, sku: 'TEE-M',
+//   name: 'Tee M', quantity: 5, backorderedQuantity: 3, readyQuantity: 3, stockOnHand: 8,
+//   supplierCancelled: false }, …]
+
+// What one receipt let ship: only the variants it brought in.
+const fromReceipt = await admin.purchasing.backorders.ready({ goodsReceiptId: receipt.id });
+for await (const line of fromReceipt) { /* every page */ }
+```
+
+- **The rule.** Per variant, over the store's stock locations: free = on hand − (allocated − the
+  claims allocation holds) − the in-stock parts no allocation holds, at most on hand. A paid
+  backordered order allocates past on hand, so taking its claims back out of `allocated` leaves what
+  the in-stock parts of open orders hold. An order whose reservation waits for fulfilment (net
+  terms, a stock-bypass import) holds nothing: its claim stays in, and its in-stock part is held
+  out of on hand as the stock it was promised. The free units go to the claims oldest order first
+  (placed, else created for an order never placed, then order code); a line is listed with what it
+  gets (`readyQuantity`, 1 to `backorderedQuantity`). Every open claim keeps its turn, a parked or
+  approval-waiting order's too (`orderState` says which). Another store's allocations at a shared
+  location stay in `allocated`, so the figure errs low there.
+- **Scope.** The ACTIVE store's own orders (a store of the same legal entity never lists another's
+  customers' orders) and its own stock locations. Nothing is allocated: open the order and fulfil it.
+- **The count** is on `alerts.summary()`: `backordersReadyLines` and `backordersReadyOrders`
+  (`null` from an engine before step 3.6, which refuses `ready()` itself at validation).
+- **Access.** Needs `ReadOrder`, the Purchasing plugin and purchasing switched on
+  (`PURCHASING_NOT_ENABLED`, 422). Refusals: `GOODS_RECEIPT_NOT_FOUND` (404, a receipt of another
+  legal entity too), `GOODS_RECEIPT_INVALID` (400, a page out of range: `limit` is 1 to 100).
+
+Needs an engine with step 3.6; against an older engine the request fails GraphQL validation
+(`GRAPHQL_VALIDATION_FAILED`). `supplierCancelled` (a line whose back-to-back link the supplier
+side ended, an ordinary backorder again) needs an engine with step 5.1. A line still waiting for
+its own purchase order (an open back-to-back link while it holds less than its open units, or a
+drop-ship line) is never listed: its purchase order serves it, not free stock.
+
+#### Order links (back-to-back)
+
+"Order from supplier" on a customer's order line: a line on a draft purchase order, linked to the
+order line, so the goods are allocated to that order line when they are received, before anything
+else, whatever the order's payment terms (net terms included).
+
+```ts
+// Onto the variant's preferred supplier's newest draft into the destination, else a new draft.
+const { link, purchaseOrder, createdPurchaseOrder } = await admin.purchasing.links.backToBack.create(
+  { orderLineId, baseQuantity: 3, stockLocationId },
+  { idempotencyKey: 'order-line-42-b2b' }
+);
+// link: { id, kind: 'back_to_back', status: 'open', orderCode: 'WT-0042', purchaseOrderCode:
+//   'PO-2026-0007', baseQuantity: 3, allocatedBaseQuantity: 0, expectedOn: null, … }
+
+// Later: what the order line waits for, and what arrived ("Supplier cancelled" included).
+const links = await admin.purchasing.links.forOrder(orderId);
+// [{ status: 'allocated', allocatedBaseQuantity: 3, stockLocationId, expectedOn: '2026-10-20',
+//    expectedOnConfirmed: true, … }]
+const onTheOrder = await admin.purchasing.links.forPurchaseOrder(purchaseOrder.id);
+
+// A dialog's defaults: what a link may order for the line, and what create takes by default.
+const { openBaseQuantity, linkedBaseQuantity, maxBaseQuantity, suggestedBaseQuantity } =
+  await admin.purchasing.links.backToBack.quantities(orderLineId);
+
+// The order line no longer waits for it; the purchase order line keeps its quantity.
+await admin.purchasing.links.backToBack.remove(link.id);
+```
+
+- **Where the line goes.** The draft named (`purchaseOrderId`: a standard draft of that supplier
+  and destination), else the supplier's newest draft into the destination (`stockLocationId`, else
+  the tenant's location, else the store's only one), else a new draft (`createdPurchaseOrder`). The
+  supplier is the variant's preferred one unless `supplierId` names another. The line buys whole
+  purchase units covering `baseQuantity`. A second link of the same order line onto the same draft
+  grows its line and its link instead.
+- **How much.** At most the order line's open units (not yet in a live fulfilment) that its other
+  links do not claim yet and their arrived, unshipped goods do not cover. Left out, all of those
+  the line plainly lacks: when goods that arrived for its earlier links may still cover it (units
+  shipped before they came cannot be told apart), the default refuses and asks for a quantity (`PURCHASE_LINK_EXCEEDS_OPEN_QUANTITY`, 422,
+  `details[0].maxBaseQuantity`). `backToBack.quantities(orderLineId)` answers both figures before
+  anything is written (`maxBaseQuantity`, and `suggestedBaseQuantity`: 0 when the default would
+  refuse), with the line's open units and what its active links claim; it needs
+  `UpdatePurchaseOrder`, as `create` does, and refuses a line `create` refuses whatever the quantity
+  (`PURCHASE_LINK_ORDER_LINE_NOT_FOUND`, `PURCHASE_LINK_ORDER_NOT_LINKABLE`). It needs an engine with
+  step 5.4.
+- **On receipt.** The accepted units of a linked purchase order line go to its links in the order
+  they were made, each up to what it claims and what its order line still has open (goods that
+  arrived for it earlier and have not shipped count as covering it), and are allocated to the
+  order line at the receipt location, when one of the order's stores holds that location (a
+  destination changed after the link leaves the link waiting). A prepaid backordered line already holds its
+  quantity: nothing is booked twice, and the units still count as its link's. Imported, cancelled
+  and fully shipped lines take nothing. What no link takes is ordinary stock.
+- **Status.** `open` → `partially_allocated` → `allocated`; `released` when the order or line is
+  cancelled (`order_cancelled`, `line_cancelled`) or the link removed (`removed`);
+  `supplier_cancelled` (`po_line_cancelled`) when its purchase order line can no longer supply it:
+  the order is cancelled or closed short, a revision removes or lowers the line, a supplier with no
+  backorders cancels the rest, a return credits refused goods. An ended link stays listed.
+- **Scope.** `create` takes a line of an order of the ACTIVE store (another store's answers
+  `PURCHASE_LINK_ORDER_LINE_NOT_FOUND`); `forOrder` answers nothing for another store's order;
+  `orderCode` is null on `forPurchaseOrder` for an order of another store of the legal entity.
+- **Access.** `create` and `remove` need `UpdatePurchaseOrder` on every store of the legal entity,
+  and `create` also `CreatePurchaseOrder` when it makes a new draft (`PURCHASE_LINK_DRAFT_DENIED`,
+  403); the reads `ReadPurchaseOrder`. Refusals: `PURCHASE_LINK_ORDER_NOT_LINKABLE` (422: not
+  placed, cancelled, imported, or drop-shipped), `PURCHASE_LINK_SUPPLIER_REQUIRED` (422: no
+  preferred supplier), `PURCHASE_LINK_INVALID` (400), `PURCHASE_LINK_NOT_FOUND` (404),
+  `PURCHASE_LINK_ALREADY_RELEASED` (422), `PURCHASE_ORDER_NOT_EDITABLE`, `SUPPLIER_ARCHIVED`,
+  `MANAGED_BY_PROVIDER` (422), and the destination's location refusals.
+- A receipt that meets a linked line while it is being fulfilled answers `PURCHASE_LINK_LINE_BUSY`
+  (try again; nothing was posted, and the receipt's key is free).
+
+Needs an engine with step 5.1; against an older engine the request fails GraphQL validation
+(`GRAPHQL_VALIDATION_FAILED`).
+
+#### Drop-ship
+
+A supplier item whose drop-ship mode is `always`, or `optional` when the store cannot ship the
+whole line from stock, makes a placed order's line a drop-ship line: the supplier sends it straight
+to the customer, and none of our stock is reserved, sold or given back for it. The platform drafts
+one drop-ship purchase order per supplier when the order is placed, with the order's delivery
+address. Staff approve and send it as any purchase order, then record what the supplier shipped:
+
+```ts
+const dropShip = await admin.purchasing.links.dropShip.get(purchaseOrderId);
+// { orderCode: 'WT-0042', address: { fullName: 'Anna de Vries', streetLine1: 'Keizersgracht 12',
+//   city: 'Amsterdam', postalCode: '1015 AB', countryCode: 'NL', … },
+//   lines: [{ purchaseOrderLineId, orderLineId, sku: 'TEE-M', orderedBaseQuantity: 2,
+//             shippedBaseQuantity: 0, toShipBaseQuantity: 2 }] }
+
+const { fulfillment, closedPurchaseOrder } = await admin.purchasing.links.dropShip.recordShipment(
+  { purchaseOrderId, carrier: 'PostNL', trackingCode: '3SABC1234567' },
+  { idempotencyKey: 'po-0009-shipment-1' }
+);
+// fulfillment: { state: 'Shipped', method: 'PostNL', trackingCode: … }
+// closedPurchaseOrder: true once no line can ship more.
+```
+
+- **What it does.** A fulfilment of the customer's lines with the `drop-ship` handler, moved to
+  `Shipped` at once, so the customer gets the usual shipping email. Its `method` is the carrier
+  (else "Shipment" in the store's language) and never names the supplier, since the shopper reads
+  it. No stock movement is written for those lines. Each line's cost (`OrderLine.customFields.cost`)
+  becomes the purchase order line's base-unit cost in the order's currency, at the platform rate of
+  `shippedOn` (or of up to 7 days earlier), or at the `fxRate` given (`ManageInventoryCost`). The
+  purchase order closes once no line can ship more; what no customer line waits for (whole
+  purchase units beyond the customer's quantity) is cancelled as a close short would. Its links
+  read `partially_shipped` / `shipped`.
+- **Which store.** The address, the PDF and the shipment belong to the customer order's store: from
+  another store of the legal entity, `get` answers `orderCode` and `address` null, the document is
+  `PURCHASE_ORDER_DOCUMENT_NOT_FOUND`, and `recordShipment` is `PURCHASE_LINK_INVALID`.
+- **Order edits.** A drop-ship line's quantity cannot be raised past what its supplier was asked
+  for (`DROP_SHIP_QUANTITY_RAISED`, 422): the extra units would be neither reserved nor ordered.
+- **How much.** `lines` left out ships everything each line still has to ship. A line ships at most
+  `toShipBaseQuantity`: what it still orders, at most what the customer's line still waits for
+  (`DROP_SHIP_SHIPMENT_EXCEEDS_ORDERED`, 422, `details[0].maxBaseQuantity`).
+- **The key is required.** A retried shipment never fulfils twice.
+- **Elsewhere.** A drop-ship line cannot be fulfilled from a warehouse (`LINE_DROP_SHIPPED`), and a
+  drop-ship purchase order cannot be received (`DROP_SHIP_PO_NOT_RECEIVABLE`), given lines by
+  hand, duplicated or cancelled after a shipment.
+- **Access.** `recordShipment` needs `UpdatePurchaseOrder` and `UpdateOrder`
+  (`DROP_SHIP_SHIPMENT_DENIED`, 403), and a credential not restricted to stock locations
+  (`LOCATION_NOT_ALLOWED`); `get` needs `ReadPurchaseOrder`. Other refusals:
+  `PURCHASE_ORDER_INVALID_TRANSITION` (not sent), `PURCHASE_LINK_INVALID` (400),
+  `DROP_SHIP_FULFILLMENT_REFUSED`, `FX_RATE_UNAVAILABLE`, `FX_RATE_OVERRIDE_NOT_ALLOWED` (403),
+  `MANAGED_BY_PROVIDER`.
+
+Needs an engine with step 5.2; against an older engine the request fails GraphQL validation
+(`GRAPHQL_VALIDATION_FAILED`), and its drop-ship links read `open` whatever shipped.
+
+#### Receipts
+
+Receiving goods against the legal entity's sent purchase orders: one receipt is the goods ONE
+supplier delivered at ONE stock location, covering lines of one or more of its orders; a reversal
+takes accepted goods of a receipt back out when the receipt was wrong.
+
+```ts
+// What can be received at a location (or for one supplier or order), with the scan keys.
+const lines = await admin.purchasing.receipts.receivable({ stockLocationId });
+// [{ purchaseOrderCode: 'PO-2026-0001', purchaseOrderLineId, sku, supplierSku, supplierBarcode,
+//    gtin, purchaseUnitLabel: 'box of 6', purchaseUnitFactor: 6, remainingBaseQuantity: 12,
+//    toleranceBaseQuantity: 1, maxAcceptedBaseQuantity: 13, expectedOn, … }]
+
+const receipt = await admin.purchasing.receipts.post(
+  {
+    supplierDeliveryRef: 'DN-4711',
+    lines: [
+      { purchaseOrderLineId, acceptedBaseQuantity: 10, rejectedBaseQuantity: 2, rejectReason: 'Damaged' },
+    ],
+  },
+  { idempotencyKey: idempotencyKey() } // required
+);
+// { code: 'GR-2026-0001', kind: 'receipt', receivedOn: '2026-10-13', lines: [{ acceptedBaseQuantity,
+//   rejectedBaseQuantity, landedUnitCost: '1300.000000', fxRate: '1.00000000', … }], … }
+
+await admin.purchasing.receipts.reverse(
+  { goodsReceiptId: receipt.id, reason: 'Booked on the wrong order' }, // every line, or `lines`
+  { idempotencyKey: idempotencyKey() } // required
+);
+
+const { items } = await admin.purchasing.receipts.list({ purchaseOrderId, limit: 25 });
+const one = await admin.purchasing.receipts.get(receipt.id);
+```
+
+- **Quantities are base (stock) units.** `acceptedBaseQuantity` enters stock at the location (a
+  `purchase_receipt` movement with the receipt's number as its reference, which
+  `stock.level_changed` names in `reference_document`); `rejectedBaseQuantity` moves nothing and
+  stays open on the order line until a return to the supplier resolves it (a reason is required).
+- **Tolerance.** A line may accept its remainder plus the supplier's over-receipt tolerance (the
+  purchasing default when the supplier has none): `maxAcceptedBaseQuantity`. Beyond it the poster
+  needs `ReceiveOverTolerance` and an `overReceiptReason` on the line, else
+  `RECEIPT_EXCEEDS_TOLERANCE` (422, `details` per line).
+- **What a receipt does.** In one transaction: the stock movements, the weighted average cost
+  (`inventory_cost.changed`), each order line's received quantity, the cancellation of a line's
+  remainder when the supplier ships no backorders, the order closing when nothing more is to come,
+  the incoming stock, and `goods_receipt.posted`. A reversal takes the goods back out at each
+  line's original landed cost and reopens a closed order; it is refused `STOCK_WOULD_GO_NEGATIVE`
+  (422) when the goods are no longer on hand: move or recount stock first.
+- **Exchange rates.** A line priced in another currency than the purchasing one converts at the
+  platform rate of `receivedOn` (or the latest of the 7 days before); none is
+  `FX_RATE_UNAVAILABLE` (422, the key is released: retry once the rates synced). A holder of
+  `ManageInventoryCost` may state the rate (`fxRates: [{ currencyCode, rate }]`,
+  `FX_RATE_OVERRIDE_NOT_ALLOWED` otherwise).
+- **Access.** Every method needs the Purchasing plugin and purchasing switched on for the legal
+  entity (`PURCHASING_NOT_ENABLED`, 422). Reads need `ReadPurchaseOrder` or
+  `ReceivePurchaseOrder`; `post` and `reverse` need `ReceivePurchaseOrder` on **every** store of
+  the legal entity (`SHARED_SELLER_NOT_ALLOWED`, 403), at a location of the store the caller may
+  act at (`LOCATION_NOT_ALLOWED`, 403: a restricted credential's locations, a warehouse staff
+  member's assigned warehouses) that the legal entity owns. An app or token that owns a variant's
+  stock refuses anyone else's receipt of it (`FIELD_GROUP_LOCKED`).
+- **`post` and `reverse` require `{ idempotencyKey }`** (the type says so): a retried receipt
+  answers the first one and never books the stock twice.
+
+These methods need an engine with supplier returns (purchase-orders step 3.5): every receipt they
+answer selects the two returned quantities below. Against an older engine, goods receipts without
+supplier returns included, the request fails GraphQL validation (`GRAPHQL_VALIDATION_FAILED`), so
+upgrade the engine before this release of the SDK.
+
+A receipt line also answers `returnedBaseQuantity` (accepted goods sent back to the supplier from
+stock, which a reversal can no longer take back) and `returnedRejectedBaseQuantity` (refused goods
+sent back), counting every return not cancelled ([Returns](#returns)).
+
+#### Returns
+
+Goods going back to a supplier: refused goods from a goods receipt (`origin: 'rejected'`, they
+never entered stock), or goods found faulty later (`origin: 'on_hand'`, they leave stock when the
+return ships). A return goes to ONE supplier from ONE stock location; each line names the goods
+receipt line its goods came in on, which fixes the cost they leave at.
+
+```ts
+const draft = await admin.purchasing.returns.create({
+  origin: 'rejected',
+  supplierReference: 'RMA-88213', // the supplier's return authorisation, optional
+  lines: [{ goodsReceiptLineId, baseQuantity: 2, outcome: 'credit_expected' }],
+});
+// { code: 'RS-2026-0001', status: 'draft', lines: [{ reason: 'Damaged' /* the receipt's */, … }] }
+
+const shipped = await admin.purchasing.returns.ship(
+  draft.id,
+  { carrier: 'PostNL', trackingCode: '3S…' }, // notifySupplier: false skips the email
+  { idempotencyKey: idempotencyKey() } // required
+);
+// { status: 'shipped', shippedAt, documentIssuedAt, … } and the supplier gets the PDF by email
+
+await admin.purchasing.returns.resolveLine({
+  supplierReturnLineId: shipped.lines[0].id,
+  resolution: 'credited', // or 'replaced', 'written_off'
+  creditAmount: 2600, // informational, minor units of the line's currencyCode
+  resolutionReference: 'CN-77',
+});
+// the last line resolved: { status: 'resolved', resolvedAt, … }
+
+await admin.purchasing.returns.update(id, { trackingCode: '3S…' }); // a draft: lines too
+await admin.purchasing.returns.cancel(id, { reason: 'Raised twice' }); // a draft only
+const { url } = await admin.purchasing.returns.document(shipped.id); // five minutes
+const { items } = await admin.purchasing.returns.list({ status: 'shipped', limit: 25 });
+```
+
+- **Lifecycle.** `draft → shipped → resolved`, and `draft → cancelled` (the meta catalog serves
+  it as `transitions.supplierReturn`). A draft's lines, location, notes and references can change;
+  a shipped return keeps what left, and changes only its carrier, tracking code and supplier
+  reference. A shipped return is never cancelled (`SUPPLIER_RETURN_INVALID_TRANSITION`, 422).
+- **What a line may return.** At most what its receipt line still holds: its refused units for a
+  return of refused goods, its accepted units less reversals for goods from stock, in both cases
+  less the other returns not cancelled (a draft holds its quantity). More is
+  `SUPPLIER_RETURN_EXCEEDS_RETURNABLE` (422, `details` per line with `returnableBaseQuantity`).
+- **What a ship does.** In one transaction: goods from stock leave the location (a
+  `supplier_return` movement with the return's number as its reference) at their receipt lines'
+  landed cost, which the weighted average takes out (`inventory_cost.changed`); refused goods move
+  nothing. On the purchase order lines, refused goods credited or written off are cancelled (an
+  order with nothing more to come closes), refused goods to be replaced stay open, and goods from
+  stock to be replaced are open again (`returnedForReplacementBaseQuantity`; a closed order
+  reopens). Then `supplier_return.status_changed`, the PDF (in the supplier's language), and after
+  the commit the "Supplier Return Sent" email unless `notifySupplier: false`. Below zero is
+  `STOCK_WOULD_GO_NEGATIVE` (422): move or recount stock first.
+- **Resolutions.** A line expecting a credit is `credited` or `written_off`; one expecting a
+  replacement is `replaced`, `credited` or `written_off` (the last two cancel what the replacement
+  kept open on the order line); a write-off is `written_off`. A line is resolved once.
+- **Access.** Every method needs the Purchasing plugin and purchasing switched on for the legal
+  entity (`PURCHASING_NOT_ENABLED`, 422). Reads and `document` need `ReadPurchaseOrder` or
+  `ReceivePurchaseOrder`; `create` needs `CreatePurchaseOrder`, `update`, `resolveLine` and
+  `cancel` `UpdatePurchaseOrder`, and `ship` `ReceivePurchaseOrder`, each on **every** store of the
+  legal entity (`SHARED_SELLER_NOT_ALLOWED`, 403), at a location the caller may act at
+  (`LOCATION_NOT_ALLOWED`, 403). An app or token that owns a variant's stock refuses anyone else's
+  ship of it from stock (`FIELD_GROUP_LOCKED`).
+- **The email.** It goes to the supplier's order contact, else its order email; before anything is
+  written the ship is refused `SUPPLIER_HAS_NO_ORDER_EMAIL` or `SUPPLIER_EMAIL_UNDELIVERABLE` (the
+  store's "Supplier Return Sent" email off, without a recipient, or no email delivery), and
+  `PRIVATE_STORAGE_UNCONFIGURED` without a private document bucket (all 422, `details[0]` with
+  `field: 'notifySupplier'` for the first two). With `notifySupplier: false` a deployment without
+  the bucket ships with no document (`document` is then `SUPPLIER_RETURN_DOCUMENT_NOT_FOUND`).
+- **`ship` requires `{ idempotencyKey }`** (the type says so): a retried ship answers the first
+  one and never takes the goods out of stock twice. The other writes take an optional key.
+
+These methods need an engine with supplier returns (purchase-orders phase 3, step 3.5). Against an
+older engine the request fails GraphQL validation (`GRAPHQL_VALIDATION_FAILED`).
+
+##### Landed charges
+
+Freight, duty and fees paid to get a receipt's goods in, spread over its lines and taken into their
+weighted average cost.
+
+```ts
+const receipt = await admin.purchasing.receipts.charges.add(
+  {
+    goodsReceiptId,
+    kind: 'freight', // freight | duty | fee | other
+    amount: 12500, // whole minor units of currencyCode
+    currencyCode: 'USD', // the purchasing currency when left out
+    allocation: 'value', // value (default) | quantity | weight
+    incurredOn: '2026-10-12', // today in the legal entity's zone when left out
+    payeeName: 'DHL Freight', // or payeeSupplierId
+  },
+  { idempotencyKey: idempotencyKey() } // optional
+);
+// { …receipt, lines: [{ landedUnitCost: '1150.000000', … }],
+//   charges: [{ id, kind: 'freight', amountEntityCurrency: '11500.000000', fxRate: '0.92000000',
+//     allocations: [{ goodsReceiptLineId, baseQuantity: 10, amount: '11500.000000',
+//       unitCostDelta: '1150.000000' }], removedAt: null, … }] }
+
+await admin.purchasing.receipts.charges.remove({ chargeId, reason: 'Billed twice' });
+const { charges } = (await admin.purchasing.receipts.get(goodsReceiptId)) ?? { charges: [] };
+```
+
+- **Allocation.** Over the units each line still holds (accepted less reversed): by value (each
+  line's quantity × unit cost in the purchasing currency), by quantity, or by weight (package grams
+  × quantity; a variant without a weight refuses the charge, `LANDED_CHARGE_WEIGHT_MISSING`, 422,
+  `details` per variant). One rounding per line, the remainder on the largest line.
+- **Cost.** The share on units still on hand revalues the weighted average; the share on units
+  sold since is recorded as `unabsorbedAmount` on the cost entry (`inventory_cost.changed`, cause
+  `landed_charge`), never pushed into any cost of goods sold. Each line's `landedUnitCost` rises by
+  its share per unit, so a later reversal or return takes the units out at the landed cost.
+- **Removal** takes the share still on the lines' units back out of the average (units sold since
+  keep theirs: a negative `unabsorbedAmount`), lowers each line's landed cost by what the charge
+  added, and keeps the charge with `removedAt` and the reason. A charge is never deleted.
+- **Exchange rates.** A charge in another currency converts at the platform rate of `incurredOn`
+  (or the latest of the 7 days before); none is `FX_RATE_UNAVAILABLE` (422: retry once the rates
+  synced, or state `fxRate`).
+- **Access.** Both writes need `ManageInventoryCost` on **every** store of the legal entity
+  (`SHARED_SELLER_NOT_ALLOWED`, 403). Refusals: `GOODS_RECEIPT_NOT_FOUND`, `LANDED_CHARGE_NOT_FOUND`
+  (404), `LANDED_CHARGE_INVALID` (400: a value, a reversal named, a day ahead),
+  `LANDED_CHARGE_NOTHING_TO_ALLOCATE` (422: every unit reversed, or no value to allocate by),
+  `LANDED_CHARGE_ALREADY_REMOVED` (422), `SUPPLIER_NOT_FOUND` (404, the payee),
+  `MANAGED_BY_PROVIDER` (422).
+
+These methods need an engine with landed charges (purchase-orders step 3.4); against an older
+engine the request, `receipts.get` included, fails GraphQL validation (`GRAPHQL_VALIDATION_FAILED`).
+
 ### Errors
 
 One hierarchy, all re-exported from this package so you need no direct dependency on