@revenexx/node 0.1.1 → 0.2.0

package/dist/services/orders.d.ts

@@ -3,11 +3,15 @@ import { Models } from '../models.js';
 import { OrderStatus } from '../enums/order-status.js';
 import { OrderPaymentStatus } from '../enums/order-payment-status.js';
 import { OrderFulfillmentStatus } from '../enums/order-fulfillment-status.js';
+import { OrderVocabularyTone } from '../enums/order-vocabulary-tone.js';
 import { OrdersVocabulariesGetName } from '../enums/orders-vocabularies-get-name.js';
 import { OrderCommentVisibility } from '../enums/order-comment-visibility.js';
 import { OrderReturnSettlement } from '../enums/order-return-settlement.js';
 import { OrderReturnRefusal } from '../enums/order-return-refusal.js';
 import '../query.js';
+import '../enums/accept-line-decision.js';
+import '../enums/accept-result-origin.js';
+import '../enums/accept-result-status.js';
 import '../enums/address-type-row-tone.js';
 import '../enums/address-type-row-create-request-tone.js';
 import '../enums/address-type-row-update-request-tone.js';
@@ -21,12 +25,23 @@ import '../enums/approval-rule-update-request-approver-type.js';
 import '../enums/approval-rule-update-request-condition.js';
 import '../enums/approval-rule-update-request-effect.js';
 import '../enums/assets-source.js';
+import '../enums/assignment-role-tone.js';
+import '../enums/assignment-role-create-request-tone.js';
+import '../enums/assignment-role-update-request-tone.js';
+import '../enums/attach-request-direction.js';
+import '../enums/attach-request-visibility.js';
 import '../enums/attribute-value-bucket.js';
 import '../enums/auth-mail-source.js';
+import '../enums/auth-mfa-challenge-request-factor.js';
 import '../enums/recovery-mail-source.js';
 import '../enums/registration-status.js';
+import '../enums/availability-state-tone.js';
+import '../enums/banner-draft-layout.js';
+import '../enums/banner-draft-update-request-layout.js';
 import '../enums/budget-change-reason.js';
 import '../enums/budget-movement-result-status.js';
+import '../enums/budget-release-scope.js';
+import '../enums/budget-release-status.js';
 import '../enums/cart-status.js';
 import '../enums/cart-merge-strategy.js';
 import '../enums/cart-price-snapshot-mode.js';
@@ -54,18 +69,44 @@ import '../enums/channel-vocabulary-tone.js';
 import '../enums/channel-vocabulary-name.js';
 import '../enums/channel-vocabulary-source.js';
 import '../enums/channel-vocabulary-ref-name.js';
+import '../enums/consent-record-action.js';
+import '../enums/consent-record-surface.js';
+import '../enums/consent-record-create-request-action.js';
+import '../enums/consent-record-create-request-surface.js';
+import '../enums/consent-vocabulary-source.js';
+import '../enums/contact-order-approval-mode.js';
 import '../enums/contact-registration-status.js';
 import '../enums/contact-status.js';
 import '../enums/contact-activity-kind.js';
+import '../enums/order-approval-mode.js';
 import '../enums/contact-create-request-registration-status.js';
 import '../enums/contact-event-kind-tone.js';
 import '../enums/contact-event-kind-create-request-tone.js';
 import '../enums/contact-event-kind-update-request-tone.js';
-import '../enums/contact-update-request-registration-status.js';
+import '../enums/contact-point-kind-tone.js';
+import '../enums/contact-point-kind-create-request-tone.js';
+import '../enums/contact-point-kind-update-request-tone.js';
+import '../enums/cookie-kind.js';
+import '../enums/cookie-create-request-kind.js';
+import '../enums/cookie-update-request-kind.js';
 import '../enums/cost-center-budget-type.js';
+import '../enums/cost-center-create-request-budget-type.js';
 import '../enums/cost-center-restriction-type.js';
 import '../enums/cost-center-restriction-create-request-type.js';
 import '../enums/cost-center-restriction-update-request-type.js';
+import '../enums/cost-center-update-request-budget-type.js';
+import '../enums/cost-centers-vocabulary-tone.js';
+import '../enums/cost-centers-vocabulary-name.js';
+import '../enums/cost-centers-vocabulary-source.js';
+import '../enums/cost-centers-vocabulary-summary-name.js';
+import '../enums/direct-order-status.js';
+import '../enums/document-source.js';
+import '../enums/document-visibility.js';
+import '../enums/document-kind-tone.js';
+import '../enums/document-vocabulary-default-tone.js';
+import '../enums/document-vocabulary-name.js';
+import '../enums/document-vocabulary-source.js';
+import '../enums/document-vocabulary-tone.js';
 import '../enums/payment-fee-type.js';
 import '../enums/payment-method-kind.js';
 import '../enums/form-status.js';
@@ -75,6 +116,7 @@ import '../enums/form-submission-prune-request-status.js';
 import '../enums/forms-vocabulary-tone.js';
 import '../enums/forms-vocabulary-name.js';
 import '../enums/forms-vocabulary-summary-name.js';
+import '../enums/inventory-receive-warning-code.js';
 import '../enums/inventory-vocabulary-default-tone.js';
 import '../enums/inventory-vocabulary-source.js';
 import '../enums/cart-io-apply-mode.js';
@@ -82,6 +124,7 @@ import '../enums/cart-io-direction.js';
 import '../enums/cart-io-entity.js';
 import '../enums/io-profile-resource-apply-mode.js';
 import '../enums/io-profile-resource-direction.js';
+import '../enums/inventory-unorderable-reason.js';
 import '../enums/lifecycle-stage-tone.js';
 import '../enums/lifecycle-stage-create-request-tone.js';
 import '../enums/lifecycle-stage-update-request-tone.js';
@@ -98,22 +141,33 @@ import '../enums/markets-vocabulary-tone.js';
 import '../enums/markets-vocabulary-name.js';
 import '../enums/markets-vocabulary-source.js';
 import '../enums/markets-vocabulary-summary-name.js';
+import '../enums/note-request-visibility.js';
 import '../enums/order-cancellation-scope.js';
+import '../enums/order-discount-target.js';
+import '../enums/order-discount-effect-kind.js';
+import '../enums/order-discount-placement.js';
+import '../enums/order-discount-source.js';
+import '../enums/order-discount-value-type.js';
 import '../enums/order-item-type.js';
 import '../enums/order-list-kind-tone.js';
 import '../enums/order-list-kind-row-tone.js';
+import '../enums/order-list-skip-reason.js';
 import '../enums/order-list-cart-mode.js';
 import '../enums/order-list-vocabulary-default-tone.js';
 import '../enums/order-list-vocabulary-name.js';
 import '../enums/order-list-vocabulary-source.js';
 import '../enums/order-list-vocabulary-tone.js';
+import '../enums/order-return-refund-mode.js';
 import '../enums/order-return-status.js';
-import '../enums/order-vocabulary-tone.js';
 import '../enums/order-vocabulary-name.js';
 import '../enums/order-vocabulary-source.js';
 import '../enums/order-vocabulary-summary-name.js';
 import '../enums/order-resolution-stage.js';
+import '../enums/organization-credit-limit-mode.js';
+import '../enums/organization-shipping-advice.js';
 import '../enums/organization-status.js';
+import '../enums/credit-limit-mode.js';
+import '../enums/shipping-advice.js';
 import '../enums/page-status.js';
 import '../enums/pages-vocabulary-app.js';
 import '../enums/pages-vocabulary-tone.js';
@@ -135,6 +189,7 @@ import '../enums/price-entries-adjust-response-rounding-mode.js';
 import '../enums/price-entries-bulk-mode.js';
 import '../enums/price-rounding-mode.js';
 import '../enums/price-entry-type.js';
+import '../enums/price-line-price-reason.js';
 import '../enums/price-list-status.js';
 import '../enums/price-list-tax-basis.js';
 import '../enums/price-currency-source.js';
@@ -146,22 +201,86 @@ import '../enums/price-vocabulary-tone.js';
 import '../enums/price-vocabulary-name.js';
 import '../enums/price-vocabulary-source.js';
 import '../enums/price-vocabulary-ref-name.js';
+import '../enums/procurement-vocabulary-default-tone.js';
+import '../enums/procurement-vocabulary-name.js';
+import '../enums/procurement-vocabulary-source.js';
+import '../enums/procurement-vocabulary-summary-name.js';
+import '../enums/procurement-vocabulary-value-tone.js';
 import '../enums/product-categories-source.js';
 import '../enums/product-grid-column-source.js';
 import '../enums/product-label-source.js';
 import '../enums/product-label-attribute-source.js';
 import '../enums/products-kind.js';
+import '../enums/promotion-condition-match.js';
+import '../enums/promotion-reach.js';
+import '../enums/promotion-recurrence-kind.js';
+import '../enums/promotion-return-behaviour.js';
+import '../enums/promotion-status.js';
+import '../enums/promotion-bundle-allocation.js';
+import '../enums/promotion-bundle-patch-allocation.js';
+import '../enums/promotion-bundle-write-allocation.js';
+import '../enums/promotion-condition-kind.js';
+import '../enums/promotion-condition-match-mode.js';
+import '../enums/promotion-condition-patch-kind.js';
+import '../enums/promotion-condition-patch-match-mode.js';
+import '../enums/promotion-condition-write-kind.js';
+import '../enums/promotion-condition-write-match-mode.js';
+import '../enums/promotion-effect-kind.js';
+import '../enums/promotion-effect-target-scope.js';
+import '../enums/promotion-effect-unit-choice.js';
+import '../enums/promotion-effect-value-type.js';
+import '../enums/promotion-effect-patch-kind.js';
+import '../enums/promotion-effect-patch-target-scope.js';
+import '../enums/promotion-effect-patch-unit-choice.js';
+import '../enums/promotion-effect-patch-value-type.js';
+import '../enums/promotion-effect-write-kind.js';
+import '../enums/promotion-effect-write-target-scope.js';
+import '../enums/promotion-effect-write-unit-choice.js';
+import '../enums/promotion-effect-write-value-type.js';
+import '../enums/promotion-patch-condition-match.js';
+import '../enums/promotion-patch-reach.js';
+import '../enums/promotion-patch-recurrence-kind.js';
+import '../enums/promotion-patch-return-behaviour.js';
+import '../enums/promotion-patch-status.js';
+import '../enums/promotion-release-request-reason.js';
+import '../enums/promotion-write-condition-match.js';
+import '../enums/promotion-write-reach.js';
+import '../enums/promotion-write-recurrence-kind.js';
+import '../enums/promotion-write-return-behaviour.js';
+import '../enums/promotion-write-status.js';
+import '../enums/punchout-entry-probe-result-entry-probe-status.js';
+import '../enums/punchout-entry-test-result-protocol.js';
+import '../enums/punchout-field-mapping-import-request-protocol.js';
+import '../enums/punchout-return-preview-protocol.js';
 import '../enums/purchase-request-status.js';
 import '../enums/purchase-request-event-name.js';
 import '../enums/purchase-request-item-type.js';
 import '../enums/purchase-request-item-create-request-type.js';
 import '../enums/purchase-request-item-update-request-type.js';
+import '../enums/purpose-legal-basis.js';
+import '../enums/purpose-create-request-legal-basis.js';
+import '../enums/purpose-update-request-legal-basis.js';
+import '../enums/quote-origin.js';
+import '../enums/quote-status.js';
+import '../enums/quote-attachment-direction.js';
+import '../enums/quote-attachment-visibility.js';
+import '../enums/quote-detail-origin.js';
+import '../enums/quote-detail-status.js';
+import '../enums/quote-event-visibility.js';
+import '../enums/quote-item-decision.js';
+import '../enums/quote-item-price-reason.js';
+import '../enums/quote-line-input-price-reason.js';
+import '../enums/redemption-state.js';
 import '../enums/reorder-point-source.js';
 import '../enums/reservation-status.js';
 import '../enums/price-on-request-reason.js';
 import '../enums/price-tax-basis.js';
 import '../enums/price-tax-basis-source.js';
 import '../enums/role-catalog-response-source.js';
+import '../enums/sales-rep-vocabulary-default-tone.js';
+import '../enums/sales-rep-vocabulary-source.js';
+import '../enums/seed-request-mode.js';
+import '../enums/seed-result-mode.js';
 import '../enums/segment-rule-match.js';
 import '../enums/segment-member-source.js';
 import '../enums/segment-rule-operator.js';
@@ -191,14 +310,35 @@ import '../enums/shipping-vocabulary-tone.js';
 import '../enums/shipping-weight-unit-create-request-tone.js';
 import '../enums/shipping-weight-unit-row-tone.js';
 import '../enums/shipping-weight-unit-update-request-tone.js';
+import '../enums/stacking-group-mode.js';
+import '../enums/stacking-group-patch-mode.js';
+import '../enums/stacking-group-write-mode.js';
 import '../enums/stock-movement-type.js';
 import '../enums/store-asset-request-visibility.js';
 import '../enums/submit-item-type.js';
 import '../enums/submit-result-outcome.js';
+import '../enums/tag-manager-container-check-reason.js';
+import '../enums/tag-manager-marketing-tag-kind.js';
+import '../enums/tag-manager-marketing-tag-load.js';
+import '../enums/tag-manager-marketing-tag-input-kind.js';
+import '../enums/tag-manager-marketing-tag-input-load.js';
+import '../enums/tag-manager-trigger-kind.js';
+import '../enums/tag-manager-trigger-input-kind.js';
+import '../enums/tag-manager-variable-kind.js';
+import '../enums/tag-manager-variable-input-kind.js';
 import '../enums/validation-failed-response-status.js';
+import '../enums/vendor-legal-basis-override.js';
+import '../enums/vendor-create-request-legal-basis-override.js';
+import '../enums/vendor-update-request-legal-basis-override.js';
 import '../enums/vocabulary-default-tone.js';
 import '../enums/vocabulary-source.js';
 import '../enums/vocabulary-tone.js';
+import '../enums/voucher-status.js';
+import '../enums/voucher-batch-status.js';
+import '../enums/voucher-batch-patch-status.js';
+import '../enums/voucher-batch-write-status.js';
+import '../enums/voucher-patch-status.js';
+import '../enums/voucher-write-status.js';
 import '../enums/attribute-boolean-status.js';
 import '../enums/attribute-datetime-status.js';
 import '../enums/attribute-email-status.js';
@@ -246,7 +386,7 @@ declare class Orders {
     client: Client;
     constructor(client: Client);
     /**
-     * The route behind every order overview: the open orders of one customer, everything on hold, everything a market placed last week, or the one order somebody is quoting a number for (?number=ORD-000123 — the number is not the id, and this is how one becomes the other). The order LIST: the order rows without their positions, shipments, returns or cancellations — read GET /orders/{id} for the aggregate of one. Every parameter below is an exact match on the column it names, and combining them is an AND. Two kinds of key are not offered: one that names NO column is dropped silently, so a mistyped ?stauts=placed answers 200 with the whole list (compare the 'filter' echo against what you sent — no status code reports it), and the jsonb columns buyer, billing_address, shipping_address, payment, shipping, user_data and metadata reach the database as a text comparison and answer 400 invalid_value for anything that is not a whole JSON document.
+     * The route behind every order overview: the open orders of one customer, everything on hold, everything a market placed last week, or the one order somebody is quoting a number for (?number=ORD-000123 — the number is not the id, and this is how one becomes the other). The order LIST: the order rows without their positions, shipments, returns or cancellations — read GET /orders/{id} for the aggregate of one. Every parameter below is an exact match on the column it names, and combining them is an AND. Two kinds of key are not offered: one that names NO column is not a filter — the SDK release after app-sdks#30 answers it 400 unknown_filter, and until then a mistyped ?stauts=placed is dropped and answers the whole list (compare the 'filter' echo against what you sent) — and the jsonb columns buyer, billing_address, shipping_address, payment, shipping, user_data and metadata reach the database as a text comparison and answer 400 invalid_value for anything that is not a whole JSON document.
      *
      * @param {string} params.id - Filter to exactly one order. GET /orders/{id} is the direct form and answers the aggregate; this exists because the list honours it too. Primary key of the order, and the id every other route takes. Not the order number.
      * @param {string} params.number - Look an order up by its NUMBER — the one filter a service desk starts from, and the way to turn the number a customer quotes into the uuid every other route wants. Exact match; there is no substring search on this API. The order number a human quotes — drawn from the tenant's order range at place-time, unique per tenant and never reused. It is NOT the id: every route addresses an order by uuid, and GET /orders?number=… is how a number becomes one.
@@ -265,12 +405,21 @@ declare class Orders {
      * @param {string} params.holdReason - Filter to rows whose `hold_reason` is exactly this value. Why the order is held, in the words the shipping guard quotes back. Null when it is not held — releasing a hold clears it.
      * @param {number} params.itemCount - Filter to rows whose `item_count` is exactly this value. The summed ORDERED quantity over all positions, rounded to a whole number — a headline figure for a list, computed once at place-time. It is deliberately not reduced when something is cancelled or returned; the positions carry that arithmetic.
      * @param {number} params.subtotal - Filter to rows whose `subtotal` is exactly this value. NET total of the positions (the sum of their line_total), COMPUTED here at place-time. In `currency`, four decimal places. A caller cannot set it.
-     * @param {number} params.shippingTotal - Filter to rows whose `shipping_total` is exactly this value. NET shipping cost, taken from shipping.price or, when the snapshot carries no price, from the request's shipping_total. In `currency`.
+     * @param {number} params.discountTotal - Filter to rows whose `discount_total` is exactly this value. Every discount a promotion took off this order, summed: the positions' discounts, a head-level voucher distributed across them, a discount placed as its own position, and any reduction of the shipping charge. COMPUTED here from the components the caller evaluated — a caller cannot set it. `subtotal` stays the UNDISCOUNTED sum, so the two together say what was charged and what was given away.
+     * @param {number} params.shippingTotal - Filter to rows whose `shipping_total` is exactly this value. NET shipping cost, taken from shipping.price or, when the snapshot carries no price, from the request's shipping_total. In `currency`. This is the price BEFORE any promotion reduced it; the reduction is a row in the discount components.
+     * @param {number} params.shippingTaxRate - Filter to rows whose `shipping_tax_rate` is exactly this value. The tax percentage the shipping charge was taxed at, frozen at place-time (19 means 19 %). Stored rather than only used, because otherwise nobody could say afterwards how much of tax_total was shipping — which an ERP export of a discounted shipping charge needs.
+     * @param {number} params.shippingTaxAmount - Filter to rows whose `shipping_tax_amount` is exactly this value. Tax on the shipping charge, computed on what is OWED after any promotion reduced it. Part of tax_total, and stored separately so the shipping line can be stated on its own.
+     * @param {number} params.paymentFeeAmount - Filter to rows whose `payment_fee_amount` is exactly this value. The payment surcharge this order was placed with, NET — what the payments app computed for the chosen method (a fixed amount, or a share of the order). Zero for a method that charges nothing, which is most of them. Passed in with the payment arrangement the way the shipping price is, and stored rather than folded into the `payment` blob: a grand_total that silently included a fee nobody could point at is a reconciliation nobody can finish.
+     * @param {number} params.paymentFeeTaxRate - Filter to rows whose `payment_fee_tax_rate` is exactly this value. The rate the payment surcharge was taxed at, frozen at place-time (19 means 19 %). A surcharge is a Nebenleistung and is taxed like one.
+     * @param {number} params.paymentFeeTaxAmount - Filter to rows whose `payment_fee_tax_amount` is exactly this value. Tax on the payment surcharge, part of tax_total and stored separately so the fee can be stated on its own line of an invoice or an export.
      * @param {number} params.taxTotal - Filter to rows whose `tax_total` is exactly this value. All tax on this order: the positions' tax_amount plus the tax on shipping (shipping_total × shipping.tax_rate). COMPUTED here — a caller cannot set it.
-     * @param {number} params.grandTotal - Filter to rows whose `grand_total` is exactly this value. What the buyer owes: subtotal + shipping_total + tax_total, COMPUTED by this app and NEVER taken from the caller — trusting a supplied total is how inconsistent orders happened. This is the number the approval threshold is compared against and the number the revenue rollup sums.
+     * @param {number} params.grandTotal - Filter to rows whose `grand_total` is exactly this value. What the buyer owes: the positions' discounted totals plus the discounted shipping charge plus the payment surcharge plus tax_total, COMPUTED by this app and NEVER taken from the caller — trusting a supplied total is how inconsistent orders happened. This is the number the approval threshold is compared against and the number the revenue rollup sums.
      * @param {string} params.placedAt - Exact timestamp equality — this API has no range filter. To bound a period, sort with `order` and page. When the order was PLACED. Null while it is pending approval: an order awaiting sign-off exists but was never placed, and that is exactly the difference this field records.
      * @param {string} params.completedAt - Exact timestamp equality — this API has no range filter. To bound a period, sort with `order` and page. When the order was closed — by a full shipment, by payment or by hand, depending on the tenant's auto_complete_on. Null until then.
      * @param {string} params.cancelledAt - Exact timestamp equality — this API has no range filter. To bound a period, sort with `order` and page. When the order was cancelled, whether by a full cancel or by the last open quantity being cancelled position by position. Null otherwise.
+     * @param {string} params.externalId - Filter to rows whose `external_id` is exactly this value. The key this order has in the system that OWNS it — the ERP's own handle on the sales order, which is what a write-back addresses. Distinct from `external_ref`, which is the readable ORDER NUMBER that system quotes at a human, and from `number`, which is the one this app issued. Unique per tenant where set, so a retried import that sends the same key again is refused rather than founding a second order. Null for an order the shop owns.
+     * @param {string} params.sourceSyncedAt - Exact timestamp equality — this API has no range filter. To bound a period, sort with `order` and page. When this order was last confirmed against its source. What a delta run asks for changes since, and what tells an operator that a feed has gone quiet — an edit made here does not touch it, because it says when the SOURCE was last seen, not when the row changed. Null for a order no source owns.
+     * @param {string} params.requestedDeliveryDate - The dispatch list for one day: every order the buyer asked to have on it. Exact equality on the DAY — there is no range filter here, so a week is seven calls or a sort with `order=requested_delivery_date.asc` and paging. It answers about the ORDER's date; a position that named its own is not found this way. The calendar day the BUYER asked to be delivered on, as a date and not a moment — a buyer asks for Tuesday, not for Tuesday at 14:03 in a timezone nobody named. It is a wish and nothing here judges it: a date in the past, a weekend or a day inside the lead time is stored as sent, because what is deliverable is the merchant's answer and this app reads neither stock nor carrier calendar. The positions carry their own, and A POSITION'S DATE WINS over this one — this is the proposal for every position that names none. Null on an order that asked for nothing, which is the ordinary case. It was collected in `user_data.requested_date` before this column existed and is still echoed there by callers that have not moved over; the column is what is compared, sorted and mapped.
      * @param {string} params.createdAt - Exact timestamp equality — this API has no range filter. To bound a period, sort with `order` and page. When the order row was written. For a placed order this is placed_at; for a requested one it is when the request was submitted.
      * @param {string} params.updatedAt - Exact timestamp equality — this API has no range filter. To bound a period, sort with `order` and page. When any column of the order last changed — every status move, every re-derived fulfillment, every modification.
      * @param {number} params.limit - Page size (default 50, max 200). A larger value is clamped to 200 rather than refused.
@@ -297,12 +446,21 @@ declare class Orders {
         holdReason?: string;
         itemCount?: number;
         subtotal?: number;
+        discountTotal?: number;
         shippingTotal?: number;
+        shippingTaxRate?: number;
+        shippingTaxAmount?: number;
+        paymentFeeAmount?: number;
+        paymentFeeTaxRate?: number;
+        paymentFeeTaxAmount?: number;
         taxTotal?: number;
         grandTotal?: number;
         placedAt?: string;
         completedAt?: string;
         cancelledAt?: string;
+        externalId?: string;
+        sourceSyncedAt?: string;
+        requestedDeliveryDate?: string;
         createdAt?: string;
         updatedAt?: string;
         limit?: number;
@@ -310,7 +468,7 @@ declare class Orders {
         order?: string;
     }): Promise<{}>;
     /**
-     * The route behind every order overview: the open orders of one customer, everything on hold, everything a market placed last week, or the one order somebody is quoting a number for (?number=ORD-000123 — the number is not the id, and this is how one becomes the other). The order LIST: the order rows without their positions, shipments, returns or cancellations — read GET /orders/{id} for the aggregate of one. Every parameter below is an exact match on the column it names, and combining them is an AND. Two kinds of key are not offered: one that names NO column is dropped silently, so a mistyped ?stauts=placed answers 200 with the whole list (compare the 'filter' echo against what you sent — no status code reports it), and the jsonb columns buyer, billing_address, shipping_address, payment, shipping, user_data and metadata reach the database as a text comparison and answer 400 invalid_value for anything that is not a whole JSON document.
+     * The route behind every order overview: the open orders of one customer, everything on hold, everything a market placed last week, or the one order somebody is quoting a number for (?number=ORD-000123 — the number is not the id, and this is how one becomes the other). The order LIST: the order rows without their positions, shipments, returns or cancellations — read GET /orders/{id} for the aggregate of one. Every parameter below is an exact match on the column it names, and combining them is an AND. Two kinds of key are not offered: one that names NO column is not a filter — the SDK release after app-sdks#30 answers it 400 unknown_filter, and until then a mistyped ?stauts=placed is dropped and answers the whole list (compare the 'filter' echo against what you sent) — and the jsonb columns buyer, billing_address, shipping_address, payment, shipping, user_data and metadata reach the database as a text comparison and answer 400 invalid_value for anything that is not a whole JSON document.
      *
      * @param {string} id - Filter to exactly one order. GET /orders/{id} is the direct form and answers the aggregate; this exists because the list honours it too. Primary key of the order, and the id every other route takes. Not the order number.
      * @param {string} number - Look an order up by its NUMBER — the one filter a service desk starts from, and the way to turn the number a customer quotes into the uuid every other route wants. Exact match; there is no substring search on this API. The order number a human quotes — drawn from the tenant's order range at place-time, unique per tenant and never reused. It is NOT the id: every route addresses an order by uuid, and GET /orders?number=… is how a number becomes one.
@@ -329,12 +487,21 @@ declare class Orders {
      * @param {string} holdReason - Filter to rows whose `hold_reason` is exactly this value. Why the order is held, in the words the shipping guard quotes back. Null when it is not held — releasing a hold clears it.
      * @param {number} itemCount - Filter to rows whose `item_count` is exactly this value. The summed ORDERED quantity over all positions, rounded to a whole number — a headline figure for a list, computed once at place-time. It is deliberately not reduced when something is cancelled or returned; the positions carry that arithmetic.
      * @param {number} subtotal - Filter to rows whose `subtotal` is exactly this value. NET total of the positions (the sum of their line_total), COMPUTED here at place-time. In `currency`, four decimal places. A caller cannot set it.
-     * @param {number} shippingTotal - Filter to rows whose `shipping_total` is exactly this value. NET shipping cost, taken from shipping.price or, when the snapshot carries no price, from the request's shipping_total. In `currency`.
+     * @param {number} discountTotal - Filter to rows whose `discount_total` is exactly this value. Every discount a promotion took off this order, summed: the positions' discounts, a head-level voucher distributed across them, a discount placed as its own position, and any reduction of the shipping charge. COMPUTED here from the components the caller evaluated — a caller cannot set it. `subtotal` stays the UNDISCOUNTED sum, so the two together say what was charged and what was given away.
+     * @param {number} shippingTotal - Filter to rows whose `shipping_total` is exactly this value. NET shipping cost, taken from shipping.price or, when the snapshot carries no price, from the request's shipping_total. In `currency`. This is the price BEFORE any promotion reduced it; the reduction is a row in the discount components.
+     * @param {number} shippingTaxRate - Filter to rows whose `shipping_tax_rate` is exactly this value. The tax percentage the shipping charge was taxed at, frozen at place-time (19 means 19 %). Stored rather than only used, because otherwise nobody could say afterwards how much of tax_total was shipping — which an ERP export of a discounted shipping charge needs.
+     * @param {number} shippingTaxAmount - Filter to rows whose `shipping_tax_amount` is exactly this value. Tax on the shipping charge, computed on what is OWED after any promotion reduced it. Part of tax_total, and stored separately so the shipping line can be stated on its own.
+     * @param {number} paymentFeeAmount - Filter to rows whose `payment_fee_amount` is exactly this value. The payment surcharge this order was placed with, NET — what the payments app computed for the chosen method (a fixed amount, or a share of the order). Zero for a method that charges nothing, which is most of them. Passed in with the payment arrangement the way the shipping price is, and stored rather than folded into the `payment` blob: a grand_total that silently included a fee nobody could point at is a reconciliation nobody can finish.
+     * @param {number} paymentFeeTaxRate - Filter to rows whose `payment_fee_tax_rate` is exactly this value. The rate the payment surcharge was taxed at, frozen at place-time (19 means 19 %). A surcharge is a Nebenleistung and is taxed like one.
+     * @param {number} paymentFeeTaxAmount - Filter to rows whose `payment_fee_tax_amount` is exactly this value. Tax on the payment surcharge, part of tax_total and stored separately so the fee can be stated on its own line of an invoice or an export.
      * @param {number} taxTotal - Filter to rows whose `tax_total` is exactly this value. All tax on this order: the positions' tax_amount plus the tax on shipping (shipping_total × shipping.tax_rate). COMPUTED here — a caller cannot set it.
-     * @param {number} grandTotal - Filter to rows whose `grand_total` is exactly this value. What the buyer owes: subtotal + shipping_total + tax_total, COMPUTED by this app and NEVER taken from the caller — trusting a supplied total is how inconsistent orders happened. This is the number the approval threshold is compared against and the number the revenue rollup sums.
+     * @param {number} grandTotal - Filter to rows whose `grand_total` is exactly this value. What the buyer owes: the positions' discounted totals plus the discounted shipping charge plus the payment surcharge plus tax_total, COMPUTED by this app and NEVER taken from the caller — trusting a supplied total is how inconsistent orders happened. This is the number the approval threshold is compared against and the number the revenue rollup sums.
      * @param {string} placedAt - Exact timestamp equality — this API has no range filter. To bound a period, sort with `order` and page. When the order was PLACED. Null while it is pending approval: an order awaiting sign-off exists but was never placed, and that is exactly the difference this field records.
      * @param {string} completedAt - Exact timestamp equality — this API has no range filter. To bound a period, sort with `order` and page. When the order was closed — by a full shipment, by payment or by hand, depending on the tenant's auto_complete_on. Null until then.
      * @param {string} cancelledAt - Exact timestamp equality — this API has no range filter. To bound a period, sort with `order` and page. When the order was cancelled, whether by a full cancel or by the last open quantity being cancelled position by position. Null otherwise.
+     * @param {string} externalId - Filter to rows whose `external_id` is exactly this value. The key this order has in the system that OWNS it — the ERP's own handle on the sales order, which is what a write-back addresses. Distinct from `external_ref`, which is the readable ORDER NUMBER that system quotes at a human, and from `number`, which is the one this app issued. Unique per tenant where set, so a retried import that sends the same key again is refused rather than founding a second order. Null for an order the shop owns.
+     * @param {string} sourceSyncedAt - Exact timestamp equality — this API has no range filter. To bound a period, sort with `order` and page. When this order was last confirmed against its source. What a delta run asks for changes since, and what tells an operator that a feed has gone quiet — an edit made here does not touch it, because it says when the SOURCE was last seen, not when the row changed. Null for a order no source owns.
+     * @param {string} requestedDeliveryDate - The dispatch list for one day: every order the buyer asked to have on it. Exact equality on the DAY — there is no range filter here, so a week is seven calls or a sort with `order=requested_delivery_date.asc` and paging. It answers about the ORDER's date; a position that named its own is not found this way. The calendar day the BUYER asked to be delivered on, as a date and not a moment — a buyer asks for Tuesday, not for Tuesday at 14:03 in a timezone nobody named. It is a wish and nothing here judges it: a date in the past, a weekend or a day inside the lead time is stored as sent, because what is deliverable is the merchant's answer and this app reads neither stock nor carrier calendar. The positions carry their own, and A POSITION'S DATE WINS over this one — this is the proposal for every position that names none. Null on an order that asked for nothing, which is the ordinary case. It was collected in `user_data.requested_date` before this column existed and is still echoed there by callers that have not moved over; the column is what is compared, sorted and mapped.
      * @param {string} createdAt - Exact timestamp equality — this API has no range filter. To bound a period, sort with `order` and page. When the order row was written. For a placed order this is placed_at; for a requested one it is when the request was submitted.
      * @param {string} updatedAt - Exact timestamp equality — this API has no range filter. To bound a period, sort with `order` and page. When any column of the order last changed — every status move, every re-derived fulfillment, every modification.
      * @param {number} limit - Page size (default 50, max 200). A larger value is clamped to 200 rather than refused.
@@ -344,9 +511,31 @@ declare class Orders {
      * @returns {Promise<{}>}
      * @deprecated Use the object parameter style method for a better developer experience.
      */
-    ordersList(id?: string, number?: string, customerOrderNumber?: string, externalRef?: string, acknowledgedAt?: string, cartId?: string, contactId?: string, organizationId?: string, channelId?: string, currency?: string, status?: OrderStatus, paymentStatus?: OrderPaymentStatus, fulfillmentStatus?: OrderFulfillmentStatus, onHold?: boolean, holdReason?: string, itemCount?: number, subtotal?: number, shippingTotal?: number, taxTotal?: number, grandTotal?: number, placedAt?: string, completedAt?: string, cancelledAt?: string, createdAt?: string, updatedAt?: string, limit?: number, offset?: number, order?: string): Promise<{}>;
+    ordersList(id?: string, number?: string, customerOrderNumber?: string, externalRef?: string, acknowledgedAt?: string, cartId?: string, contactId?: string, organizationId?: string, channelId?: string, currency?: string, status?: OrderStatus, paymentStatus?: OrderPaymentStatus, fulfillmentStatus?: OrderFulfillmentStatus, onHold?: boolean, holdReason?: string, itemCount?: number, subtotal?: number, discountTotal?: number, shippingTotal?: number, shippingTaxRate?: number, shippingTaxAmount?: number, paymentFeeAmount?: number, paymentFeeTaxRate?: number, paymentFeeTaxAmount?: number, taxTotal?: number, grandTotal?: number, placedAt?: string, completedAt?: string, cancelledAt?: string, externalId?: string, sourceSyncedAt?: string, requestedDeliveryDate?: string, createdAt?: string, updatedAt?: string, limit?: number, offset?: number, order?: string): Promise<{}>;
     /**
-     * The counters this tenant numbers its orders, delivery notes and returns from — what an operator sees on the Number ranges settings page, and what a migration reads to check the prefixes and the padding before it imports anything. Every parameter below is an exact-match filter on the column it names (?code=order finds the order counter). Two things are not: a key that names NO column is dropped silently — the call answers 200 with the unfiltered page, so compare the 'filter' echo against what you sent — and the jsonb column 'metadata' is honoured by the router but refused by the database (400 invalid_value) unless the value is a whole JSON document, which is why it is not offered here. It does not draw a number: `counter` is the last number DRAWN, and only placing an order, a shipment or a return moves it.
+     * A one-off per tenant, and a MIGRATION rather than a feature: the day a buyer asked to be delivered on was collected long before it had a field of its own, in `user_data.requested_date` — a free-form blob, so the date was present and neither filterable, sortable nor visible to any ERP mapping. This copies what is already there into `requested_delivery_date` on every order that carries no date yet, and it is safe to run again: a second call finds nothing to fill and says so. It reads only the orders with no date, so it is cheap; `filled` is what it changed and `scanned` what it had to look at, and `scanned` never falls to zero, because an order that genuinely asked for no day is read by every later run. THE JSONB KEY IS LEFT WHERE IT IS: `user_data` belongs to the caller and is handed back untouched, so the key stays as a deprecated echo of the column — the column is what is compared, sorted and mapped from here on. `updated_at` is not touched either: it says when the row last changed for the merchant, and stamping the whole table with today would destroy that reading for every reader of it, a delta run included. A value in the key that is not a calendar day is counted under `skipped` and left alone rather than refusing the run. The scan stops itself before the gateway's timeout and hands back a `cursor`; send it back unchanged until `done` is true.
+     *
+     * @param {string} params.cursor - Continue an unfinished run: the exact value the previous call returned, which is the id of the last order it read. Do not construct one — it is a resume point, not an offset. Omit it on the first call.
+     * @param {number} params.limit - Orders read per page of the scan (default 500, clamped to 1000). It is the page size, not a cap on the run: the scan keeps paging until it finishes or runs out of time.
+     * @throws {RevenexxException}
+     * @returns {Promise<Models.OrderRequestedDeliveryDateMigration>}
+     */
+    ordersMigrationsRequestedDeliveryDate(params?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<Models.OrderRequestedDeliveryDateMigration>;
+    /**
+     * A one-off per tenant, and a MIGRATION rather than a feature: the day a buyer asked to be delivered on was collected long before it had a field of its own, in `user_data.requested_date` — a free-form blob, so the date was present and neither filterable, sortable nor visible to any ERP mapping. This copies what is already there into `requested_delivery_date` on every order that carries no date yet, and it is safe to run again: a second call finds nothing to fill and says so. It reads only the orders with no date, so it is cheap; `filled` is what it changed and `scanned` what it had to look at, and `scanned` never falls to zero, because an order that genuinely asked for no day is read by every later run. THE JSONB KEY IS LEFT WHERE IT IS: `user_data` belongs to the caller and is handed back untouched, so the key stays as a deprecated echo of the column — the column is what is compared, sorted and mapped from here on. `updated_at` is not touched either: it says when the row last changed for the merchant, and stamping the whole table with today would destroy that reading for every reader of it, a delta run included. A value in the key that is not a calendar day is counted under `skipped` and left alone rather than refusing the run. The scan stops itself before the gateway's timeout and hands back a `cursor`; send it back unchanged until `done` is true.
+     *
+     * @param {string} cursor - Continue an unfinished run: the exact value the previous call returned, which is the id of the last order it read. Do not construct one — it is a resume point, not an offset. Omit it on the first call.
+     * @param {number} limit - Orders read per page of the scan (default 500, clamped to 1000). It is the page size, not a cap on the run: the scan keeps paging until it finishes or runs out of time.
+     * @throws {RevenexxException}
+     * @returns {Promise<Models.OrderRequestedDeliveryDateMigration>}
+     * @deprecated Use the object parameter style method for a better developer experience.
+     */
+    ordersMigrationsRequestedDeliveryDate(cursor?: string, limit?: number): Promise<Models.OrderRequestedDeliveryDateMigration>;
+    /**
+     * The counters this tenant numbers its orders, delivery notes and returns from — what an operator sees on the Number ranges settings page, and what a migration reads to check the prefixes and the padding before it imports anything. Every parameter below is an exact-match filter on the column it names (?code=order finds the order counter). Two things are not: a key that names NO column is not a filter — the SDK release after app-sdks#30 answers it 400 unknown_filter, and until then it is dropped and absent from the 'filter' echo, so compare that echo against what you sent — and the jsonb column 'metadata' is honoured by the router but refused by the database (400 invalid_value) unless the value is a whole JSON document, which is why it is not offered here. It does not draw a number: `counter` is the last number DRAWN, and only placing an order, a shipment or a return moves it.
      *
      * @param {string} params.id - Filter to rows whose `id` is exactly this value. Primary key of the number range.
      * @param {string} params.code - Look a range up by its code — 'order', 'delivery', 'return', or whatever a settings key points at. Which counter this is, in the app's own words: 'order' numbers orders, 'delivery' numbers delivery notes, 'return' numbers returns. Unique per tenant, and the value the order_number_range_code / delivery_number_range_code / return_number_range_code settings point at — a setting naming a code no range carries is the 422 'number_range_missing'.
@@ -382,7 +571,7 @@ declare class Orders {
         order?: string;
     }): Promise<{}>;
     /**
-     * The counters this tenant numbers its orders, delivery notes and returns from — what an operator sees on the Number ranges settings page, and what a migration reads to check the prefixes and the padding before it imports anything. Every parameter below is an exact-match filter on the column it names (?code=order finds the order counter). Two things are not: a key that names NO column is dropped silently — the call answers 200 with the unfiltered page, so compare the 'filter' echo against what you sent — and the jsonb column 'metadata' is honoured by the router but refused by the database (400 invalid_value) unless the value is a whole JSON document, which is why it is not offered here. It does not draw a number: `counter` is the last number DRAWN, and only placing an order, a shipment or a return moves it.
+     * The counters this tenant numbers its orders, delivery notes and returns from — what an operator sees on the Number ranges settings page, and what a migration reads to check the prefixes and the padding before it imports anything. Every parameter below is an exact-match filter on the column it names (?code=order finds the order counter). Two things are not: a key that names NO column is not a filter — the SDK release after app-sdks#30 answers it 400 unknown_filter, and until then it is dropped and absent from the 'filter' echo, so compare that echo against what you sent — and the jsonb column 'metadata' is honoured by the router but refused by the database (400 invalid_value) unless the value is a whole JSON document, which is why it is not offered here. It does not draw a number: `counter` is the last number DRAWN, and only placing an order, a shipment or a return moves it.
      *
      * @param {string} id - Filter to rows whose `id` is exactly this value. Primary key of the number range.
      * @param {string} code - Look a range up by its code — 'order', 'delivery', 'return', or whatever a settings key points at. Which counter this is, in the app's own words: 'order' numbers orders, 'delivery' numbers delivery notes, 'return' numbers returns. Unique per tenant, and the value the order_number_range_code / delivery_number_range_code / return_number_range_code settings point at — a setting naming a code no range carries is the 422 'number_range_missing'.
@@ -404,7 +593,7 @@ declare class Orders {
      */
     ordersNumberRangesList(id?: string, code?: string, prefix?: string, suffix?: string, padding?: number, counter?: number, step?: number, positionStep?: number, channelId?: string, createdAt?: string, updatedAt?: string, limit?: number, offset?: number, order?: string): Promise<{}>;
     /**
-     * Add a counter beyond the three a tenant is seeded with, and give it the shape a merchant's numbers actually have: {prefix}{counter padded to `padding`}{suffix}, moving by `step` per draw. A new range is what the order_number_range_code / delivery_number_range_code / return_number_range_code settings can then be pointed at — the code is the name those settings use, and a setting naming a code no range carries makes placing an order answer 422. `code` is unique per tenant, so this is a 409 for one that is taken rather than a second counter under the same name. It does not renumber anything that already exists, and setting `counter` to a value already issued re-issues those numbers, which the unique index on the order number then refuses.
+     * Add a counter beyond the three a tenant is seeded with, and give it the shape a merchant's numbers actually have: {prefix}{counter padded to `padding`}{suffix}, moving by `step` per draw. A new range is what the order_number_range_code / delivery_number_range_code / return_number_range_code settings can then be pointed at — the code is the name those settings use, and a setting naming a code no range carries makes placing an order answer 422. `code` is unique per tenant, so this is a 409 for one that is taken rather than a second counter under the same name. It does not renumber anything that already exists, and setting `counter` to a value already issued re-issues those numbers, which the unique index on the order number then refuses. created_at and updated_at are the server's: a body carrying either is 400 server_owned_field.
      *
      * @param {string} params.code - Which counter this is, in the app's own words: 'order' numbers orders, 'delivery' numbers delivery notes, 'return' numbers returns. Unique per tenant, and the value the order_number_range_code / delivery_number_range_code / return_number_range_code settings point at — a setting naming a code no range carries is the 422 'number_range_missing'.
      * @param {string} params.channelId - The sales channel this range was created for, as a label. It does NOT select the range: a draw finds the range by `code` alone, and the unique index (tenant, code) means one code is one range per tenant — so an order on another channel draws from the same range this one names. Null on the three seeded ranges, which is every tenant-wide range.
@@ -430,7 +619,7 @@ declare class Orders {
         suffix?: string;
     }): Promise<Models.NumberRange>;
     /**
-     * Add a counter beyond the three a tenant is seeded with, and give it the shape a merchant's numbers actually have: {prefix}{counter padded to `padding`}{suffix}, moving by `step` per draw. A new range is what the order_number_range_code / delivery_number_range_code / return_number_range_code settings can then be pointed at — the code is the name those settings use, and a setting naming a code no range carries makes placing an order answer 422. `code` is unique per tenant, so this is a 409 for one that is taken rather than a second counter under the same name. It does not renumber anything that already exists, and setting `counter` to a value already issued re-issues those numbers, which the unique index on the order number then refuses.
+     * Add a counter beyond the three a tenant is seeded with, and give it the shape a merchant's numbers actually have: {prefix}{counter padded to `padding`}{suffix}, moving by `step` per draw. A new range is what the order_number_range_code / delivery_number_range_code / return_number_range_code settings can then be pointed at — the code is the name those settings use, and a setting naming a code no range carries makes placing an order answer 422. `code` is unique per tenant, so this is a 409 for one that is taken rather than a second counter under the same name. It does not renumber anything that already exists, and setting `counter` to a value already issued re-issues those numbers, which the unique index on the order number then refuses. created_at and updated_at are the server's: a body carrying either is 400 server_owned_field.
      *
      * @param {string} code - Which counter this is, in the app's own words: 'order' numbers orders, 'delivery' numbers delivery notes, 'return' numbers returns. Unique per tenant, and the value the order_number_range_code / delivery_number_range_code / return_number_range_code settings point at — a setting naming a code no range carries is the 422 'number_range_missing'.
      * @param {string} channelId - The sales channel this range was created for, as a label. It does NOT select the range: a draw finds the range by `code` alone, and the unique index (tenant, code) means one code is one range per tenant — so an order on another channel draws from the same range this one names. Null on the three seeded ranges, which is every tenant-wide range.
@@ -454,7 +643,7 @@ declare class Orders {
      */
     ordersNumberRangesDefaults(): Promise<Models.OrderNumberRangesSeeded>;
     /**
-     * Remove a counter a tenant no longer numbers anything from. It touches nothing that was numbered out of it: existing orders, delivery notes and returns keep the numbers they were given, because a number is copied onto the row at place-time and is not a reference to this table. Deleting one of the three standard codes is allowed and is usually a mistake — the next draw against it answers 422 'number_range_missing', unless POST /orders/number-ranges/defaults or a reinstall seeds it again, which starts its counter back at 0.
+     * Remove a counter a tenant no longer numbers anything from. It touches nothing that was numbered out of it: existing orders, delivery notes and returns keep the numbers they were given, because a number is copied onto the row at place-time and is not a reference to this table. Only a range that has never drawn a number can be removed: one whose counter is above 0 answers 409 range_in_use, because a standard code would come back at 0 on the next draw and hand out numbers that already exist.
      *
      * @param {string} params.id - The number range id (uuid).
      * @throws {RevenexxException}
@@ -464,7 +653,7 @@ declare class Orders {
         id: string;
     }): Promise<Models.OrderDeleted>;
     /**
-     * Remove a counter a tenant no longer numbers anything from. It touches nothing that was numbered out of it: existing orders, delivery notes and returns keep the numbers they were given, because a number is copied onto the row at place-time and is not a reference to this table. Deleting one of the three standard codes is allowed and is usually a mistake — the next draw against it answers 422 'number_range_missing', unless POST /orders/number-ranges/defaults or a reinstall seeds it again, which starts its counter back at 0.
+     * Remove a counter a tenant no longer numbers anything from. It touches nothing that was numbered out of it: existing orders, delivery notes and returns keep the numbers they were given, because a number is copied onto the row at place-time and is not a reference to this table. Only a range that has never drawn a number can be removed: one whose counter is above 0 answers 409 range_in_use, because a standard code would come back at 0 on the next draw and hand out numbers that already exist.
      *
      * @param {string} id - The number range id (uuid).
      * @throws {RevenexxException}
@@ -492,7 +681,7 @@ declare class Orders {
      */
     ordersNumberRangesGet(id: string): Promise<Models.NumberRange>;
     /**
-     * Change the format or the state of an existing counter: a new prefix or suffix, a wider padding, a different step, a different position_step for new order lines — or `counter` itself, which is state rather than configuration. Everything takes effect on the NEXT draw only: nothing that was already numbered is renumbered, so widening the padding leaves ORD-000123 and starts writing ORD-0000124. Moving `counter` forward skips numbers, and moving it back re-issues numbers that exist, which the unique index on the order number answers 409 for at place-time rather than here. Renaming `code` to one another range of this tenant already holds is a 409.
+     * Change the format or the state of an existing counter: a new prefix or suffix, a wider padding, a different step, a different position_step for new order lines — or `counter` itself, which is state rather than configuration. Everything takes effect on the NEXT draw only: nothing that was already numbered is renumbered, so widening the padding leaves ORD-000123 and starts writing ORD-0000124. Moving `counter` forward skips numbers; moving it BACK is refused (422 counter_rewind), because it would hand out numbers orders already carry — resending the counter the range already has is fine, only a change is checked. Renaming `code` to one another range of this tenant already holds is a 409. updated_at is stamped by the server; a body carrying created_at or updated_at is 400 server_owned_field.
      *
      * @param {string} params.id - The number range id (uuid).
      * @param {string} params.channelId - The sales channel this range was created for, as a label. It does NOT select the range: a draw finds the range by `code` alone, and the unique index (tenant, code) means one code is one range per tenant — so an order on another channel draws from the same range this one names. Null on the three seeded ranges, which is every tenant-wide range.
@@ -520,7 +709,7 @@ declare class Orders {
         suffix?: string;
     }): Promise<Models.NumberRange>;
     /**
-     * Change the format or the state of an existing counter: a new prefix or suffix, a wider padding, a different step, a different position_step for new order lines — or `counter` itself, which is state rather than configuration. Everything takes effect on the NEXT draw only: nothing that was already numbered is renumbered, so widening the padding leaves ORD-000123 and starts writing ORD-0000124. Moving `counter` forward skips numbers, and moving it back re-issues numbers that exist, which the unique index on the order number answers 409 for at place-time rather than here. Renaming `code` to one another range of this tenant already holds is a 409.
+     * Change the format or the state of an existing counter: a new prefix or suffix, a wider padding, a different step, a different position_step for new order lines — or `counter` itself, which is state rather than configuration. Everything takes effect on the NEXT draw only: nothing that was already numbered is renumbered, so widening the padding leaves ORD-000123 and starts writing ORD-0000124. Moving `counter` forward skips numbers; moving it BACK is refused (422 counter_rewind), because it would hand out numbers orders already carry — resending the counter the range already has is fine, only a change is checked. Renaming `code` to one another range of this tenant already holds is a 409. updated_at is stamped by the server; a body carrying created_at or updated_at is 400 server_owned_field.
      *
      * @param {string} id - The number range id (uuid).
      * @param {string} channelId - The sales channel this range was created for, as a label. It does NOT select the range: a draw finds the range by `code` alone, and the unique index (tenant, code) means one code is one range per tenant — so an order on another channel draws from the same range this one names. Null on the three seeded ranges, which is every tenant-wide range.
@@ -538,7 +727,7 @@ declare class Orders {
      */
     ordersNumberRangesUpdate(id: string, channelId?: string, code?: string, counter?: number, metadata?: object, padding?: number, positionStep?: number, prefix?: string, step?: number, suffix?: string): Promise<Models.NumberRange>;
     /**
-     * The way an order comes into existence — the call a checkout, a punch-out or an ERP import makes once the basket is final. The body is a SNAPSHOT: items with their product copies, plus the buyer, the addresses and the payment and shipping choices frozen as they were at this moment, so the order stays readable when the catalogue or the customer changes underneath it. The app draws the order number from the tenant's order range, numbers the positions, computes subtotal, tax and grand_total from the lines, and writes the order.placed event that carries the order onto the bus. It does not reserve stock, take payment or talk to an ERP: those are separate capabilities, and this route's job ends when the event is on the bus. Two things can turn a placement into a REQUEST awaiting approval, and both still answer 201 — with status='pending' and no placed_at: a principal holding only orders.request, and an order worth more than the tenant's require_approval_above_value (a principal holding orders.approve is exempt from the threshold). The order.requested event says which, in 'approval_reason'. The currency defaults to the market's default_currency setting and the position cap is the tenant's max_items_per_order.
+     * The way an order comes into existence — the call a checkout, a punch-out or an ERP import makes once the basket is final. The body is a SNAPSHOT: items with their product copies, plus the buyer, the addresses and the payment and shipping choices frozen as they were at this moment, so the order stays readable when the catalogue or the customer changes underneath it. The app draws the order number from the tenant's order range, numbers the positions, computes subtotal, tax and grand_total from the lines, and writes the order.placed event that carries the order onto the bus. It does not reserve stock, take payment or talk to an ERP: those are separate capabilities, and this route's job ends when the event is on the bus. Two things can turn a placement into a REQUEST awaiting approval, and both still answer 201 — with status='pending' and no placed_at: a principal holding only orders.request, and an order worth more than the tenant's require_approval_above_value (a principal holding orders.approve is exempt from the threshold). The order.requested event says which, in 'approval_reason'. The currency defaults to the market's default_currency setting and the position cap is the tenant's max_items_per_order. PRICES ARE THE CALLER'S: this app reads no price list, so the unit price, the tax rate, the shipping charge and the promotions a caller evaluated are taken as sent — refused only when they cannot be money (a negative price or shipping charge, a tax rate outside 0–100). Totals, tax amounts and the discount split are computed here.
      *
      * @param {Models.OrderItemCreateRequest[]} params.items - The order positions — at least one, and at most the tenant's max_items_per_order (500 out of the box; a longer list is a 400 naming the limit).
      * @param {object} params.billingAddress - The invoice address, FROZEN at place-time. Changing the customer's address afterwards does not change what this order was billed to.
@@ -548,14 +737,19 @@ declare class Orders {
      * @param {string} params.contactId - The PERSON who ordered — a contact in the customers app. Resolved from the acting principal whenever the caller carries one, and a body value that disagrees is refused rather than silently overridden. Null for a guest checkout. Ignored when the caller carries a principal — the RESOLVED contact wins, and a body value that disagrees is a 400 rather than a silent override.
      * @param {string} params.currency - ISO 4217 code of EVERY amount on this order. Frozen at place-time from the market's default_currency unless the caller named one. Nothing on this order is ever converted, and the approval threshold is read in this currency — which is why the threshold is a per-market setting. Defaults to the market's default_currency setting.
      * @param {string} params.customerOrderNumber - The BUYER's own reference — their purchase-order number. Free text, not unique, never generated here: it exists so the paperwork can carry the number the buyer's accounts payable will look for. One of the few fields PUT /orders/{id} may still change.
+     * @param {string} params.externalId - The key this order has in the system that OWNS it — the ERP's own handle on the sales order, which is what a write-back addresses. Distinct from `external_ref`, which is the readable ORDER NUMBER that system quotes at a human, and from `number`, which is the one this app issued. Unique per tenant where set, so a retried import that sends the same key again is refused rather than founding a second order. Null for an order the shop owns. Sending it a second time is a 409, not a second order: the key is unique per tenant, which is what makes a retried import safe to run. Recover by reading the order back with GET /orders?external_id=… and correcting that one.
+     * @param {object} params.externalRefs - Every OTHER system that knows this order, keyed by system name — a second ERP, a procurement platform, a portal. `external_id` is the leading system; this is the rest. Not a query parameter: a jsonb column is compared as a whole document, so look the row up by `external_id` and read this off the answer.
      * @param {number} params.grandTotal - Optional, and CHECKED rather than used: the order always computes its own total from the positions, the shipping cost and the tax. Send it as a checksum on that arithmetic — if it agrees the order is placed, and if it disagrees the call is refused with 400 naming both numbers, yours and the computed one. The comparison is at 2 decimal places (this app stores 4, ERPs work to 2, so a difference below a cent is agreement). It is never taken as the order value: the approval threshold and the revenue rollup read the computed number, which is why a total that disagrees is an error rather than an override.
      * @param {object} params.metadata - Free-form data belonging to the INTEGRATION side — an ERP's own bookkeeping about this order. Stored and returned untouched; nothing here reads it.
      * @param {string} params.organizationId - The COMPANY the order is booked on — an organization in the customers app, and the B2B half of who ordered. This is what orders.reports.customer-rollup aggregates by and what makes an order visible to a buyer's colleagues. Null on a private or guest order, which the rollup counts separately because it cannot attribute it. A principal's own organization wins over this when it has one.
-     * @param {object} params.payment - The payment arrangement as it was chosen, FROZEN. This app reads exactly two keys and stores the rest untouched: 'status' seeds payment_status at place-time when it names one of the permitted values (anything else is ignored and the order starts 'open'), and 'payment_id' is merged in by POST /orders/{id}/payment-status. The method itself, its provider fields and any redirect state belong to the payments app.
+     * @param {object} params.payment - The payment arrangement as it was chosen, FROZEN. This app reads exactly two keys and stores the rest untouched: 'status' seeds payment_status at place-time when it names one of the permitted values (anything else is ignored and the order starts 'open'; a buyer's own call may only send 'open'), and 'payment_id' is merged in by POST /orders/{id}/payment-status. The method itself, its provider fields and any redirect state belong to the payments app.
+     * @param {string} params.requestedDeliveryDate - The calendar day the BUYER asked to be delivered on, as a date and not a moment — a buyer asks for Tuesday, not for Tuesday at 14:03 in a timezone nobody named. It is a wish and nothing here judges it: a date in the past, a weekend or a day inside the lead time is stored as sent, because what is deliverable is the merchant's answer and this app reads neither stock nor carrier calendar. The positions carry their own, and A POSITION'S DATE WINS over this one — this is the proposal for every position that names none. Null on an order that asked for nothing, which is the ordinary case. It was collected in `user_data.requested_date` before this column existed and is still echoed there by callers that have not moved over; the column is what is compared, sorted and mapped. 'YYYY-MM-DD'. A value that is not a day that exists is a 400. Omit it and `user_data.requested_date` is taken instead, which is where a caller written before this field existed puts it — send the field and that copy is ignored.
      * @param {object} params.shipping - The shipping arrangement as it was chosen, FROZEN. Two keys are READ at place-time and feed the totals: 'price' becomes shipping_total (the shipping_total field is only the fallback when this is absent) and 'tax_rate' is what shipping is taxed at, because shipping is a Nebenleistung and is taxed too. Everything else — the carrier product, the delivery window, the pickup point — is stored untouched and belongs to the shipping app.
      * @param {object} params.shippingAddress - The delivery address, FROZEN at place-time — what goes on the label of every shipment of this order. Null on an order that is never delivered (a service, a digital item, a collection).
-     * @param {number} params.shippingTotal - NET shipping cost, taken from shipping.price or, when the snapshot carries no price, from the request's shipping_total. In `currency`. Only read when the shipping snapshot carries no 'price'.
-     * @param {object} params.userData - Free-form data belonging to the ORDERING side — carried through from the storefront or the cart and handed back untouched. One of the few fields PUT /orders/{id} may still change.
+     * @param {number} params.shippingTotal - NET shipping cost, taken from shipping.price or, when the snapshot carries no price, from the request's shipping_total. In `currency`. This is the price BEFORE any promotion reduced it; the reduction is a row in the discount components. Only read when the shipping snapshot carries no 'price'. Below zero is a 400, and so is a 'shipping.price' below zero or a 'shipping.tax_rate' outside 0–100.
+     * @param {object} params.sourceData - What the source said about this row, kept as it said it: `{"system": …, "etag": …, "raw": {…}}`. The `etag` is what a write-back has to send back in `If-Match`, and there is nowhere else to keep it between two runs. `raw` holds the source fields this app does not model, so they survive a round trip instead of being lost on the first edit. Nothing here reads it, and no transition clears it.
+     * @param {string} params.sourceSyncedAt - When this order was last confirmed against its source. What a delta run asks for changes since, and what tells an operator that a feed has gone quiet — an edit made here does not touch it, because it says when the SOURCE was last seen, not when the row changed. Null for a order no source owns.
+     * @param {object} params.userData - Free-form data belonging to the ORDERING side — carried through from the storefront or the cart and handed back untouched. One of the few fields PUT /orders/{id} may still change. One key of it is read: `requested_date`, which is where the wanted delivery date was collected before it had a column, and which is taken as the date only when `requested_delivery_date` names none. The blob itself is never rewritten by that reading.
      * @throws {RevenexxException}
      * @returns {Promise<Models.OrderPlaced>}
      */
@@ -568,17 +762,22 @@ declare class Orders {
         contactId?: string;
         currency?: string;
         customerOrderNumber?: string;
+        externalId?: string;
+        externalRefs?: object;
         grandTotal?: number;
         metadata?: object;
         organizationId?: string;
         payment?: object;
+        requestedDeliveryDate?: string;
         shipping?: object;
         shippingAddress?: object;
         shippingTotal?: number;
+        sourceData?: object;
+        sourceSyncedAt?: string;
         userData?: object;
     }): Promise<Models.OrderPlaced>;
     /**
-     * The way an order comes into existence — the call a checkout, a punch-out or an ERP import makes once the basket is final. The body is a SNAPSHOT: items with their product copies, plus the buyer, the addresses and the payment and shipping choices frozen as they were at this moment, so the order stays readable when the catalogue or the customer changes underneath it. The app draws the order number from the tenant's order range, numbers the positions, computes subtotal, tax and grand_total from the lines, and writes the order.placed event that carries the order onto the bus. It does not reserve stock, take payment or talk to an ERP: those are separate capabilities, and this route's job ends when the event is on the bus. Two things can turn a placement into a REQUEST awaiting approval, and both still answer 201 — with status='pending' and no placed_at: a principal holding only orders.request, and an order worth more than the tenant's require_approval_above_value (a principal holding orders.approve is exempt from the threshold). The order.requested event says which, in 'approval_reason'. The currency defaults to the market's default_currency setting and the position cap is the tenant's max_items_per_order.
+     * The way an order comes into existence — the call a checkout, a punch-out or an ERP import makes once the basket is final. The body is a SNAPSHOT: items with their product copies, plus the buyer, the addresses and the payment and shipping choices frozen as they were at this moment, so the order stays readable when the catalogue or the customer changes underneath it. The app draws the order number from the tenant's order range, numbers the positions, computes subtotal, tax and grand_total from the lines, and writes the order.placed event that carries the order onto the bus. It does not reserve stock, take payment or talk to an ERP: those are separate capabilities, and this route's job ends when the event is on the bus. Two things can turn a placement into a REQUEST awaiting approval, and both still answer 201 — with status='pending' and no placed_at: a principal holding only orders.request, and an order worth more than the tenant's require_approval_above_value (a principal holding orders.approve is exempt from the threshold). The order.requested event says which, in 'approval_reason'. The currency defaults to the market's default_currency setting and the position cap is the tenant's max_items_per_order. PRICES ARE THE CALLER'S: this app reads no price list, so the unit price, the tax rate, the shipping charge and the promotions a caller evaluated are taken as sent — refused only when they cannot be money (a negative price or shipping charge, a tax rate outside 0–100). Totals, tax amounts and the discount split are computed here.
      *
      * @param {Models.OrderItemCreateRequest[]} items - The order positions — at least one, and at most the tenant's max_items_per_order (500 out of the box; a longer list is a 400 naming the limit).
      * @param {object} billingAddress - The invoice address, FROZEN at place-time. Changing the customer's address afterwards does not change what this order was billed to.
@@ -588,19 +787,24 @@ declare class Orders {
      * @param {string} contactId - The PERSON who ordered — a contact in the customers app. Resolved from the acting principal whenever the caller carries one, and a body value that disagrees is refused rather than silently overridden. Null for a guest checkout. Ignored when the caller carries a principal — the RESOLVED contact wins, and a body value that disagrees is a 400 rather than a silent override.
      * @param {string} currency - ISO 4217 code of EVERY amount on this order. Frozen at place-time from the market's default_currency unless the caller named one. Nothing on this order is ever converted, and the approval threshold is read in this currency — which is why the threshold is a per-market setting. Defaults to the market's default_currency setting.
      * @param {string} customerOrderNumber - The BUYER's own reference — their purchase-order number. Free text, not unique, never generated here: it exists so the paperwork can carry the number the buyer's accounts payable will look for. One of the few fields PUT /orders/{id} may still change.
+     * @param {string} externalId - The key this order has in the system that OWNS it — the ERP's own handle on the sales order, which is what a write-back addresses. Distinct from `external_ref`, which is the readable ORDER NUMBER that system quotes at a human, and from `number`, which is the one this app issued. Unique per tenant where set, so a retried import that sends the same key again is refused rather than founding a second order. Null for an order the shop owns. Sending it a second time is a 409, not a second order: the key is unique per tenant, which is what makes a retried import safe to run. Recover by reading the order back with GET /orders?external_id=… and correcting that one.
+     * @param {object} externalRefs - Every OTHER system that knows this order, keyed by system name — a second ERP, a procurement platform, a portal. `external_id` is the leading system; this is the rest. Not a query parameter: a jsonb column is compared as a whole document, so look the row up by `external_id` and read this off the answer.
      * @param {number} grandTotal - Optional, and CHECKED rather than used: the order always computes its own total from the positions, the shipping cost and the tax. Send it as a checksum on that arithmetic — if it agrees the order is placed, and if it disagrees the call is refused with 400 naming both numbers, yours and the computed one. The comparison is at 2 decimal places (this app stores 4, ERPs work to 2, so a difference below a cent is agreement). It is never taken as the order value: the approval threshold and the revenue rollup read the computed number, which is why a total that disagrees is an error rather than an override.
      * @param {object} metadata - Free-form data belonging to the INTEGRATION side — an ERP's own bookkeeping about this order. Stored and returned untouched; nothing here reads it.
      * @param {string} organizationId - The COMPANY the order is booked on — an organization in the customers app, and the B2B half of who ordered. This is what orders.reports.customer-rollup aggregates by and what makes an order visible to a buyer's colleagues. Null on a private or guest order, which the rollup counts separately because it cannot attribute it. A principal's own organization wins over this when it has one.
-     * @param {object} payment - The payment arrangement as it was chosen, FROZEN. This app reads exactly two keys and stores the rest untouched: 'status' seeds payment_status at place-time when it names one of the permitted values (anything else is ignored and the order starts 'open'), and 'payment_id' is merged in by POST /orders/{id}/payment-status. The method itself, its provider fields and any redirect state belong to the payments app.
+     * @param {object} payment - The payment arrangement as it was chosen, FROZEN. This app reads exactly two keys and stores the rest untouched: 'status' seeds payment_status at place-time when it names one of the permitted values (anything else is ignored and the order starts 'open'; a buyer's own call may only send 'open'), and 'payment_id' is merged in by POST /orders/{id}/payment-status. The method itself, its provider fields and any redirect state belong to the payments app.
+     * @param {string} requestedDeliveryDate - The calendar day the BUYER asked to be delivered on, as a date and not a moment — a buyer asks for Tuesday, not for Tuesday at 14:03 in a timezone nobody named. It is a wish and nothing here judges it: a date in the past, a weekend or a day inside the lead time is stored as sent, because what is deliverable is the merchant's answer and this app reads neither stock nor carrier calendar. The positions carry their own, and A POSITION'S DATE WINS over this one — this is the proposal for every position that names none. Null on an order that asked for nothing, which is the ordinary case. It was collected in `user_data.requested_date` before this column existed and is still echoed there by callers that have not moved over; the column is what is compared, sorted and mapped. 'YYYY-MM-DD'. A value that is not a day that exists is a 400. Omit it and `user_data.requested_date` is taken instead, which is where a caller written before this field existed puts it — send the field and that copy is ignored.
      * @param {object} shipping - The shipping arrangement as it was chosen, FROZEN. Two keys are READ at place-time and feed the totals: 'price' becomes shipping_total (the shipping_total field is only the fallback when this is absent) and 'tax_rate' is what shipping is taxed at, because shipping is a Nebenleistung and is taxed too. Everything else — the carrier product, the delivery window, the pickup point — is stored untouched and belongs to the shipping app.
      * @param {object} shippingAddress - The delivery address, FROZEN at place-time — what goes on the label of every shipment of this order. Null on an order that is never delivered (a service, a digital item, a collection).
-     * @param {number} shippingTotal - NET shipping cost, taken from shipping.price or, when the snapshot carries no price, from the request's shipping_total. In `currency`. Only read when the shipping snapshot carries no 'price'.
-     * @param {object} userData - Free-form data belonging to the ORDERING side — carried through from the storefront or the cart and handed back untouched. One of the few fields PUT /orders/{id} may still change.
+     * @param {number} shippingTotal - NET shipping cost, taken from shipping.price or, when the snapshot carries no price, from the request's shipping_total. In `currency`. This is the price BEFORE any promotion reduced it; the reduction is a row in the discount components. Only read when the shipping snapshot carries no 'price'. Below zero is a 400, and so is a 'shipping.price' below zero or a 'shipping.tax_rate' outside 0–100.
+     * @param {object} sourceData - What the source said about this row, kept as it said it: `{"system": …, "etag": …, "raw": {…}}`. The `etag` is what a write-back has to send back in `If-Match`, and there is nowhere else to keep it between two runs. `raw` holds the source fields this app does not model, so they survive a round trip instead of being lost on the first edit. Nothing here reads it, and no transition clears it.
+     * @param {string} sourceSyncedAt - When this order was last confirmed against its source. What a delta run asks for changes since, and what tells an operator that a feed has gone quiet — an edit made here does not touch it, because it says when the SOURCE was last seen, not when the row changed. Null for a order no source owns.
+     * @param {object} userData - Free-form data belonging to the ORDERING side — carried through from the storefront or the cart and handed back untouched. One of the few fields PUT /orders/{id} may still change. One key of it is read: `requested_date`, which is where the wanted delivery date was collected before it had a column, and which is taken as the date only when `requested_delivery_date` names none. The blob itself is never rewritten by that reading.
      * @throws {RevenexxException}
      * @returns {Promise<Models.OrderPlaced>}
      * @deprecated Use the object parameter style method for a better developer experience.
      */
-    ordersPlace(items: Models.OrderItemCreateRequest[], billingAddress?: object, buyer?: object, cartId?: string, channelId?: string, contactId?: string, currency?: string, customerOrderNumber?: string, grandTotal?: number, metadata?: object, organizationId?: string, payment?: object, shipping?: object, shippingAddress?: object, shippingTotal?: number, userData?: object): Promise<Models.OrderPlaced>;
+    ordersPlace(items: Models.OrderItemCreateRequest[], billingAddress?: object, buyer?: object, cartId?: string, channelId?: string, contactId?: string, currency?: string, customerOrderNumber?: string, externalId?: string, externalRefs?: object, grandTotal?: number, metadata?: object, organizationId?: string, payment?: object, requestedDeliveryDate?: string, shipping?: object, shippingAddress?: object, shippingTotal?: number, sourceData?: object, sourceSyncedAt?: string, userData?: object): Promise<Models.OrderPlaced>;
     /**
      * What each company has bought, as numbers another app can keep: order count, lifetime revenue, first and last order date, and the same count and revenue over the last 30, 90 and 365 days. This is what a customer segment like "bought for more than 100k last year" is built on, and the customers app materialises it into a local projection its segment rules query. It answers about ORGANIZATIONS only — a private or guest order carries none and is counted in orders_without_organization rather than attributed to anybody — and it converts nothing, so an organization that ordered in two currencies gets both listed and one summed number to read with care. Revenue lives in orders, customer segments live in the customers app, and the two may not join (ADR-0055: no cross-app FK, grant or view). This capability is the hand-over. Every number is additive (count/sum/min/max) so partial answers merge; the average order value is deliberately not returned — it is revenue_total / order_count over the merged parts. Windows are anchored at as_of, which is echoed back so a loop measures one consistent picture.
      *
@@ -630,14 +834,88 @@ declare class Orders {
      */
     ordersReportsCustomerRollup(asOf?: string, cursor?: string, organizationIds?: string[], statuses?: OrderStatus[]): Promise<Models.OrderCustomerRollupResponse>;
     /**
-     * Which value sets this app will describe for you, by name — order statuses, payment statuses, fulfillment statuses, item types, return statuses and return resolutions — so a client can discover them instead of shipping its own copy of five statuses that goes stale one release later. The values themselves are deliberately NOT here: this is the index, and each set is fetched on its own. Discovery for the vocabulary routes. Names: cancellation-scopes, comment-visibilities, fulfillment-statuses, item-types, payment-statuses, return-resolutions, return-statuses, statuses. Fetch one with GET /orders/vocabularies/{name}; a client holding the qualified pair 'orders.<name>' builds that URL from the pair alone. 'title' and 'description' are locale maps wherever somebody wrote the copy and plain strings where the fallback did — read both forms.
+     * The reasons a merchant takes goods back under, in their own words and in the order a picker should offer them — what a returns dialog fills its reason select from, and what turns the `reason_code` on a return into a title somebody can read. It is the one vocabulary of this app the MERCHANT keeps rather than the database: why a customer sent something back differs per trade, so it is a table and a merchant gets their own without a release of this app. The set is served whole and seeds itself: a tenant that has never read it is given the nine standard reasons on the way, so this route never answers an empty select. Exactly one row carries `is_default` — the reason a picker preselects, repaired on read if nothing holds it — and it is deliberately 'other' rather than a real reason, because `order_returns.reason_code` is nullable and nothing here falls back to the flag. Every parameter below is an exact match on the column it names, and a key that names no column is 400 unknown_filter; limit, offset and order ('column.asc' | 'column.desc') page and sort it. The jsonb columns `labels` and `descriptions` are not offered, because the data plane answers 400 for anything that is not a whole JSON document. Adding, renaming and retiring a reason has no address here yet.
+     *
+     * @param {string} params.id - Filter to rows whose `id` is exactly this value. Primary key of the reason. The {id} segment of the item route; `code` is what a return stores.
+     * @param {string} params.code - Look one reason up by the code a return carries. Exact match, and the way to turn a `reason_code` off a return into the row that titles it. The stable identifier a return carries in `reason_code`, and the one thing about a reason that is not a label: lowercase, starting with a letter, with digits, '-' and '_' after it. It is what a report groups by and what an ERP mapping keys on, so it is fixed once created — the title is what a merchant renames.
+     * @param {string} params.title - Filter to rows whose `title` is exactly this value. What an operator reads in the picker, in the tenant's own words. Renaming it rewrites no return, because a return stores the code.
+     * @param {string} params.description - Filter to rows whose `description` is exactly this value. One sentence on when to pick this reason, for whoever is choosing between two that sound alike. Null where nobody wrote one.
+     * @param {boolean} params.isDefault - Filter to the one reason a picker preselects. Exactly one row of a tenant carries it. Exactly one reason of the tenant carries this: the one a picker preselects. It is NOT a fallback — `order_returns.reason_code` is nullable and a return registered without a code carries none, deliberately, because a default of 'Damaged in transit' would label returns that were never damaged. The seeded flag sits on 'other' for that reason. The set repairs itself on read when no row holds it.
+     * @param {OrderVocabularyTone} params.tone - Filter to rows whose `tone` is exactly this value. The semantic badge colour a client renders this reason in — the same five tones every vocabulary of this platform uses. The client owns what each tone looks like.
+     * @param {number} params.position - Filter to rows whose `position` is exactly this value. Where the reason sits in the picker, ascending. Ties fall back to whatever the database returns, so a merchant who cares about the order gives every row its own number.
+     * @param {boolean} params.isSystem - Filter to rows whose `is_system` is exactly this value. True for a reason the app seeded, and it means only 'we put it there' — not that it is protected. A merchant may rename, re-tone and reorder a seeded reason like any other; nothing here branches on this flag.
+     * @param {string} params.createdAt - Exact timestamp equality — this API has no range filter. To bound a period, sort with `order` and page. When the reason was created — the seed writes the nine standard ones on install.
+     * @param {string} params.updatedAt - Exact timestamp equality — this API has no range filter. To bound a period, sort with `order` and page. When the reason last changed.
+     * @param {number} params.limit - Page size (default 50, max 200). A larger value is clamped to 200 rather than refused.
+     * @param {number} params.offset - Row offset for pagination (default 0).
+     * @param {string} params.order - Sort by one column: 'column' | 'column.asc' | 'column.desc'. A bare column sorts ascending, the direction is lower case, and the column has to exist — the value reaches the data plane verbatim and anything else is a 400.
+     * @throws {RevenexxException}
+     * @returns {Promise<{}>}
+     */
+    ordersReturnReasonsList(params?: {
+        id?: string;
+        code?: string;
+        title?: string;
+        description?: string;
+        isDefault?: boolean;
+        tone?: OrderVocabularyTone;
+        position?: number;
+        isSystem?: boolean;
+        createdAt?: string;
+        updatedAt?: string;
+        limit?: number;
+        offset?: number;
+        order?: string;
+    }): Promise<{}>;
+    /**
+     * The reasons a merchant takes goods back under, in their own words and in the order a picker should offer them — what a returns dialog fills its reason select from, and what turns the `reason_code` on a return into a title somebody can read. It is the one vocabulary of this app the MERCHANT keeps rather than the database: why a customer sent something back differs per trade, so it is a table and a merchant gets their own without a release of this app. The set is served whole and seeds itself: a tenant that has never read it is given the nine standard reasons on the way, so this route never answers an empty select. Exactly one row carries `is_default` — the reason a picker preselects, repaired on read if nothing holds it — and it is deliberately 'other' rather than a real reason, because `order_returns.reason_code` is nullable and nothing here falls back to the flag. Every parameter below is an exact match on the column it names, and a key that names no column is 400 unknown_filter; limit, offset and order ('column.asc' | 'column.desc') page and sort it. The jsonb columns `labels` and `descriptions` are not offered, because the data plane answers 400 for anything that is not a whole JSON document. Adding, renaming and retiring a reason has no address here yet.
+     *
+     * @param {string} id - Filter to rows whose `id` is exactly this value. Primary key of the reason. The {id} segment of the item route; `code` is what a return stores.
+     * @param {string} code - Look one reason up by the code a return carries. Exact match, and the way to turn a `reason_code` off a return into the row that titles it. The stable identifier a return carries in `reason_code`, and the one thing about a reason that is not a label: lowercase, starting with a letter, with digits, '-' and '_' after it. It is what a report groups by and what an ERP mapping keys on, so it is fixed once created — the title is what a merchant renames.
+     * @param {string} title - Filter to rows whose `title` is exactly this value. What an operator reads in the picker, in the tenant's own words. Renaming it rewrites no return, because a return stores the code.
+     * @param {string} description - Filter to rows whose `description` is exactly this value. One sentence on when to pick this reason, for whoever is choosing between two that sound alike. Null where nobody wrote one.
+     * @param {boolean} isDefault - Filter to the one reason a picker preselects. Exactly one row of a tenant carries it. Exactly one reason of the tenant carries this: the one a picker preselects. It is NOT a fallback — `order_returns.reason_code` is nullable and a return registered without a code carries none, deliberately, because a default of 'Damaged in transit' would label returns that were never damaged. The seeded flag sits on 'other' for that reason. The set repairs itself on read when no row holds it.
+     * @param {OrderVocabularyTone} tone - Filter to rows whose `tone` is exactly this value. The semantic badge colour a client renders this reason in — the same five tones every vocabulary of this platform uses. The client owns what each tone looks like.
+     * @param {number} position - Filter to rows whose `position` is exactly this value. Where the reason sits in the picker, ascending. Ties fall back to whatever the database returns, so a merchant who cares about the order gives every row its own number.
+     * @param {boolean} isSystem - Filter to rows whose `is_system` is exactly this value. True for a reason the app seeded, and it means only 'we put it there' — not that it is protected. A merchant may rename, re-tone and reorder a seeded reason like any other; nothing here branches on this flag.
+     * @param {string} createdAt - Exact timestamp equality — this API has no range filter. To bound a period, sort with `order` and page. When the reason was created — the seed writes the nine standard ones on install.
+     * @param {string} updatedAt - Exact timestamp equality — this API has no range filter. To bound a period, sort with `order` and page. When the reason last changed.
+     * @param {number} limit - Page size (default 50, max 200). A larger value is clamped to 200 rather than refused.
+     * @param {number} offset - Row offset for pagination (default 0).
+     * @param {string} order - Sort by one column: 'column' | 'column.asc' | 'column.desc'. A bare column sorts ascending, the direction is lower case, and the column has to exist — the value reaches the data plane verbatim and anything else is a 400.
+     * @throws {RevenexxException}
+     * @returns {Promise<{}>}
+     * @deprecated Use the object parameter style method for a better developer experience.
+     */
+    ordersReturnReasonsList(id?: string, code?: string, title?: string, description?: string, isDefault?: boolean, tone?: OrderVocabularyTone, position?: number, isSystem?: boolean, createdAt?: string, updatedAt?: string, limit?: number, offset?: number, order?: string): Promise<{}>;
+    /**
+     * One reason with its code, its title, the labels and descriptions per locale and the badge tone a client renders it in. Reach for it when you hold the id — from the list, or off a Cockpit row. Addressed by uuid and not by code: a `reason_code` read off a return becomes a row through GET /orders/return-reasons?code=… . Unlike the list this route does NOT seed, because an id can only have come from a set that was already read.
+     *
+     * @param {string} params.id - The return reason id (uuid) — not its code. A code is turned into a row through GET /orders/return-reasons?code=damaged.
+     * @throws {RevenexxException}
+     * @returns {Promise<Models.OrderReturnReason>}
+     */
+    ordersReturnReasonsGet(params: {
+        id: string;
+    }): Promise<Models.OrderReturnReason>;
+    /**
+     * One reason with its code, its title, the labels and descriptions per locale and the badge tone a client renders it in. Reach for it when you hold the id — from the list, or off a Cockpit row. Addressed by uuid and not by code: a `reason_code` read off a return becomes a row through GET /orders/return-reasons?code=… . Unlike the list this route does NOT seed, because an id can only have come from a set that was already read.
+     *
+     * @param {string} id - The return reason id (uuid) — not its code. A code is turned into a row through GET /orders/return-reasons?code=damaged.
+     * @throws {RevenexxException}
+     * @returns {Promise<Models.OrderReturnReason>}
+     * @deprecated Use the object parameter style method for a better developer experience.
+     */
+    ordersReturnReasonsGet(id: string): Promise<Models.OrderReturnReason>;
+    /**
+     * Which value sets this app will describe for you, by name — order statuses, payment statuses, fulfillment statuses, item types, return statuses and return resolutions — so a client can discover them instead of shipping its own copy of five statuses that goes stale one release later. The values themselves are deliberately NOT here: this is the index, and each set is fetched on its own. Discovery for the vocabulary routes. Names: cancellation-scopes, comment-visibilities, discount-applies-to, discount-effect-kinds, discount-placements, discount-sources, discount-value-types, fulfillment-statuses, item-types, payment-statuses, refund-modes, return-reason-tones, return-resolutions, return-statuses, statuses. Fetch one with GET /orders/vocabularies/{name}; a client holding the qualified pair 'orders.<name>' builds that URL from the pair alone. 'title' and 'description' are locale maps wherever somebody wrote the copy and plain strings where the fallback did — read both forms.
      *
      * @throws {RevenexxException}
      * @returns {Promise<Models.OrderVocabularyIndex>}
      */
     ordersVocabulariesList(): Promise<Models.OrderVocabularyIndex>;
     /**
-     * Everything a UI needs to render one of this app's value sets without knowing it: every permitted value, in order, each with a title and description in the locales somebody wrote and a badge tone to colour it. Fetch it once and a status filter, a status badge and a resolution picker all stay correct through a lifecycle change, because the set served IS the set enforced. It answers about values, not about rows — nothing here says how many orders are in a status. The values are read out of the column's CHECK constraint, so the served set IS the enforced set and the two cannot drift — a value added to the constraint appears here even before anyone labels it, titled from its own key. Values come back in constraint order, which is lifecycle order for a status, and 'final' marks the values that END the lifecycle (completed, cancelled) so a client can ask "is this order still open?" instead of matching names it guessed. Every set is exhaustive ('closed' is always true); 'source' says who enforces it — 'schema' for a CHECK constraint, 'app' for 'return-resolutions', whose column carries none and whose words the return routes enforce instead. Those values additionally carry 'stage' (complete | reject): the transition that accepts them. 'title' and 'description' are locale maps where the copy was written and plain strings where the key-derived fallback answered, on the vocabulary and on every value alike. Names: cancellation-scopes, comment-visibilities, fulfillment-statuses, item-types, payment-statuses, return-resolutions, return-statuses, statuses.
+     * Everything a UI needs to render one of this app's value sets without knowing it: every permitted value, in order, each with a title and description in the locales somebody wrote and a badge tone to colour it. Fetch it once and a status filter, a status badge and a resolution picker all stay correct through a lifecycle change, because the set served IS the set enforced. It answers about values, not about rows — nothing here says how many orders are in a status. The values are read out of the column's CHECK constraint, so the served set IS the enforced set and the two cannot drift — a value added to the constraint appears here even before anyone labels it, titled from its own key. Values come back in constraint order, which is lifecycle order for a status, and 'final' marks the values that END the lifecycle (completed, cancelled) so a client can ask "is this order still open?" instead of matching names it guessed. Every set is exhaustive ('closed' is always true); 'source' says who enforces it — 'schema' for a CHECK constraint, 'app' for 'return-resolutions', whose column carries none and whose words the return routes enforce instead. Those values additionally carry 'stage' (complete | reject): the transition that accepts them. 'title' and 'description' are locale maps where the copy was written and plain strings where the key-derived fallback answered, on the vocabulary and on every value alike. Names: cancellation-scopes, comment-visibilities, discount-applies-to, discount-effect-kinds, discount-placements, discount-sources, discount-value-types, fulfillment-statuses, item-types, payment-statuses, refund-modes, return-reason-tones, return-resolutions, return-statuses, statuses.
      *
      * @param {OrdersVocabulariesGetName} params.name - The vocabulary name — the part after the dot in the qualified id.
      * @throws {RevenexxException}
@@ -647,7 +925,7 @@ declare class Orders {
         name: OrdersVocabulariesGetName;
     }): Promise<Models.OrderVocabulary>;
     /**
-     * Everything a UI needs to render one of this app's value sets without knowing it: every permitted value, in order, each with a title and description in the locales somebody wrote and a badge tone to colour it. Fetch it once and a status filter, a status badge and a resolution picker all stay correct through a lifecycle change, because the set served IS the set enforced. It answers about values, not about rows — nothing here says how many orders are in a status. The values are read out of the column's CHECK constraint, so the served set IS the enforced set and the two cannot drift — a value added to the constraint appears here even before anyone labels it, titled from its own key. Values come back in constraint order, which is lifecycle order for a status, and 'final' marks the values that END the lifecycle (completed, cancelled) so a client can ask "is this order still open?" instead of matching names it guessed. Every set is exhaustive ('closed' is always true); 'source' says who enforces it — 'schema' for a CHECK constraint, 'app' for 'return-resolutions', whose column carries none and whose words the return routes enforce instead. Those values additionally carry 'stage' (complete | reject): the transition that accepts them. 'title' and 'description' are locale maps where the copy was written and plain strings where the key-derived fallback answered, on the vocabulary and on every value alike. Names: cancellation-scopes, comment-visibilities, fulfillment-statuses, item-types, payment-statuses, return-resolutions, return-statuses, statuses.
+     * Everything a UI needs to render one of this app's value sets without knowing it: every permitted value, in order, each with a title and description in the locales somebody wrote and a badge tone to colour it. Fetch it once and a status filter, a status badge and a resolution picker all stay correct through a lifecycle change, because the set served IS the set enforced. It answers about values, not about rows — nothing here says how many orders are in a status. The values are read out of the column's CHECK constraint, so the served set IS the enforced set and the two cannot drift — a value added to the constraint appears here even before anyone labels it, titled from its own key. Values come back in constraint order, which is lifecycle order for a status, and 'final' marks the values that END the lifecycle (completed, cancelled) so a client can ask "is this order still open?" instead of matching names it guessed. Every set is exhaustive ('closed' is always true); 'source' says who enforces it — 'schema' for a CHECK constraint, 'app' for 'return-resolutions', whose column carries none and whose words the return routes enforce instead. Those values additionally carry 'stage' (complete | reject): the transition that accepts them. 'title' and 'description' are locale maps where the copy was written and plain strings where the key-derived fallback answered, on the vocabulary and on every value alike. Names: cancellation-scopes, comment-visibilities, discount-applies-to, discount-effect-kinds, discount-placements, discount-sources, discount-value-types, fulfillment-statuses, item-types, payment-statuses, refund-modes, return-reason-tones, return-resolutions, return-statuses, statuses.
      *
      * @param {OrdersVocabulariesGetName} name - The vocabulary name — the part after the dot in the qualified id.
      * @throws {RevenexxException}
@@ -656,7 +934,7 @@ declare class Orders {
      */
     ordersVocabulariesGet(name: OrdersVocabulariesGetName): Promise<Models.OrderVocabulary>;
     /**
-     * The single source of order information, and what an order detail screen is built from: the order row plus its positions, its shipments with the shipment_items each one booked, its returns and its cancellations — one call, no assembling five lists. A cancellation's and a return's 'positions' are ARRAYS of {order_item_id, quantity}; a return's entries additionally carry 'restock'. Two things it does not carry: the comments and the event trail, which are their own paginated routes because both grow without bound. Addressed by uuid — an order number goes through GET /orders?number=… first.
+     * The single source of order information, and what an order detail screen is built from: the order row plus its positions, its shipments with the shipment_items each one booked, its returns and its cancellations — one call, no assembling five lists. A cancellation's and a return's 'positions' are ARRAYS of {order_item_id, quantity}; a return's entries additionally carry 'restock'. Two things it does not carry: the comments and the event trail, which are their own paginated routes because both grow without bound. Addressed by uuid — an order number goes through GET /orders?number=… first. The fields currency, grand_total, contact_id and status and the five statuses are read by other apps (payments checks a payment against them) and are stable from 1.0.
      *
      * @param {string} params.id - The order id (uuid). This segment reaches a uuid column: an order NUMBER is not accepted here — filter GET /orders by ?number= to resolve one.
      * @throws {RevenexxException}
@@ -666,7 +944,7 @@ declare class Orders {
         id: string;
     }): Promise<Models.OrderDetail>;
     /**
-     * The single source of order information, and what an order detail screen is built from: the order row plus its positions, its shipments with the shipment_items each one booked, its returns and its cancellations — one call, no assembling five lists. A cancellation's and a return's 'positions' are ARRAYS of {order_item_id, quantity}; a return's entries additionally carry 'restock'. Two things it does not carry: the comments and the event trail, which are their own paginated routes because both grow without bound. Addressed by uuid — an order number goes through GET /orders?number=… first.
+     * The single source of order information, and what an order detail screen is built from: the order row plus its positions, its shipments with the shipment_items each one booked, its returns and its cancellations — one call, no assembling five lists. A cancellation's and a return's 'positions' are ARRAYS of {order_item_id, quantity}; a return's entries additionally carry 'restock'. Two things it does not carry: the comments and the event trail, which are their own paginated routes because both grow without bound. Addressed by uuid — an order number goes through GET /orders?number=… first. The fields currency, grand_total, contact_id and status and the five statuses are read by other apps (payments checks a payment against them) and are stable from 1.0.
      *
      * @param {string} id - The order id (uuid). This segment reaches a uuid column: an order NUMBER is not accepted here — filter GET /orders by ?number= to resolve one.
      * @throws {RevenexxException}
@@ -675,15 +953,20 @@ declare class Orders {
      */
     ordersGet(id: string): Promise<Models.OrderDetail>;
     /**
-     * The narrow correction window a service desk needs: the customer gave the wrong delivery address, the buyer's name is misspelled, their purchase-order number was missing. Six columns and no others — customer_order_number, buyer, billing_address, shipping_address, user_data and metadata — and each is REPLACED whole, not merged, so send the entire address rather than the one line that changed. It moves nothing: status, payment_status, fulfillment_status and the quantities belong to the action routes, and a body carrying them is accepted with those keys quietly dropped. The window closes when the fulfilling system acknowledges the order, because from then on the ERP holds the copy that ships — unless the tenant set allow_modification_after_acknowledge. Every accepted change writes an order.updated event naming the columns it touched.
+     * The narrow correction window a service desk needs: the customer gave the wrong delivery address, the buyer's name is misspelled, their purchase-order number was missing. Ten columns and no others — customer_order_number, buyer, billing_address, shipping_address, user_data, metadata, and the four that say where the order came from (external_id, external_refs, source_synced_at, source_data) — and each is REPLACED whole, not merged, so send the entire address rather than the one line that changed. The last four are the only ones a delta run needs, and this is the only address that refreshes them without moving the order: a new ETag and a new confirmation time arrive here. It moves nothing: status, payment_status, fulfillment_status and the quantities belong to the action routes, and a body carrying them is accepted with those keys quietly dropped — except created_at and updated_at, which are the server's and answer 400 server_owned_field. The window closes when the fulfilling system acknowledges the order, because from then on the ERP holds the copy that ships — unless the tenant set allow_modification_after_acknowledge. Every accepted change writes an order.updated event naming the columns it touched.
      *
      * @param {string} params.id - The order id (uuid). This segment reaches a uuid column: an order NUMBER is not accepted here — filter GET /orders by ?number= to resolve one.
      * @param {object} params.billingAddress - The invoice address, FROZEN at place-time. Changing the customer's address afterwards does not change what this order was billed to. Replaced wholesale — send the whole address, not a patch of it.
      * @param {object} params.buyer - The ordering party as it was at place-time, FROZEN: a copy, not a reference, so the order still reads correctly after the customer record is renamed, merged or deleted. The caller decides what goes in; this app stores it and reads nothing out of it. Replaced wholesale — send the whole snapshot, not a patch of it.
      * @param {string} params.customerOrderNumber - The BUYER's own reference — their purchase-order number. Free text, not unique, never generated here: it exists so the paperwork can carry the number the buyer's accounts payable will look for. One of the few fields PUT /orders/{id} may still change.
+     * @param {string} params.externalId - The key this order has in the system that OWNS it — the ERP's own handle on the sales order, which is what a write-back addresses. Distinct from `external_ref`, which is the readable ORDER NUMBER that system quotes at a human, and from `number`, which is the one this app issued. Unique per tenant where set, so a retried import that sends the same key again is refused rather than founding a second order. Null for an order the shop owns. Replaced wholesale, and null disowns the order — no source then answers for it. Moving it to a key another order of this tenant holds is a 409.
+     * @param {object} params.externalRefs - Every OTHER system that knows this order, keyed by system name — a second ERP, a procurement platform, a portal. `external_id` is the leading system; this is the rest. Not a query parameter: a jsonb column is compared as a whole document, so look the row up by `external_id` and read this off the answer. Replaced wholesale — send the whole map, not the one system that changed.
      * @param {object} params.metadata - Free-form data belonging to the INTEGRATION side — an ERP's own bookkeeping about this order. Stored and returned untouched; nothing here reads it. Replaced wholesale.
+     * @param {string} params.requestedDeliveryDate - The calendar day the BUYER asked to be delivered on, as a date and not a moment — a buyer asks for Tuesday, not for Tuesday at 14:03 in a timezone nobody named. It is a wish and nothing here judges it: a date in the past, a weekend or a day inside the lead time is stored as sent, because what is deliverable is the merchant's answer and this app reads neither stock nor carrier calendar. The positions carry their own, and A POSITION'S DATE WINS over this one — this is the proposal for every position that names none. Null on an order that asked for nothing, which is the ordinary case. It was collected in `user_data.requested_date` before this column existed and is still echoed there by callers that have not moved over; the column is what is compared, sorted and mapped. The buyer rang up and asked for a different day. 'YYYY-MM-DD', and null withdraws the request entirely. It moves the ORDER's date only — a position that named its own keeps it, because the line wins. It is not held to any lead time here: a date the merchant cannot serve is a conversation, not a 400.
      * @param {object} params.shippingAddress - The delivery address, FROZEN at place-time — what goes on the label of every shipment of this order. Null on an order that is never delivered (a service, a digital item, a collection). Replaced wholesale. This is the one correction that actually matters after placement: the label of every shipment still to go out is printed from it.
-     * @param {object} params.userData - Free-form data belonging to the ORDERING side — carried through from the storefront or the cart and handed back untouched. One of the few fields PUT /orders/{id} may still change. Replaced wholesale.
+     * @param {object} params.sourceData - What the source said about this row, kept as it said it: `{"system": …, "etag": …, "raw": {…}}`. The `etag` is what a write-back has to send back in `If-Match`, and there is nowhere else to keep it between two runs. `raw` holds the source fields this app does not model, so they survive a round trip instead of being lost on the first edit. Nothing here reads it, and no transition clears it. Replaced wholesale, which is how a fresh ETag arrives: send what the source said THIS time, not a patch of what it said last time.
+     * @param {string} params.sourceSyncedAt - When this order was last confirmed against its source. What a delta run asks for changes since, and what tells an operator that a feed has gone quiet — an edit made here does not touch it, because it says when the SOURCE was last seen, not when the row changed. Null for a order no source owns. This is where a delta run stamps the run it confirmed the order in.
+     * @param {object} params.userData - Free-form data belonging to the ORDERING side — carried through from the storefront or the cart and handed back untouched. One of the few fields PUT /orders/{id} may still change. One key of it is read: `requested_date`, which is where the wanted delivery date was collected before it had a column, and which is taken as the date only when `requested_delivery_date` names none. The blob itself is never rewritten by that reading. Replaced wholesale — the `requested_date` key included, so a body that rewrites this blob without it drops that echo. The typed column is unaffected either way.
      * @throws {RevenexxException}
      * @returns {Promise<Models.Order>}
      */
@@ -692,49 +975,71 @@ declare class Orders {
         billingAddress?: object;
         buyer?: object;
         customerOrderNumber?: string;
+        externalId?: string;
+        externalRefs?: object;
         metadata?: object;
+        requestedDeliveryDate?: string;
         shippingAddress?: object;
+        sourceData?: object;
+        sourceSyncedAt?: string;
         userData?: object;
     }): Promise<Models.Order>;
     /**
-     * The narrow correction window a service desk needs: the customer gave the wrong delivery address, the buyer's name is misspelled, their purchase-order number was missing. Six columns and no others — customer_order_number, buyer, billing_address, shipping_address, user_data and metadata — and each is REPLACED whole, not merged, so send the entire address rather than the one line that changed. It moves nothing: status, payment_status, fulfillment_status and the quantities belong to the action routes, and a body carrying them is accepted with those keys quietly dropped. The window closes when the fulfilling system acknowledges the order, because from then on the ERP holds the copy that ships — unless the tenant set allow_modification_after_acknowledge. Every accepted change writes an order.updated event naming the columns it touched.
+     * The narrow correction window a service desk needs: the customer gave the wrong delivery address, the buyer's name is misspelled, their purchase-order number was missing. Ten columns and no others — customer_order_number, buyer, billing_address, shipping_address, user_data, metadata, and the four that say where the order came from (external_id, external_refs, source_synced_at, source_data) — and each is REPLACED whole, not merged, so send the entire address rather than the one line that changed. The last four are the only ones a delta run needs, and this is the only address that refreshes them without moving the order: a new ETag and a new confirmation time arrive here. It moves nothing: status, payment_status, fulfillment_status and the quantities belong to the action routes, and a body carrying them is accepted with those keys quietly dropped — except created_at and updated_at, which are the server's and answer 400 server_owned_field. The window closes when the fulfilling system acknowledges the order, because from then on the ERP holds the copy that ships — unless the tenant set allow_modification_after_acknowledge. Every accepted change writes an order.updated event naming the columns it touched.
      *
      * @param {string} id - The order id (uuid). This segment reaches a uuid column: an order NUMBER is not accepted here — filter GET /orders by ?number= to resolve one.
      * @param {object} billingAddress - The invoice address, FROZEN at place-time. Changing the customer's address afterwards does not change what this order was billed to. Replaced wholesale — send the whole address, not a patch of it.
      * @param {object} buyer - The ordering party as it was at place-time, FROZEN: a copy, not a reference, so the order still reads correctly after the customer record is renamed, merged or deleted. The caller decides what goes in; this app stores it and reads nothing out of it. Replaced wholesale — send the whole snapshot, not a patch of it.
      * @param {string} customerOrderNumber - The BUYER's own reference — their purchase-order number. Free text, not unique, never generated here: it exists so the paperwork can carry the number the buyer's accounts payable will look for. One of the few fields PUT /orders/{id} may still change.
+     * @param {string} externalId - The key this order has in the system that OWNS it — the ERP's own handle on the sales order, which is what a write-back addresses. Distinct from `external_ref`, which is the readable ORDER NUMBER that system quotes at a human, and from `number`, which is the one this app issued. Unique per tenant where set, so a retried import that sends the same key again is refused rather than founding a second order. Null for an order the shop owns. Replaced wholesale, and null disowns the order — no source then answers for it. Moving it to a key another order of this tenant holds is a 409.
+     * @param {object} externalRefs - Every OTHER system that knows this order, keyed by system name — a second ERP, a procurement platform, a portal. `external_id` is the leading system; this is the rest. Not a query parameter: a jsonb column is compared as a whole document, so look the row up by `external_id` and read this off the answer. Replaced wholesale — send the whole map, not the one system that changed.
      * @param {object} metadata - Free-form data belonging to the INTEGRATION side — an ERP's own bookkeeping about this order. Stored and returned untouched; nothing here reads it. Replaced wholesale.
+     * @param {string} requestedDeliveryDate - The calendar day the BUYER asked to be delivered on, as a date and not a moment — a buyer asks for Tuesday, not for Tuesday at 14:03 in a timezone nobody named. It is a wish and nothing here judges it: a date in the past, a weekend or a day inside the lead time is stored as sent, because what is deliverable is the merchant's answer and this app reads neither stock nor carrier calendar. The positions carry their own, and A POSITION'S DATE WINS over this one — this is the proposal for every position that names none. Null on an order that asked for nothing, which is the ordinary case. It was collected in `user_data.requested_date` before this column existed and is still echoed there by callers that have not moved over; the column is what is compared, sorted and mapped. The buyer rang up and asked for a different day. 'YYYY-MM-DD', and null withdraws the request entirely. It moves the ORDER's date only — a position that named its own keeps it, because the line wins. It is not held to any lead time here: a date the merchant cannot serve is a conversation, not a 400.
      * @param {object} shippingAddress - The delivery address, FROZEN at place-time — what goes on the label of every shipment of this order. Null on an order that is never delivered (a service, a digital item, a collection). Replaced wholesale. This is the one correction that actually matters after placement: the label of every shipment still to go out is printed from it.
-     * @param {object} userData - Free-form data belonging to the ORDERING side — carried through from the storefront or the cart and handed back untouched. One of the few fields PUT /orders/{id} may still change. Replaced wholesale.
+     * @param {object} sourceData - What the source said about this row, kept as it said it: `{"system": …, "etag": …, "raw": {…}}`. The `etag` is what a write-back has to send back in `If-Match`, and there is nowhere else to keep it between two runs. `raw` holds the source fields this app does not model, so they survive a round trip instead of being lost on the first edit. Nothing here reads it, and no transition clears it. Replaced wholesale, which is how a fresh ETag arrives: send what the source said THIS time, not a patch of what it said last time.
+     * @param {string} sourceSyncedAt - When this order was last confirmed against its source. What a delta run asks for changes since, and what tells an operator that a feed has gone quiet — an edit made here does not touch it, because it says when the SOURCE was last seen, not when the row changed. Null for a order no source owns. This is where a delta run stamps the run it confirmed the order in.
+     * @param {object} userData - Free-form data belonging to the ORDERING side — carried through from the storefront or the cart and handed back untouched. One of the few fields PUT /orders/{id} may still change. One key of it is read: `requested_date`, which is where the wanted delivery date was collected before it had a column, and which is taken as the date only when `requested_delivery_date` names none. The blob itself is never rewritten by that reading. Replaced wholesale — the `requested_date` key included, so a body that rewrites this blob without it drops that echo. The typed column is unaffected either way.
      * @throws {RevenexxException}
      * @returns {Promise<Models.Order>}
      * @deprecated Use the object parameter style method for a better developer experience.
      */
-    ordersUpdate(id: string, billingAddress?: object, buyer?: object, customerOrderNumber?: string, metadata?: object, shippingAddress?: object, userData?: object): Promise<Models.Order>;
+    ordersUpdate(id: string, billingAddress?: object, buyer?: object, customerOrderNumber?: string, externalId?: string, externalRefs?: object, metadata?: object, requestedDeliveryDate?: string, shippingAddress?: object, sourceData?: object, sourceSyncedAt?: string, userData?: object): Promise<Models.Order>;
     /**
-     * The return channel for whatever fulfils the order. An Integration Studio workflow picks up order.placed, books the order into the ERP, and calls this with the id the ERP gave it — which lands in external_ref and makes the two systems mutually findable. It stamps acknowledged_at from the server's clock, and that timestamp is what closes the correction window: PUT /orders/{id} refuses afterwards, because the copy that ships now lives elsewhere. It is a handshake and nothing more — it does not change status, payment_status or fulfillment_status, and it does not ship anything. Once only: a second call is a 422 rather than a silent overwrite of the first system's reference.
+     * The return channel for whatever fulfils the order. An Integration Studio workflow picks up order.placed, books the order into the ERP, and calls this with what the ERP gave it — the readable order number in external_ref, the ERP's own key in external_id, and the token a later write-back has to hand back in source_data. That is what makes the two systems mutually findable, and an external_id another order of this tenant already holds is a 409 rather than a silent second claim on the same ERP record. It stamps acknowledged_at from the server's clock, and that timestamp is what closes the correction window: PUT /orders/{id} refuses afterwards, because the copy that ships now lives elsewhere. It is a handshake and nothing more — it does not change status, payment_status or fulfillment_status, and it does not ship anything. Once only: a second call is a 422 rather than a silent overwrite of the first system's reference.
      *
      * @param {string} params.id - The order id (uuid). This segment reaches a uuid column: an order NUMBER is not accepted here — filter GET /orders by ?number= to resolve one.
+     * @param {string} params.externalId - The key this order has in the system that OWNS it — the ERP's own handle on the sales order, which is what a write-back addresses. Distinct from `external_ref`, which is the readable ORDER NUMBER that system quotes at a human, and from `number`, which is the one this app issued. Unique per tenant where set, so a retried import that sends the same key again is refused rather than founding a second order. Null for an order the shop owns. The key beside the document number, and the one a write-back addresses. Keeps the existing value when omitted; a key another order of this tenant already holds is a 409.
      * @param {string} params.externalRef - The FULFILLING system's reference for this order, typically the ERP order number. Written once by POST /orders/{id}/acknowledge and null until an integration acknowledged it. Keeps the existing value when omitted.
+     * @param {object} params.externalRefs - Every OTHER system that knows this order, keyed by system name — a second ERP, a procurement platform, a portal. `external_id` is the leading system; this is the rest. Not a query parameter: a jsonb column is compared as a whole document, so look the row up by `external_id` and read this off the answer. Keeps the existing value when omitted.
+     * @param {object} params.sourceData - What the source said about this row, kept as it said it: `{"system": …, "etag": …, "raw": {…}}`. The `etag` is what a write-back has to send back in `If-Match`, and there is nowhere else to keep it between two runs. `raw` holds the source fields this app does not model, so they survive a round trip instead of being lost on the first edit. Nothing here reads it, and no transition clears it. Where the ETag of the handover belongs. Keeps the existing value when omitted.
+     * @param {string} params.sourceSyncedAt - When this order was last confirmed against its source. What a delta run asks for changes since, and what tells an operator that a feed has gone quiet — an edit made here does not touch it, because it says when the SOURCE was last seen, not when the row changed. Null for a order no source owns. Keeps the existing value when omitted — the acknowledgement itself is stamped in acknowledged_at, which is a different fact.
      * @throws {RevenexxException}
      * @returns {Promise<Models.Order>}
      */
     ordersAcknowledge(params: {
         id: string;
+        externalId?: string;
         externalRef?: string;
+        externalRefs?: object;
+        sourceData?: object;
+        sourceSyncedAt?: string;
     }): Promise<Models.Order>;
     /**
-     * The return channel for whatever fulfils the order. An Integration Studio workflow picks up order.placed, books the order into the ERP, and calls this with the id the ERP gave it — which lands in external_ref and makes the two systems mutually findable. It stamps acknowledged_at from the server's clock, and that timestamp is what closes the correction window: PUT /orders/{id} refuses afterwards, because the copy that ships now lives elsewhere. It is a handshake and nothing more — it does not change status, payment_status or fulfillment_status, and it does not ship anything. Once only: a second call is a 422 rather than a silent overwrite of the first system's reference.
+     * The return channel for whatever fulfils the order. An Integration Studio workflow picks up order.placed, books the order into the ERP, and calls this with what the ERP gave it — the readable order number in external_ref, the ERP's own key in external_id, and the token a later write-back has to hand back in source_data. That is what makes the two systems mutually findable, and an external_id another order of this tenant already holds is a 409 rather than a silent second claim on the same ERP record. It stamps acknowledged_at from the server's clock, and that timestamp is what closes the correction window: PUT /orders/{id} refuses afterwards, because the copy that ships now lives elsewhere. It is a handshake and nothing more — it does not change status, payment_status or fulfillment_status, and it does not ship anything. Once only: a second call is a 422 rather than a silent overwrite of the first system's reference.
      *
      * @param {string} id - The order id (uuid). This segment reaches a uuid column: an order NUMBER is not accepted here — filter GET /orders by ?number= to resolve one.
+     * @param {string} externalId - The key this order has in the system that OWNS it — the ERP's own handle on the sales order, which is what a write-back addresses. Distinct from `external_ref`, which is the readable ORDER NUMBER that system quotes at a human, and from `number`, which is the one this app issued. Unique per tenant where set, so a retried import that sends the same key again is refused rather than founding a second order. Null for an order the shop owns. The key beside the document number, and the one a write-back addresses. Keeps the existing value when omitted; a key another order of this tenant already holds is a 409.
      * @param {string} externalRef - The FULFILLING system's reference for this order, typically the ERP order number. Written once by POST /orders/{id}/acknowledge and null until an integration acknowledged it. Keeps the existing value when omitted.
+     * @param {object} externalRefs - Every OTHER system that knows this order, keyed by system name — a second ERP, a procurement platform, a portal. `external_id` is the leading system; this is the rest. Not a query parameter: a jsonb column is compared as a whole document, so look the row up by `external_id` and read this off the answer. Keeps the existing value when omitted.
+     * @param {object} sourceData - What the source said about this row, kept as it said it: `{"system": …, "etag": …, "raw": {…}}`. The `etag` is what a write-back has to send back in `If-Match`, and there is nowhere else to keep it between two runs. `raw` holds the source fields this app does not model, so they survive a round trip instead of being lost on the first edit. Nothing here reads it, and no transition clears it. Where the ETag of the handover belongs. Keeps the existing value when omitted.
+     * @param {string} sourceSyncedAt - When this order was last confirmed against its source. What a delta run asks for changes since, and what tells an operator that a feed has gone quiet — an edit made here does not touch it, because it says when the SOURCE was last seen, not when the row changed. Null for a order no source owns. Keeps the existing value when omitted — the acknowledgement itself is stamped in acknowledged_at, which is a different fact.
      * @throws {RevenexxException}
      * @returns {Promise<Models.Order>}
      * @deprecated Use the object parameter style method for a better developer experience.
      */
-    ordersAcknowledge(id: string, externalRef?: string): Promise<Models.Order>;
+    ordersAcknowledge(id: string, externalId?: string, externalRef?: string, externalRefs?: object, sourceData?: object, sourceSyncedAt?: string): Promise<Models.Order>;
     /**
-     * Call the whole order off: every position's full quantity is booked as cancelled, the order moves to 'cancelled', a cancellation record is written with the reason and who gave it, and an order.cancelled event goes onto the bus. Only while NOTHING has shipped — once a single position has gone out the order is partly real and this answers 422; take the remaining quantities off with POST /orders/{id}/items/cancel instead, and handle what already shipped as a return. It refunds nothing and returns nothing to stock: payment travels through /payment-status and restocking is an explicit inventories call by the orchestrator. A tenant may require a reason (cancel_requires_reason), and a hold may block it (on_hold_blocks = 'shipping_and_cancel').
+     * Call the whole order off: every position's full quantity is booked as cancelled, the order moves to 'cancelled', a cancellation record is written with the reason and who gave it, and an order.cancelled event goes onto the bus. Only while NOTHING has shipped — once a single position has gone out the order is partly real and this answers 422; take the remaining quantities off with POST /orders/{id}/items/cancel instead, and handle what already shipped as a return. It refunds nothing and returns nothing to stock: payment travels through /payment-status and restocking is an explicit inventories call by the orchestrator. A tenant may require a reason (cancel_requires_reason), and a hold may block it (on_hold_blocks = 'shipping_and_cancel'). A pending order may be cancelled. A BUYER's own call reaches further back only: the buyer cancels while the order is pending or placed, not acknowledged by a fulfilling system and with nothing shipped — otherwise 422 order_not_cancellable, and the merchant decides.
      *
      * @param {string} params.id - The order id (uuid). This segment reaches a uuid column: an order NUMBER is not accepted here — filter GET /orders by ?number= to resolve one.
      * @param {string} params.cancelledBy - Who cancelled, as the caller reported it — an operator, a desk, a system. Free text; this app does not resolve it against a user directory.
@@ -748,7 +1053,7 @@ declare class Orders {
         reason?: string;
     }): Promise<Models.Order>;
     /**
-     * Call the whole order off: every position's full quantity is booked as cancelled, the order moves to 'cancelled', a cancellation record is written with the reason and who gave it, and an order.cancelled event goes onto the bus. Only while NOTHING has shipped — once a single position has gone out the order is partly real and this answers 422; take the remaining quantities off with POST /orders/{id}/items/cancel instead, and handle what already shipped as a return. It refunds nothing and returns nothing to stock: payment travels through /payment-status and restocking is an explicit inventories call by the orchestrator. A tenant may require a reason (cancel_requires_reason), and a hold may block it (on_hold_blocks = 'shipping_and_cancel').
+     * Call the whole order off: every position's full quantity is booked as cancelled, the order moves to 'cancelled', a cancellation record is written with the reason and who gave it, and an order.cancelled event goes onto the bus. Only while NOTHING has shipped — once a single position has gone out the order is partly real and this answers 422; take the remaining quantities off with POST /orders/{id}/items/cancel instead, and handle what already shipped as a return. It refunds nothing and returns nothing to stock: payment travels through /payment-status and restocking is an explicit inventories call by the orchestrator. A tenant may require a reason (cancel_requires_reason), and a hold may block it (on_hold_blocks = 'shipping_and_cancel'). A pending order may be cancelled. A BUYER's own call reaches further back only: the buyer cancels while the order is pending or placed, not acknowledged by a fulfilling system and with nothing shipped — otherwise 422 order_not_cancellable, and the merchant decides.
      *
      * @param {string} id - The order id (uuid). This segment reaches a uuid column: an order NUMBER is not accepted here — filter GET /orders by ?number= to resolve one.
      * @param {string} cancelledBy - Who cancelled, as the caller reported it — an operator, a desk, a system. Free text; this app does not resolve it against a user directory.
@@ -759,7 +1064,7 @@ declare class Orders {
      */
     ordersCancel(id: string, cancelledBy?: string, reason?: string): Promise<Models.Order>;
     /**
-     * What people have written about this order, oldest first: the service desk's own notes and the messages meant for the customer, in one list. Filter by ?visibility=customer to build the version a customer may see, and by ?visibility=internal for the desk's own — the route does NOT decide that for you, so a customer-facing surface has to ask for the customer ones. Comments are prose about the order and never move it; the lifecycle lives in the event trail. Every parameter below is an exact match on the column it names. `order_id` is deliberately absent: the route fixes it from the path AFTER the query filter is read, so sending one is accepted and then overwritten — it filters nothing. DEPRECATED KEY: the response also repeats 'items' under 'comments' for compatibility with the pre-envelope shape. It is the same array; read 'items'. The alias is removed in the next minor version.
+     * What people have written about this order, oldest first: the service desk's own notes and the messages meant for the customer, in one list. Filter by ?visibility=customer to build the version a customer may see, and by ?visibility=internal for the desk's own — on a back-office call the route does NOT decide that for you; on a buyer's own call it does, and only the customer-visible ones exist (asking for ?visibility=internal is 403 buyer_not_permitted). Comments are prose about the order and never move it; the lifecycle lives in the event trail. Every parameter below is an exact match on the column it names. `order_id` is deliberately absent: the route fixes it from the path AFTER the query filter is read, so sending one is accepted and then overwritten — it filters nothing.
      *
      * @param {string} params.id - The order id (uuid). This segment reaches a uuid column: an order NUMBER is not accepted here — filter GET /orders by ?number= to resolve one.
      * @param {string} params.idQuery - Filter to rows whose `id` is exactly this value. Primary key of the comment.
@@ -785,7 +1090,7 @@ declare class Orders {
         order?: string;
     }): Promise<{}>;
     /**
-     * What people have written about this order, oldest first: the service desk's own notes and the messages meant for the customer, in one list. Filter by ?visibility=customer to build the version a customer may see, and by ?visibility=internal for the desk's own — the route does NOT decide that for you, so a customer-facing surface has to ask for the customer ones. Comments are prose about the order and never move it; the lifecycle lives in the event trail. Every parameter below is an exact match on the column it names. `order_id` is deliberately absent: the route fixes it from the path AFTER the query filter is read, so sending one is accepted and then overwritten — it filters nothing. DEPRECATED KEY: the response also repeats 'items' under 'comments' for compatibility with the pre-envelope shape. It is the same array; read 'items'. The alias is removed in the next minor version.
+     * What people have written about this order, oldest first: the service desk's own notes and the messages meant for the customer, in one list. Filter by ?visibility=customer to build the version a customer may see, and by ?visibility=internal for the desk's own — on a back-office call the route does NOT decide that for you; on a buyer's own call it does, and only the customer-visible ones exist (asking for ?visibility=internal is 403 buyer_not_permitted). Comments are prose about the order and never move it; the lifecycle lives in the event trail. Every parameter below is an exact match on the column it names. `order_id` is deliberately absent: the route fixes it from the path AFTER the query filter is read, so sending one is accepted and then overwritten — it filters nothing.
      *
      * @param {string} id - The order id (uuid). This segment reaches a uuid column: an order NUMBER is not accepted here — filter GET /orders by ?number= to resolve one.
      * @param {string} idQuery - Filter to rows whose `id` is exactly this value. Primary key of the comment.
@@ -802,7 +1107,7 @@ declare class Orders {
      */
     ordersCommentsList(id: string, idQuery?: string, body?: string, visibility?: OrderCommentVisibility, author?: string, createdAt?: string, limit?: number, offset?: number, order?: string): Promise<{}>;
     /**
-     * Write down what happened that the state machine cannot record: what the customer said on the phone, why an exception was made, what the warehouse found in the box. `visibility` decides who the note is for — 'internal' for the service desk, 'customer' for text meant to be shown to the buyer — and it defaults to the tenant's default_comment_visibility, which is 'internal' out of the box, so a note is never accidentally customer-facing. Adding one writes an order.comment.added event, so the trail shows that a note was made and its visibility, without copying the text onto the bus. It changes nothing about the order, and it sends nothing to anybody: this stores a comment, it does not email the customer.
+     * Write down what happened that the state machine cannot record: what the customer said on the phone, why an exception was made, what the warehouse found in the box. `visibility` decides who the note is for — 'internal' for the service desk, 'customer' for text meant to be shown to the buyer — and it defaults to the tenant's default_comment_visibility, which is 'internal' out of the box, so a note is never accidentally customer-facing. Adding one writes an order.comment.added event, so the trail shows that a note was made and its visibility, without copying the text onto the bus. It changes nothing about the order, and it sends nothing to anybody: this stores a comment, it does not email the customer. On a buyer's own call the note is always 'customer' — a buyer writes to the merchant, not into the desk's internal notes, and asking for 'internal' is 403 buyer_not_permitted.
      *
      * @param {string} params.id - The order id (uuid). This segment reaches a uuid column: an order NUMBER is not accepted here — filter GET /orders by ?number= to resolve one.
      * @param {string} params.body - The comment itself. Plain text; this app neither renders nor sanitizes it.
@@ -818,7 +1123,7 @@ declare class Orders {
         visibility?: OrderCommentVisibility;
     }): Promise<Models.OrderComment>;
     /**
-     * Write down what happened that the state machine cannot record: what the customer said on the phone, why an exception was made, what the warehouse found in the box. `visibility` decides who the note is for — 'internal' for the service desk, 'customer' for text meant to be shown to the buyer — and it defaults to the tenant's default_comment_visibility, which is 'internal' out of the box, so a note is never accidentally customer-facing. Adding one writes an order.comment.added event, so the trail shows that a note was made and its visibility, without copying the text onto the bus. It changes nothing about the order, and it sends nothing to anybody: this stores a comment, it does not email the customer.
+     * Write down what happened that the state machine cannot record: what the customer said on the phone, why an exception was made, what the warehouse found in the box. `visibility` decides who the note is for — 'internal' for the service desk, 'customer' for text meant to be shown to the buyer — and it defaults to the tenant's default_comment_visibility, which is 'internal' out of the box, so a note is never accidentally customer-facing. Adding one writes an order.comment.added event, so the trail shows that a note was made and its visibility, without copying the text onto the bus. It changes nothing about the order, and it sends nothing to anybody: this stores a comment, it does not email the customer. On a buyer's own call the note is always 'customer' — a buyer writes to the merchant, not into the desk's internal notes, and asking for 'internal' is 403 buyer_not_permitted.
      *
      * @param {string} id - The order id (uuid). This segment reaches a uuid column: an order NUMBER is not accepted here — filter GET /orders by ?number= to resolve one.
      * @param {string} body - The comment itself. Plain text; this app neither renders nor sanitizes it.
@@ -852,7 +1157,7 @@ declare class Orders {
      */
     ordersComplete(id: string, completedBy?: string): Promise<Models.Order>;
     /**
-     * Everything that has ever happened to this order, oldest first: placed or requested, updated, acknowledged, shipped, held, paid, returned, completed, cancelled — each with the payload the action carried. This is the audit trail an operator reads to answer "why is this order in this state", and it is the same row the platform publishes as a domain event, so what a workflow reacted to and what a person sees here cannot diverge. It is append-only and this route is read-only: rows are written by the action routes and there is no way to add, edit or remove one. An order's trail grows for as long as the order lives, so it is paginated like every other list — 'page.hasMore' says whether more of it exists. Every parameter below is an exact match on the column it names; `order_id` is deliberately absent, because the route fixes it from the path after the query filter is read and a value sent for it is overwritten rather than honoured. The jsonb column 'payload' is not offered for the same reason it is not offered on the order list: the data plane answers 400 for anything that is not a whole JSON document. DEPRECATED KEY: the response also repeats 'items' under 'events' for compatibility with the pre-envelope shape. It is the same array; read 'items'. The alias is removed in the next minor version.
+     * Everything that has ever happened to this order, oldest first: placed or requested, updated, acknowledged, shipped, held, paid, returned, completed, cancelled — each with the payload the action carried. This is the audit trail an operator reads to answer "why is this order in this state", and it is the same row the platform publishes as a domain event, so what a workflow reacted to and what a person sees here cannot diverge. It is append-only and this route is read-only: rows are written by the action routes and there is no way to add, edit or remove one. An order's trail grows for as long as the order lives, so it is paginated like every other list — 'page.hasMore' says whether more of it exists. Every parameter below is an exact match on the column it names; `order_id` is deliberately absent, because the route fixes it from the path after the query filter is read and a value sent for it is overwritten rather than honoured. The jsonb column 'payload' is not offered for the same reason it is not offered on the order list: the data plane answers 400 for anything that is not a whole JSON document.
      *
      * @param {string} params.id - The order id (uuid). This segment reaches a uuid column: an order NUMBER is not accepted here — filter GET /orders by ?number= to resolve one.
      * @param {string} params.idQuery - Filter to rows whose `id` is exactly this value. Primary key of the event row.
@@ -876,7 +1181,7 @@ declare class Orders {
         order?: string;
     }): Promise<{}>;
     /**
-     * Everything that has ever happened to this order, oldest first: placed or requested, updated, acknowledged, shipped, held, paid, returned, completed, cancelled — each with the payload the action carried. This is the audit trail an operator reads to answer "why is this order in this state", and it is the same row the platform publishes as a domain event, so what a workflow reacted to and what a person sees here cannot diverge. It is append-only and this route is read-only: rows are written by the action routes and there is no way to add, edit or remove one. An order's trail grows for as long as the order lives, so it is paginated like every other list — 'page.hasMore' says whether more of it exists. Every parameter below is an exact match on the column it names; `order_id` is deliberately absent, because the route fixes it from the path after the query filter is read and a value sent for it is overwritten rather than honoured. The jsonb column 'payload' is not offered for the same reason it is not offered on the order list: the data plane answers 400 for anything that is not a whole JSON document. DEPRECATED KEY: the response also repeats 'items' under 'events' for compatibility with the pre-envelope shape. It is the same array; read 'items'. The alias is removed in the next minor version.
+     * Everything that has ever happened to this order, oldest first: placed or requested, updated, acknowledged, shipped, held, paid, returned, completed, cancelled — each with the payload the action carried. This is the audit trail an operator reads to answer "why is this order in this state", and it is the same row the platform publishes as a domain event, so what a workflow reacted to and what a person sees here cannot diverge. It is append-only and this route is read-only: rows are written by the action routes and there is no way to add, edit or remove one. An order's trail grows for as long as the order lives, so it is paginated like every other list — 'page.hasMore' says whether more of it exists. Every parameter below is an exact match on the column it names; `order_id` is deliberately absent, because the route fixes it from the path after the query filter is read and a value sent for it is overwritten rather than honoured. The jsonb column 'payload' is not offered for the same reason it is not offered on the order list: the data plane answers 400 for anything that is not a whole JSON document.
      *
      * @param {string} id - The order id (uuid). This segment reaches a uuid column: an order NUMBER is not accepted here — filter GET /orders by ?number= to resolve one.
      * @param {string} idQuery - Filter to rows whose `id` is exactly this value. Primary key of the event row.
@@ -967,38 +1272,53 @@ declare class Orders {
      */
     ordersPaymentStatusUpdate(id: string, status: OrderPaymentStatus, paymentId?: string): Promise<Models.Order>;
     /**
-     * Open a return case: the customer has announced goods are coming back, and this is where that becomes a tracked thing with a return number of its own, drawn from the tenant's return range. Positions are guarded against what actually SHIPPED and has not already come back, so a return cannot exceed the goods that left. Each position carries a `restock` flag saying whether the item is expected to be sellable again — recorded now, acted on only when the return completes. Omitting `positions` registers everything still returnable, the 'the customer sent the whole delivery back' case. Nothing is booked yet: quantity_returned stays where it is and the order does not move — the return starts as 'registered' and travels through receive and complete or reject. Allowed on a completed order, refused on a cancelled one.
+     * Open a return case: the customer has announced goods are coming back, and this is where that becomes a tracked thing with a return number of its own, drawn from the tenant's return range. Positions are guarded against what actually SHIPPED and is neither back nor already claimed by another open return, so two returns cannot claim the same pieces. Each position carries a `restock` flag saying whether the item is expected to be sellable again — recorded now, acted on only when the return completes. Omitting `positions` registers everything still returnable, the 'the customer sent the whole delivery back' case. Nothing is booked yet: quantity_returned stays where it is and the order does not move — the return starts as 'registered' and travels through receive and complete or reject. Allowed on a completed order, refused on a cancelled one.
      *
      * @param {string} params.id - The order id (uuid). This segment reaches a uuid column: an order NUMBER is not accepted here — filter GET /orders by ?number= to resolve one.
+     * @param {string} params.externalId - The key this return case has in the system that owns it — an ERP return order, an RMA portal's case handle. `number` beside it is the return number the customer writes on the parcel; this is what a write-back addresses. Unique per tenant where set. Null for a return registered here. Send it when the case was opened in an RMA portal or an ERP — that system then finds this return again by its own key. The three transitions below do not take it: a return is registered once, and its provenance is set there.
+     * @param {object} params.externalRefs - Every OTHER system that knows this return, keyed by system name — a second ERP, a procurement platform, a portal. `external_id` is the leading system; this is the rest. Not a query parameter: a jsonb column is compared as a whole document, so look the row up by `external_id` and read this off the answer.
      * @param {object} params.metadata - Free-form data for the caller — the returns portal's own reference. Stored and returned untouched.
      * @param {Models.OrderReturnPosition[]} params.positions - What is coming back. Omitted = every position with a returnable (shipped, not yet returned) quantity, in full.
-     * @param {string} params.reason - Why the goods are coming back, free text as the customer or the desk stated it. Also what /reject stores when it is given no resolution out of the published set.
+     * @param {string} params.reason - Why the goods are coming back, free text as the customer or the desk stated it — the sentence beside the code, not a replacement for it. Also what /reject stores when it is given no resolution out of the published set.
+     * @param {string} params.reasonCode - Why the goods are coming back, as a code out of the set THIS TENANT keeps — GET /orders/return-reasons lists them. This is the field a report groups by; `reason` beside it is the sentence somebody wrote about this one return, and the two are separate because 'Damaged', 'damaged' and 'arrived broken' were one reason counted three times. Null on a return registered without one, which is allowed. There is no foreign key behind it: the registration refuses a code the tenant does not keep, and a code retired afterwards leaves the return carrying it rather than breaking it. Read the codes from GET /orders/return-reasons. Lowercased on the way in. A code this tenant does not keep is a 400 that names the ones it does; omit it and the return is registered without a code, which is allowed. Send `reason` beside it for the sentence — the two are not alternatives.
      * @param {boolean} params.restock - The default restock flag for positions that carry none of their own — and the only way to say "put it all back into stock" when the positions are defaulted. It does not restock anything itself: it decides what the completion REPORTS for the orchestrator's inventories.restock call.
+     * @param {object} params.sourceData - What the source said about this row, kept as it said it: `{"system": …, "etag": …, "raw": {…}}`. The `etag` is what a write-back has to send back in `If-Match`, and there is nowhere else to keep it between two runs. `raw` holds the source fields this app does not model, so they survive a round trip instead of being lost on the first edit. Nothing here reads it, and no transition clears it.
+     * @param {string} params.sourceSyncedAt - When this return was last confirmed against its source. What a delta run asks for changes since, and what tells an operator that a feed has gone quiet — an edit made here does not touch it, because it says when the SOURCE was last seen, not when the row changed. Null for a return no source owns.
      * @throws {RevenexxException}
      * @returns {Promise<Models.OrderReturn>}
      */
     ordersReturn(params: {
         id: string;
+        externalId?: string;
+        externalRefs?: object;
         metadata?: object;
         positions?: Models.OrderReturnPosition[];
         reason?: string;
+        reasonCode?: string;
         restock?: boolean;
+        sourceData?: object;
+        sourceSyncedAt?: string;
     }): Promise<Models.OrderReturn>;
     /**
-     * Open a return case: the customer has announced goods are coming back, and this is where that becomes a tracked thing with a return number of its own, drawn from the tenant's return range. Positions are guarded against what actually SHIPPED and has not already come back, so a return cannot exceed the goods that left. Each position carries a `restock` flag saying whether the item is expected to be sellable again — recorded now, acted on only when the return completes. Omitting `positions` registers everything still returnable, the 'the customer sent the whole delivery back' case. Nothing is booked yet: quantity_returned stays where it is and the order does not move — the return starts as 'registered' and travels through receive and complete or reject. Allowed on a completed order, refused on a cancelled one.
+     * Open a return case: the customer has announced goods are coming back, and this is where that becomes a tracked thing with a return number of its own, drawn from the tenant's return range. Positions are guarded against what actually SHIPPED and is neither back nor already claimed by another open return, so two returns cannot claim the same pieces. Each position carries a `restock` flag saying whether the item is expected to be sellable again — recorded now, acted on only when the return completes. Omitting `positions` registers everything still returnable, the 'the customer sent the whole delivery back' case. Nothing is booked yet: quantity_returned stays where it is and the order does not move — the return starts as 'registered' and travels through receive and complete or reject. Allowed on a completed order, refused on a cancelled one.
      *
      * @param {string} id - The order id (uuid). This segment reaches a uuid column: an order NUMBER is not accepted here — filter GET /orders by ?number= to resolve one.
+     * @param {string} externalId - The key this return case has in the system that owns it — an ERP return order, an RMA portal's case handle. `number` beside it is the return number the customer writes on the parcel; this is what a write-back addresses. Unique per tenant where set. Null for a return registered here. Send it when the case was opened in an RMA portal or an ERP — that system then finds this return again by its own key. The three transitions below do not take it: a return is registered once, and its provenance is set there.
+     * @param {object} externalRefs - Every OTHER system that knows this return, keyed by system name — a second ERP, a procurement platform, a portal. `external_id` is the leading system; this is the rest. Not a query parameter: a jsonb column is compared as a whole document, so look the row up by `external_id` and read this off the answer.
      * @param {object} metadata - Free-form data for the caller — the returns portal's own reference. Stored and returned untouched.
      * @param {Models.OrderReturnPosition[]} positions - What is coming back. Omitted = every position with a returnable (shipped, not yet returned) quantity, in full.
-     * @param {string} reason - Why the goods are coming back, free text as the customer or the desk stated it. Also what /reject stores when it is given no resolution out of the published set.
+     * @param {string} reason - Why the goods are coming back, free text as the customer or the desk stated it — the sentence beside the code, not a replacement for it. Also what /reject stores when it is given no resolution out of the published set.
+     * @param {string} reasonCode - Why the goods are coming back, as a code out of the set THIS TENANT keeps — GET /orders/return-reasons lists them. This is the field a report groups by; `reason` beside it is the sentence somebody wrote about this one return, and the two are separate because 'Damaged', 'damaged' and 'arrived broken' were one reason counted three times. Null on a return registered without one, which is allowed. There is no foreign key behind it: the registration refuses a code the tenant does not keep, and a code retired afterwards leaves the return carrying it rather than breaking it. Read the codes from GET /orders/return-reasons. Lowercased on the way in. A code this tenant does not keep is a 400 that names the ones it does; omit it and the return is registered without a code, which is allowed. Send `reason` beside it for the sentence — the two are not alternatives.
      * @param {boolean} restock - The default restock flag for positions that carry none of their own — and the only way to say "put it all back into stock" when the positions are defaulted. It does not restock anything itself: it decides what the completion REPORTS for the orchestrator's inventories.restock call.
+     * @param {object} sourceData - What the source said about this row, kept as it said it: `{"system": …, "etag": …, "raw": {…}}`. The `etag` is what a write-back has to send back in `If-Match`, and there is nowhere else to keep it between two runs. `raw` holds the source fields this app does not model, so they survive a round trip instead of being lost on the first edit. Nothing here reads it, and no transition clears it.
+     * @param {string} sourceSyncedAt - When this return was last confirmed against its source. What a delta run asks for changes since, and what tells an operator that a feed has gone quiet — an edit made here does not touch it, because it says when the SOURCE was last seen, not when the row changed. Null for a return no source owns.
      * @throws {RevenexxException}
      * @returns {Promise<Models.OrderReturn>}
      * @deprecated Use the object parameter style method for a better developer experience.
      */
-    ordersReturn(id: string, metadata?: object, positions?: Models.OrderReturnPosition[], reason?: string, restock?: boolean): Promise<Models.OrderReturn>;
+    ordersReturn(id: string, externalId?: string, externalRefs?: object, metadata?: object, positions?: Models.OrderReturnPosition[], reason?: string, reasonCode?: string, restock?: boolean, sourceData?: object, sourceSyncedAt?: string): Promise<Models.OrderReturn>;
     /**
-     * Accept the return and close the case: the goods are taken back on the order's books and the settlement is recorded as one of the published words — refunded, credited, replaced and so on. This is the step a refund or a credit note hangs off, and the only step that moves quantity_returned. It does not refund money and does not put stock back itself: the answer's 'restock' array names what the orchestrator should hand to inventories.restock, and payment travels through /payment-status. Once completed the return is final — receive, complete and reject all refuse afterwards. The goods accounting moves here and nowhere else: quantity_returned is booked onto each position, completed_at is stamped by the SERVER, and positions flagged restock are reported back in the answer's 'restock' array for the orchestrator's inventories.restock call. 'resolution' is validated against the settlement words this app publishes (refund, partial_refund, replacement, repair, store_credit — see GET /orders/vocabularies/return-resolutions); anything else is refused rather than stored as a word no reader knows. It is checked before the positions are booked, so a rejected value leaves nothing behind.
+     * Accept the return and close the case: the goods are taken back on the order's books and the settlement is recorded as one of the published words — refunded, credited, replaced and so on. This is the step a refund or a credit note hangs off, and the only step that moves quantity_returned. It does not refund money and does not put stock back itself: the answer's 'restock' array names what the orchestrator should hand to inventories.restock, and payment travels through /payment-status. Once completed the return is final — receive, complete and reject all refuse afterwards. The goods accounting moves here and nowhere else: quantity_returned is booked onto each position, completed_at is stamped by the SERVER, and positions flagged restock are reported back in the answer's 'restock' array for the orchestrator's inventories.restock call. 'resolution' is validated against the settlement words this app publishes (refund, partial_refund, replacement, repair, store_credit — see GET /orders/vocabularies/return-resolutions); anything else is refused rather than stored as a word no reader knows. It is checked before the positions are booked, so a rejected value leaves nothing behind. The refunds of all completed returns of one order together never exceed its grand_total: a refund_total that would cross it is 422 refund_exceeds_order, checked before anything is booked.
      *
      * @param {string} params.id - The order id (uuid). This segment reaches a uuid column: an order NUMBER is not accepted here — filter GET /orders by ?number= to resolve one.
      * @param {string} params.rid - The return id (uuid). It must belong to the order in {id} — a return of another order is a 404, not a cross-order write.
@@ -1012,7 +1332,7 @@ declare class Orders {
         resolution?: OrderReturnSettlement;
     }): Promise<Models.OrderReturnCompleted>;
     /**
-     * Accept the return and close the case: the goods are taken back on the order's books and the settlement is recorded as one of the published words — refunded, credited, replaced and so on. This is the step a refund or a credit note hangs off, and the only step that moves quantity_returned. It does not refund money and does not put stock back itself: the answer's 'restock' array names what the orchestrator should hand to inventories.restock, and payment travels through /payment-status. Once completed the return is final — receive, complete and reject all refuse afterwards. The goods accounting moves here and nowhere else: quantity_returned is booked onto each position, completed_at is stamped by the SERVER, and positions flagged restock are reported back in the answer's 'restock' array for the orchestrator's inventories.restock call. 'resolution' is validated against the settlement words this app publishes (refund, partial_refund, replacement, repair, store_credit — see GET /orders/vocabularies/return-resolutions); anything else is refused rather than stored as a word no reader knows. It is checked before the positions are booked, so a rejected value leaves nothing behind.
+     * Accept the return and close the case: the goods are taken back on the order's books and the settlement is recorded as one of the published words — refunded, credited, replaced and so on. This is the step a refund or a credit note hangs off, and the only step that moves quantity_returned. It does not refund money and does not put stock back itself: the answer's 'restock' array names what the orchestrator should hand to inventories.restock, and payment travels through /payment-status. Once completed the return is final — receive, complete and reject all refuse afterwards. The goods accounting moves here and nowhere else: quantity_returned is booked onto each position, completed_at is stamped by the SERVER, and positions flagged restock are reported back in the answer's 'restock' array for the orchestrator's inventories.restock call. 'resolution' is validated against the settlement words this app publishes (refund, partial_refund, replacement, repair, store_credit — see GET /orders/vocabularies/return-resolutions); anything else is refused rather than stored as a word no reader knows. It is checked before the positions are booked, so a rejected value leaves nothing behind. The refunds of all completed returns of one order together never exceed its grand_total: a refund_total that would cross it is 422 refund_exceeds_order, checked before anything is booked.
      *
      * @param {string} id - The order id (uuid). This segment reaches a uuid column: an order NUMBER is not accepted here — filter GET /orders by ?number= to resolve one.
      * @param {string} rid - The return id (uuid). It must belong to the order in {id} — a return of another order is a 404, not a cross-order write.
@@ -1080,10 +1400,14 @@ declare class Orders {
      *
      * @param {string} params.id - The order id (uuid). This segment reaches a uuid column: an order NUMBER is not accepted here — filter GET /orders by ?number= to resolve one.
      * @param {string} params.carrier - Who is carrying it, in the merchant's own words. Free text — this app neither validates it nor knows the carrier's API.
+     * @param {string} params.externalId - The key this shipment has in the system that issued it — the ERP's or the warehouse's handle on the delivery. `number` beside it is the DELIVERY NOTE number, which is what a customer asking after their parcel quotes; this is what a write-back addresses. Unique per tenant where set. Null for a shipment booked here. Send it when the delivery was issued elsewhere — `number` then carries that system's delivery-note number and this carries its key. A key another shipment of this tenant holds is a 409.
+     * @param {object} params.externalRefs - Every OTHER system that knows this shipment, keyed by system name — a second ERP, a procurement platform, a portal. `external_id` is the leading system; this is the rest. Not a query parameter: a jsonb column is compared as a whole document, so look the row up by `external_id` and read this off the answer.
      * @param {object} params.metadata - Free-form data for the caller — the warehouse system's own reference for this handover. Stored and returned untouched.
      * @param {string} params.number - The DELIVERY NOTE number — drawn from the tenant's delivery range, unique per tenant, and a different series from the order number. A caller may supply its own when the number is issued by the warehouse system instead. Drawn from the 'delivery' range when omitted; supply one only when the number is issued elsewhere.
      * @param {Models.OrderShipmentPosition[]} params.positions - What this shipment carries. Omitted = every position with an open quantity, in full. GET /orders/{id}/shippable answers exactly the budget each one is guarded against.
      * @param {string} params.shippedAt - When the goods actually left. Defaults to now, and a caller may backdate it — a shipment booked on Monday for a Friday handover says Friday.
+     * @param {object} params.sourceData - What the source said about this row, kept as it said it: `{"system": …, "etag": …, "raw": {…}}`. The `etag` is what a write-back has to send back in `If-Match`, and there is nowhere else to keep it between two runs. `raw` holds the source fields this app does not model, so they survive a round trip instead of being lost on the first edit. Nothing here reads it, and no transition clears it.
+     * @param {string} params.sourceSyncedAt - When this shipment was last confirmed against its source. What a delta run asks for changes since, and what tells an operator that a feed has gone quiet — an edit made here does not touch it, because it says when the SOURCE was last seen, not when the row changed. Null for a shipment no source owns.
      * @param {string} params.trackingCode - The consignment number the carrier issued. Free text: every carrier formats it differently and this app stores whatever it is given.
      * @param {string} params.trackingUrl - Where a human can follow the parcel. Supplied by the caller — this app does not build it, because only the caller knows the carrier's tracking address.
      * @throws {RevenexxException}
@@ -1092,10 +1416,14 @@ declare class Orders {
     ordersShip(params: {
         id: string;
         carrier?: string;
+        externalId?: string;
+        externalRefs?: object;
         metadata?: object;
         number?: string;
         positions?: Models.OrderShipmentPosition[];
         shippedAt?: string;
+        sourceData?: object;
+        sourceSyncedAt?: string;
         trackingCode?: string;
         trackingUrl?: string;
     }): Promise<Models.OrderShipmentCreated>;
@@ -1104,19 +1432,23 @@ declare class Orders {
      *
      * @param {string} id - The order id (uuid). This segment reaches a uuid column: an order NUMBER is not accepted here — filter GET /orders by ?number= to resolve one.
      * @param {string} carrier - Who is carrying it, in the merchant's own words. Free text — this app neither validates it nor knows the carrier's API.
+     * @param {string} externalId - The key this shipment has in the system that issued it — the ERP's or the warehouse's handle on the delivery. `number` beside it is the DELIVERY NOTE number, which is what a customer asking after their parcel quotes; this is what a write-back addresses. Unique per tenant where set. Null for a shipment booked here. Send it when the delivery was issued elsewhere — `number` then carries that system's delivery-note number and this carries its key. A key another shipment of this tenant holds is a 409.
+     * @param {object} externalRefs - Every OTHER system that knows this shipment, keyed by system name — a second ERP, a procurement platform, a portal. `external_id` is the leading system; this is the rest. Not a query parameter: a jsonb column is compared as a whole document, so look the row up by `external_id` and read this off the answer.
      * @param {object} metadata - Free-form data for the caller — the warehouse system's own reference for this handover. Stored and returned untouched.
      * @param {string} number - The DELIVERY NOTE number — drawn from the tenant's delivery range, unique per tenant, and a different series from the order number. A caller may supply its own when the number is issued by the warehouse system instead. Drawn from the 'delivery' range when omitted; supply one only when the number is issued elsewhere.
      * @param {Models.OrderShipmentPosition[]} positions - What this shipment carries. Omitted = every position with an open quantity, in full. GET /orders/{id}/shippable answers exactly the budget each one is guarded against.
      * @param {string} shippedAt - When the goods actually left. Defaults to now, and a caller may backdate it — a shipment booked on Monday for a Friday handover says Friday.
+     * @param {object} sourceData - What the source said about this row, kept as it said it: `{"system": …, "etag": …, "raw": {…}}`. The `etag` is what a write-back has to send back in `If-Match`, and there is nowhere else to keep it between two runs. `raw` holds the source fields this app does not model, so they survive a round trip instead of being lost on the first edit. Nothing here reads it, and no transition clears it.
+     * @param {string} sourceSyncedAt - When this shipment was last confirmed against its source. What a delta run asks for changes since, and what tells an operator that a feed has gone quiet — an edit made here does not touch it, because it says when the SOURCE was last seen, not when the row changed. Null for a shipment no source owns.
      * @param {string} trackingCode - The consignment number the carrier issued. Free text: every carrier formats it differently and this app stores whatever it is given.
      * @param {string} trackingUrl - Where a human can follow the parcel. Supplied by the caller — this app does not build it, because only the caller knows the carrier's tracking address.
      * @throws {RevenexxException}
      * @returns {Promise<Models.OrderShipmentCreated>}
      * @deprecated Use the object parameter style method for a better developer experience.
      */
-    ordersShip(id: string, carrier?: string, metadata?: object, number?: string, positions?: Models.OrderShipmentPosition[], shippedAt?: string, trackingCode?: string, trackingUrl?: string): Promise<Models.OrderShipmentCreated>;
+    ordersShip(id: string, carrier?: string, externalId?: string, externalRefs?: object, metadata?: object, number?: string, positions?: Models.OrderShipmentPosition[], shippedAt?: string, sourceData?: object, sourceSyncedAt?: string, trackingCode?: string, trackingUrl?: string): Promise<Models.OrderShipmentCreated>;
     /**
-     * What a shipment dialog needs before it can offer anything: the open quantity per position, and one boolean saying whether a shipment would be accepted at all. Reach for it to fill a picking screen or to decide whether a 'create shipment' button is enabled, instead of subtracting the quantities client-side. It changes nothing and books nothing — it is the question POST /orders/{id}/ship answers with an action. The read half of orders.ship. The open quantity per position and the two guards (cancelled/completed order, hold) are the SAME code the ship route runs, so what this answers and what that accepts cannot drift — a client subtracting the quantities itself eventually offers a shipment the server refuses, or one it should have refused. 'shippable' is false with a 'blocked_reason' when the order is held, cancelled, completed or has nothing open.
+     * What a shipment dialog needs before it can offer anything: the open quantity per position, and one boolean saying whether a shipment would be accepted at all. Reach for it to fill a picking screen or to decide whether a 'create shipment' button is enabled, instead of subtracting the quantities client-side. It changes nothing and books nothing — it is the question POST /orders/{id}/ship answers with an action. The read half of orders.ship. The open quantity per position and the two guards (cancelled/completed order, hold) are the SAME code the ship route runs, so what this answers and what that accepts cannot drift — a client subtracting the quantities itself eventually offers a shipment the server refuses, or one it should have refused. 'shippable' is false with a 'blocked_reason' when the order is held, cancelled, completed, still pending approval or has nothing open. A discount placed as a position of its own is money, not goods, and is not listed.
      *
      * @param {string} params.id - The order id (uuid). This segment reaches a uuid column: an order NUMBER is not accepted here — filter GET /orders by ?number= to resolve one.
      * @throws {RevenexxException}
@@ -1126,7 +1458,7 @@ declare class Orders {
         id: string;
     }): Promise<Models.OrderShippable>;
     /**
-     * What a shipment dialog needs before it can offer anything: the open quantity per position, and one boolean saying whether a shipment would be accepted at all. Reach for it to fill a picking screen or to decide whether a 'create shipment' button is enabled, instead of subtracting the quantities client-side. It changes nothing and books nothing — it is the question POST /orders/{id}/ship answers with an action. The read half of orders.ship. The open quantity per position and the two guards (cancelled/completed order, hold) are the SAME code the ship route runs, so what this answers and what that accepts cannot drift — a client subtracting the quantities itself eventually offers a shipment the server refuses, or one it should have refused. 'shippable' is false with a 'blocked_reason' when the order is held, cancelled, completed or has nothing open.
+     * What a shipment dialog needs before it can offer anything: the open quantity per position, and one boolean saying whether a shipment would be accepted at all. Reach for it to fill a picking screen or to decide whether a 'create shipment' button is enabled, instead of subtracting the quantities client-side. It changes nothing and books nothing — it is the question POST /orders/{id}/ship answers with an action. The read half of orders.ship. The open quantity per position and the two guards (cancelled/completed order, hold) are the SAME code the ship route runs, so what this answers and what that accepts cannot drift — a client subtracting the quantities itself eventually offers a shipment the server refuses, or one it should have refused. 'shippable' is false with a 'blocked_reason' when the order is held, cancelled, completed, still pending approval or has nothing open. A discount placed as a position of its own is money, not goods, and is not listed.
      *
      * @param {string} id - The order id (uuid). This segment reaches a uuid column: an order NUMBER is not accepted here — filter GET /orders by ?number= to resolve one.
      * @throws {RevenexxException}