platform-types 1.10.779 → 1.10.781

package/dist/cart.d.ts

@@ -538,11 +538,11 @@ declare global {
         /**
          * Whether this promotion waives the cart's shipping.
          *
-         * ⚠️ `CartTotals.shipping` is structurally `0` today — nothing in the
-         * api computes a shipping cost yet, by design, because it is chosen at
-         * checkout. So the waiver currently changes no money, and this flag is the
-         * only place the GRANT survives to be read by whoever lands the shipping
-         * quote. Do not read its absence as "shipping was charged".
+         * ⚠️ `CartTotals.shipping` stays structurally `0`: the cart has no
+         * delivery method, so the shipping cost is chosen at checkout. Storefront
+         * checkout reads this flag there: a priced delivery method (`Method.fee`)
+         * books its freight line at `0` with `Order.freight.waivedBy: 'promotion'`.
+         * Do not read its absence as "shipping was charged".
          */
         shippingWaived?: boolean;
     }

package/dist/cjs/order.js

@@ -109,7 +109,8 @@ const positiveUnits = (value) => (typeof value === 'number' && value > 0 ? value
  * The ONE reader of the per-line fulfilment ledger (`OrderLine.fulfilledQuantity`).
  *
  * - A missing `fulfilledQuantity` counts as 0; lines with no or zero `quantity`
- *   are ignored on both sides of the ratio.
+ *   are ignored on both sides of the ratio, and so is a freight line
+ *   (`lineKind: 'freight'` with no `productId`), which is never shipped.
  * - `deliveredAt > 0` with no `shipments` is `complete` — a whole-order delivery
  *   that never went through the shipment ledger.
  * - A `disabled` or cancelled row is `none`, whatever timestamps it carries: a
@@ -120,6 +121,12 @@ const orderFulfilmentProgress = (order) => {
     let orderedUnits = 0;
     let fulfilledUnits = 0;
     for (const line of order.items ?? []) {
+        // A freight line is a charge, never handed over, so it would hold a
+        // fully shipped order at `partial` forever. The same test as
+        // `isFreightLine` (`stacks/helpers/discountCalculations.ts`), inlined
+        // because contracts import nothing from `stacks/`.
+        if (line?.lineKind === 'freight' && line.productId === undefined)
+            continue;
         const ordered = positiveUnits(line?.quantity);
         if (ordered === 0)
             continue;
@@ -279,6 +286,9 @@ exports.orderFulfilmentProgress = orderFulfilmentProgress;
  *   is refused after it, like every other refusal at commit.
  * - `ORDER_HAS_KIT_LINES` · 409 — `mode: 'edit'` on an order holding a kit line
  *   (`CartLine.kit`). Cancel or return the order instead. Nothing was written.
+ * - `ORDER_HAS_FREIGHT_LINE` · 409 — `mode: 'edit'` on an order holding a
+ *   freight line (`OrderLine.lineKind: 'freight'`). Cancel or return the order
+ *   instead. Nothing was written.
  * - `CART_PROMOTION_UNAVAILABLE` · 409 — the insert leg converting a STORED
  *   ticket whose promotion ended, was paused, deleted, has not started or is
  *   no longer cart-applicable; the `PromotionRefusal` rides `data.reason`. No
@@ -377,6 +387,15 @@ exports.orderFulfilmentProgress = orderFulfilmentProgress;
  * - `DELIVERY_METHOD_NOT_FOUND` · 400 — `deliveryMethod` is not in the store's
  *   delivery catalogue, including an absent/empty catalogue. `data: {}`;
  *   refused before reading the cart.
+ * - `DELIVERY_FEE_CURRENCY_UNSUPPORTED` · 409 — the chosen delivery method
+ *   carries a `fee` and the cart is not in the store's order currency
+ *   (`config.displayCurrency`, pesos when unset), the currency the fee is
+ *   stated in. `data: {}`; refused after the re-price.
+ * - `DELIVERY_FEE_CHANGED` · 409 — `expectedFreight` (absent reads as `0`)
+ *   differs from the freight the server computes for the chosen delivery
+ *   method. `data: DeliveryFeeChangedData` carries the server figure; show it
+ *   and confirm again. Refused after the re-price and the minimum purchase,
+ *   before any order id, coupon redemption or write.
  * - `ORDER_INVALID_CART` · 400 — the normalized cart has no finite numeric
  *   `totals.grandTotal`. `data: {}`; refused before repricing/allocation.
  * - `CART_CHANGED_SINCE_CONFIRM` · 409 — the body sent `expectedCartId` /
@@ -611,6 +630,8 @@ exports.ORDER_ERROR_CODES = [
     'CART_PROMOTION_UNAVAILABLE',
     // `mode: 'edit'` on an order holding a kit line; cancel or return it instead.
     'ORDER_HAS_KIT_LINES',
+    // `mode: 'edit'` on an order holding a freight line; cancel or return it instead.
+    'ORDER_HAS_FREIGHT_LINE',
     // Create-leg refusals about the sale's source, already answered on the wire.
     'ORDER_TARGET_REQUIRED',
     'ORDER_SOURCE_CONFLICT',
@@ -650,6 +671,10 @@ exports.ORDER_ERROR_CODES = [
     'CART_PRICES_CHANGED',
     'ORDER_ID_COLLISION',
     'DELIVERY_METHOD_NOT_FOUND',
+    // A priced delivery method (`Method.fee`): the freight moved since the shopper
+    // saw it, or the cart is not in the store's order currency.
+    'DELIVERY_FEE_CHANGED',
+    'DELIVERY_FEE_CURRENCY_UNSUPPORTED',
     'ORDER_BELOW_MINIMUM_PURCHASE',
     'ORDER_INVALID_CART',
     // The storefront's confirmed-cart pin (`StorefrontOrderCreateRequest.expectedCartId` / `expectedCartVersion`).

package/dist/cjs/store.js

@@ -139,6 +139,14 @@ exports.STORE_MODULE_ERROR_CODES = [
  *   entry naming no list of the store, with `data: { field, value }` where
  *   `field` is `<catalog>[<row>].availability.priceLists[<entry>]`.
  *
+ * - `DELIVERY_FEE_INVALID` — `POST /store` only: a delivery row's `fee` carries
+ *   an amount or a `freeAbove` that is not a finite number of at least `0` at
+ *   the order currency's ledger scale, with `data: { field }` where `field` is
+ *   `deliveryMethods[<row>].fee.<key>`; or a `paymentMethods` row carries a
+ *   `fee` at all, with `field` `paymentMethods[<row>].fee`. A `fee` that is not
+ *   an object, or that carries a key other than those two, is
+ *   `VALIDATION_FAILED`.
+ *
  * Request refusal, `409`:
  * - `WHOLESALE_LIST_REQUIRED` — an `ecommerce` save turns
  *   `config.wholesaleRequests` on while the store holds no
@@ -177,6 +185,7 @@ exports.STORE_PATCH_ERROR_CODES = [
     'DISPLAY_CURRENCY_NOT_INVOICEABLE',
     'PRODUCT_CURRENCY_NOT_INVOICEABLE',
     'PRICE_LIST_NOT_FOUND',
+    'DELIVERY_FEE_INVALID',
     'WHOLESALE_LIST_REQUIRED',
     'FORBIDDEN',
     'STORE_NOT_FOUND',

package/dist/order.d.ts

@@ -5,6 +5,32 @@ declare global {
         grandTotal: number;
         currency: string;
     }
+    /**
+     * `409 DELIVERY_FEE_CHANGED`'s `data`: the freight the server computed for
+     * the chosen delivery method, in the order currency, `0` when the method is
+     * unpriced or its fee is waived. Show it and confirm again with it as
+     * `StorefrontOrderCreateRequest.expectedFreight`.
+     */
+    interface DeliveryFeeChangedData {
+        freight: number;
+    }
+    /**
+     * Why a priced delivery method charged nothing: the goods total met the
+     * method's `fee.freeAbove`, or the cart's promotion waives shipping.
+     */
+    type OrderFreightWaiver = 'freeAbove' | 'promotion';
+    /**
+     * Which priced delivery method booked this order's freight line, and why it
+     * charged nothing when it did. METADATA only, never money: the charge is the
+     * `lineKind: 'freight'` line in `items`, which is what `total`, the payment
+     * attempt, the receivable and the voucher all read.
+     */
+    interface OrderFreight {
+        /** The `Store.deliveryMethods` row id whose `fee` was charged. */
+        methodId: number;
+        /** Present only when the line booked at 0 because the fee was waived. */
+        waivedBy?: OrderFreightWaiver;
+    }
     /**
      * A coupon as it was redeemed onto an order — the grant frozen at
      * consumption, plus the money it actually took.
@@ -250,6 +276,25 @@ declare global {
         productIds: string[];
     }
     interface OrderLine extends CartLine {
+        /**
+         * What kind of line this is. Absent means a goods (or service) line, which is
+         * every line written before freight existed: forward-only, never backfilled.
+         *
+         * `'freight'`: a server-owned, productless delivery charge. It carries no
+         * `productId` — a line naming one is goods whatever this says
+         * (`isFreightLine`); the order discount never applies to it, it moves no
+         * stock and writes no `SALE#` row, and it is never returnable or shippable.
+         * A return never credits it: the freight stays with the store.
+         *
+         * Fiscally the voucher reads the line's OWN stored `ivaType`, stamped from
+         * the store's `integrations.afip.freight` when the line is written, so a
+         * later config change never re-rates it. Only its Concepto is read live off
+         * that config, on a factura; a credit note restates its factura's.
+         *
+         * ⚠️ **Server-owned.** No order writer accepts it from a client;
+         * `stripServerOwnedLineFields` drops a caller-sent value.
+         */
+        lineKind?: 'freight';
         /** Base unit frozen from the product at sale; absent means unknown, never inferred on historical lines. */
         unit?: ProductUnit;
         /** Server-owned denomination of finite cost; absent means unknown. */
@@ -908,12 +953,17 @@ declare global {
          * deduction skips a service line rather than moving inventory a second
          * time.
          *
-         * `Order.discount` is a percentage and does NOT reach those lines — and
-         * must not, since the two units cannot be added and converting between
-         * them does not round-trip. The service order is the sole owner of its own
-         * total (its own `discount` is already spent in the lines above), so the
-         * figure invoiced is the figure the customer agreed to. The percentage
-         * still applies normally to any goods bought in the same visit.
+         * ⚠️ `Order.discount` DOES reach those lines. The ticket's own absolute
+         * `discount` is already spent in them, and `POST /orders` refuses an
+         * operator percentage on an order carrying this pointer; but a same-visit
+         * handover whose counter basket carries a discount stores
+         * `goodsDiscountPercent` (`_deliverOrder.ts`, `buildDeliveryOrderRow`): the
+         * basket's discount over the FULL gross, basket plus service lines. Every
+         * per-line site (`chargedLineTotal`, `buildInvoiceEconomics`) then cuts
+         * EVERY line by it, service lines included, so the order's total discount
+         * equals the basket's while being spread across the repair too. With no
+         * basket discount it is `0` and the service lines are billed exactly as
+         * minted. Only a freight line (`lineKind`) is ever exempt.
          */
         serviceOrderId?: string;
         /**
@@ -1165,6 +1215,13 @@ declare global {
          * nothing else can tell a second release from a first.
          */
         coupons?: OrderCoupon[];
+        /**
+         * Present only on a storefront order placed on a delivery method that
+         * carries a `fee` (`Method.fee`), and then always beside exactly one
+         * `lineKind: 'freight'` line. Server-owned: written by storefront checkout
+         * and by no other writer, and stripped from an operator body.
+         */
+        freight?: OrderFreight;
         orderPrinted?: boolean;
         tagPrinted?: boolean;
         /**
@@ -2413,6 +2470,17 @@ declare global {
          * transaction refuses too.
          */
         expectedCartVersion?: number;
+        /**
+         * The freight the storefront showed for `deliveryMethod`, in the order
+         * currency: the row's `fee.amount`, or `0` when `fee.freeAbove` is met by the
+         * cart's `grandTotal` or the cart's promotion waives shipping. Omit it (or
+         * send `0`) for an unpriced method. The server recomputes it and refuses a
+         * different figure `409 DELIVERY_FEE_CHANGED` with `data.freight`
+         * (`DeliveryFeeChangedData`), writing nothing. ⚠️ Omitting it on a method
+         * whose fee comes to more than `0` is refused the same way: the shopper is
+         * never charged a freight they were not shown.
+         */
+        expectedFreight?: number;
     }
     interface ZebraTag {
         orderId: string;
@@ -2542,7 +2610,8 @@ type OrderFulfilmentProgressInput = Pick<Partial<Order>, 'items' | 'shipments' |
  * The ONE reader of the per-line fulfilment ledger (`OrderLine.fulfilledQuantity`).
  *
  * - A missing `fulfilledQuantity` counts as 0; lines with no or zero `quantity`
- *   are ignored on both sides of the ratio.
+ *   are ignored on both sides of the ratio, and so is a freight line
+ *   (`lineKind: 'freight'` with no `productId`), which is never shipped.
  * - `deliveredAt > 0` with no `shipments` is `complete` — a whole-order delivery
  *   that never went through the shipment ledger.
  * - A `disabled` or cancelled row is `none`, whatever timestamps it carries: a
@@ -2692,6 +2761,9 @@ export declare const orderFulfilmentProgress: (order: OrderFulfilmentProgressInp
  *   is refused after it, like every other refusal at commit.
  * - `ORDER_HAS_KIT_LINES` · 409 — `mode: 'edit'` on an order holding a kit line
  *   (`CartLine.kit`). Cancel or return the order instead. Nothing was written.
+ * - `ORDER_HAS_FREIGHT_LINE` · 409 — `mode: 'edit'` on an order holding a
+ *   freight line (`OrderLine.lineKind: 'freight'`). Cancel or return the order
+ *   instead. Nothing was written.
  * - `CART_PROMOTION_UNAVAILABLE` · 409 — the insert leg converting a STORED
  *   ticket whose promotion ended, was paused, deleted, has not started or is
  *   no longer cart-applicable; the `PromotionRefusal` rides `data.reason`. No
@@ -2790,6 +2862,15 @@ export declare const orderFulfilmentProgress: (order: OrderFulfilmentProgressInp
  * - `DELIVERY_METHOD_NOT_FOUND` · 400 — `deliveryMethod` is not in the store's
  *   delivery catalogue, including an absent/empty catalogue. `data: {}`;
  *   refused before reading the cart.
+ * - `DELIVERY_FEE_CURRENCY_UNSUPPORTED` · 409 — the chosen delivery method
+ *   carries a `fee` and the cart is not in the store's order currency
+ *   (`config.displayCurrency`, pesos when unset), the currency the fee is
+ *   stated in. `data: {}`; refused after the re-price.
+ * - `DELIVERY_FEE_CHANGED` · 409 — `expectedFreight` (absent reads as `0`)
+ *   differs from the freight the server computes for the chosen delivery
+ *   method. `data: DeliveryFeeChangedData` carries the server figure; show it
+ *   and confirm again. Refused after the re-price and the minimum purchase,
+ *   before any order id, coupon redemption or write.
  * - `ORDER_INVALID_CART` · 400 — the normalized cart has no finite numeric
  *   `totals.grandTotal`. `data: {}`; refused before repricing/allocation.
  * - `CART_CHANGED_SINCE_CONFIRM` · 409 — the body sent `expectedCartId` /
@@ -2942,6 +3023,6 @@ export declare const orderFulfilmentProgress: (order: OrderFulfilmentProgressInp
  * `SUBSCRIPTION_READONLY`) sit on the order CREATE leg only: an edit is not a new
  * order, so `bareOrderPostHandler` routes past `requireMetered` entirely.
  */
-export declare const ORDER_ERROR_CODES: readonly ["ORDER_COST_DENOMINATION_UNKNOWN", "SERVICE_ORDER_DELIVERY_MANAGED", "ORDER_NOT_FOUND", "ORDER_LOCKED", "ORDER_NOT_READY", "ORDER_DELIVERED_ANOTHER_DAY", "ORDER_DELIVERY_STATE_UNCHANGED", "ORDER_ILLEGAL_TRANSITION", "ORDER_VERSION_CONFLICT", "CUSTOMER_NOT_FOUND", "CUSTOMER_MERGED", "ORDER_HAS_NO_CUSTOMER", "CUSTOMER_ANONYMIZED", "FX_CONVERSION_UNAVAILABLE", "ROLE_FORBIDDEN", "ORDER_CANCELLED", "PAYMENT_SETTLED_ON_ANOTHER_ORDER", "ORDER_HAS_SHIPMENTS", "ORDER_HAS_RETURNS", "SHIPMENT_QUANTITY_EXCEEDED", "SHIPMENT_LINE_MISMATCH", "SHIPMENT_NOT_FOUND", "SHIPMENT_LIMIT_REACHED", "SHIPMENT_TOO_LARGE", "ORDER_FULFILMENT_EXTERNAL", "SHIPMENT_FAILED", "ADMIN_REQUIRED", "IDEMPOTENCY_KEY_REQUIRED", "INVALID_IDEMPOTENCY_KEY", "IDEMPOTENCY_KEY_REUSE", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_LOCK_CONTENTION", "IDEMPOTENCY_KEY_FAILED", "IDEMPOTENT_RESPONSE_NOT_CACHED", "ORDER_CANCELLATION_NOT_PROTECTED", "ORDER_CANCELLATION_COMMITTED", "ORDER_CANCELLATION_LOCKED", "ORDER_CANCELLATION_TOO_LARGE", "ORDER_CANCELLATION_FAILED", "SALE_LEDGER_RETRACTION_REFUSED", "SALE_LEDGER_ROW_NOT_OWNED", "PRODUCT_NOT_FOUND", "PRODUCT_SALE_LIMIT_EXCEEDED", "PRODUCT_SALE_LIMIT_INVALID", "DEPOSIT_SOURCE_NOT_ALLOWED", "DEPOSIT_CURRENCY_MISMATCH", "DEPOSIT_EXCEEDS_TOTAL", "DEPOSIT_FREEZE_REQUIRES_INVOICE", "DEPOSIT_FREEZE_INVOICE_PENDING", "DEPOSIT_CHARACTERIZATION_CONFLICT", "DEPOSIT_FREEZE_INVOICE_NOT_QUALIFYING", "DEPOSIT_INVOICED_ORDER_MUST_FREEZE", "DEPOSIT_FROZEN_ORDER_MUST_FREEZE", "DEPOSIT_REFERENCE_IS_LINKED_PAYMENT", "DEPOSIT_DUPLICATE_REFERENCE", "TILL_TENDER_REQUIRES_DEPOSIT", "PAYMENT_REFERENCED_BY_DEPOSIT", "ORDER_HAS_UNREFUNDED_DEPOSIT", "ORDER_PRICE_FROZEN", "DEPOSIT_NOT_FOUND", "DEPOSIT_ALREADY_REFUNDED", "UNIT_QUANTITY_NOT_WHOLE", "UNIT_REVISION_STALE", "UNIT_QUANTITY_UNREPRESENTABLE", "KIT_RECIPE_CHANGED", "CART_PROMOTION_UNAVAILABLE", "ORDER_HAS_KIT_LINES", "ORDER_TARGET_REQUIRED", "ORDER_SOURCE_CONFLICT", "ORDER_CUSTOMER_REQUIRED", "BASKET_EMPTY", "BASKET_CHANGED_DURING_CHECKOUT", "CART_VERSION_CREATE_ONLY", "CART_VERSION_REQUIRES_CART_ID", "CART_REVISION_STALE", "CART_CUSTOMER_MISMATCH", "COUNTER_SALE_CREATE_ONLY", "SOLD_AT_CREATE_ONLY", "SOLD_AT_IN_FUTURE", "ORDER_TENDER_CREATE_ONLY", "CREDIT_OVERRIDE_CREATE_ONLY", "ON_ACCOUNT_CREATE_ONLY", "ON_ACCOUNT_WITH_TENDERS", "TENDERS_REQUIRE_COUNTER_SALE", "LINES_REQUIRE_COUNTER_SALE", "PRODUCT_COST_UNKNOWN", "PRICE_CHANGE_DISABLED", "LINE_DISCOUNT_EXCEEDS_MAX", "CUSTOMER_DISABLED", "SHIFT_NOT_AVAILABLE", "SOLD_AT_OUTSIDE_SHIFT", "ORDER_CURRENCY_NOT_SUBSCRIBED", "PAYMENT_METHODS_NOT_CONFIGURED", "PAYMENT_METHOD_NOT_FOUND", "PAYMENT_METHOD_UNAVAILABLE", "CART_PRICES_CHANGED", "ORDER_ID_COLLISION", "DELIVERY_METHOD_NOT_FOUND", "ORDER_BELOW_MINIMUM_PURCHASE", "ORDER_INVALID_CART", "CART_CHANGED_SINCE_CONFIRM", "EMAIL_VERIFICATION_REQUIRED", "ACCOUNT_DISABLED", "CUSTOMER_ACCESS_PENDING", "CUSTOMER_ACCESS_REJECTED", "CURRENCY_MISMATCH", "SHIFT_NOT_OPEN", "ORDER_DISCOUNT_AFTER_INVOICE", "ORDER_DISCOUNT_ON_SERVICE_ORDER", "ORDER_DISCOUNT_ON_MARKETPLACE_ORDER", "ORDER_INVOICE_METHOD_OUTSTANDING_FACTURA", "ORDER_SERVICE_PERIOD_AFTER_INVOICE", "ORDER_ATTEMPT_COMMITTED", "ORDER_ATTEMPT_ABANDONED", "ORDER_ATTEMPT_KEY_EXPIRED", "ORDER_ATTEMPT_KEY_SCOPE_MISMATCH", "ORDER_COMPLETION_ATTEMPT_COMMITTED", "ORDER_COMPLETION_ATTEMPT_ABANDONED"];
+export declare const ORDER_ERROR_CODES: readonly ["ORDER_COST_DENOMINATION_UNKNOWN", "SERVICE_ORDER_DELIVERY_MANAGED", "ORDER_NOT_FOUND", "ORDER_LOCKED", "ORDER_NOT_READY", "ORDER_DELIVERED_ANOTHER_DAY", "ORDER_DELIVERY_STATE_UNCHANGED", "ORDER_ILLEGAL_TRANSITION", "ORDER_VERSION_CONFLICT", "CUSTOMER_NOT_FOUND", "CUSTOMER_MERGED", "ORDER_HAS_NO_CUSTOMER", "CUSTOMER_ANONYMIZED", "FX_CONVERSION_UNAVAILABLE", "ROLE_FORBIDDEN", "ORDER_CANCELLED", "PAYMENT_SETTLED_ON_ANOTHER_ORDER", "ORDER_HAS_SHIPMENTS", "ORDER_HAS_RETURNS", "SHIPMENT_QUANTITY_EXCEEDED", "SHIPMENT_LINE_MISMATCH", "SHIPMENT_NOT_FOUND", "SHIPMENT_LIMIT_REACHED", "SHIPMENT_TOO_LARGE", "ORDER_FULFILMENT_EXTERNAL", "SHIPMENT_FAILED", "ADMIN_REQUIRED", "IDEMPOTENCY_KEY_REQUIRED", "INVALID_IDEMPOTENCY_KEY", "IDEMPOTENCY_KEY_REUSE", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_LOCK_CONTENTION", "IDEMPOTENCY_KEY_FAILED", "IDEMPOTENT_RESPONSE_NOT_CACHED", "ORDER_CANCELLATION_NOT_PROTECTED", "ORDER_CANCELLATION_COMMITTED", "ORDER_CANCELLATION_LOCKED", "ORDER_CANCELLATION_TOO_LARGE", "ORDER_CANCELLATION_FAILED", "SALE_LEDGER_RETRACTION_REFUSED", "SALE_LEDGER_ROW_NOT_OWNED", "PRODUCT_NOT_FOUND", "PRODUCT_SALE_LIMIT_EXCEEDED", "PRODUCT_SALE_LIMIT_INVALID", "DEPOSIT_SOURCE_NOT_ALLOWED", "DEPOSIT_CURRENCY_MISMATCH", "DEPOSIT_EXCEEDS_TOTAL", "DEPOSIT_FREEZE_REQUIRES_INVOICE", "DEPOSIT_FREEZE_INVOICE_PENDING", "DEPOSIT_CHARACTERIZATION_CONFLICT", "DEPOSIT_FREEZE_INVOICE_NOT_QUALIFYING", "DEPOSIT_INVOICED_ORDER_MUST_FREEZE", "DEPOSIT_FROZEN_ORDER_MUST_FREEZE", "DEPOSIT_REFERENCE_IS_LINKED_PAYMENT", "DEPOSIT_DUPLICATE_REFERENCE", "TILL_TENDER_REQUIRES_DEPOSIT", "PAYMENT_REFERENCED_BY_DEPOSIT", "ORDER_HAS_UNREFUNDED_DEPOSIT", "ORDER_PRICE_FROZEN", "DEPOSIT_NOT_FOUND", "DEPOSIT_ALREADY_REFUNDED", "UNIT_QUANTITY_NOT_WHOLE", "UNIT_REVISION_STALE", "UNIT_QUANTITY_UNREPRESENTABLE", "KIT_RECIPE_CHANGED", "CART_PROMOTION_UNAVAILABLE", "ORDER_HAS_KIT_LINES", "ORDER_HAS_FREIGHT_LINE", "ORDER_TARGET_REQUIRED", "ORDER_SOURCE_CONFLICT", "ORDER_CUSTOMER_REQUIRED", "BASKET_EMPTY", "BASKET_CHANGED_DURING_CHECKOUT", "CART_VERSION_CREATE_ONLY", "CART_VERSION_REQUIRES_CART_ID", "CART_REVISION_STALE", "CART_CUSTOMER_MISMATCH", "COUNTER_SALE_CREATE_ONLY", "SOLD_AT_CREATE_ONLY", "SOLD_AT_IN_FUTURE", "ORDER_TENDER_CREATE_ONLY", "CREDIT_OVERRIDE_CREATE_ONLY", "ON_ACCOUNT_CREATE_ONLY", "ON_ACCOUNT_WITH_TENDERS", "TENDERS_REQUIRE_COUNTER_SALE", "LINES_REQUIRE_COUNTER_SALE", "PRODUCT_COST_UNKNOWN", "PRICE_CHANGE_DISABLED", "LINE_DISCOUNT_EXCEEDS_MAX", "CUSTOMER_DISABLED", "SHIFT_NOT_AVAILABLE", "SOLD_AT_OUTSIDE_SHIFT", "ORDER_CURRENCY_NOT_SUBSCRIBED", "PAYMENT_METHODS_NOT_CONFIGURED", "PAYMENT_METHOD_NOT_FOUND", "PAYMENT_METHOD_UNAVAILABLE", "CART_PRICES_CHANGED", "ORDER_ID_COLLISION", "DELIVERY_METHOD_NOT_FOUND", "DELIVERY_FEE_CHANGED", "DELIVERY_FEE_CURRENCY_UNSUPPORTED", "ORDER_BELOW_MINIMUM_PURCHASE", "ORDER_INVALID_CART", "CART_CHANGED_SINCE_CONFIRM", "EMAIL_VERIFICATION_REQUIRED", "ACCOUNT_DISABLED", "CUSTOMER_ACCESS_PENDING", "CUSTOMER_ACCESS_REJECTED", "CURRENCY_MISMATCH", "SHIFT_NOT_OPEN", "ORDER_DISCOUNT_AFTER_INVOICE", "ORDER_DISCOUNT_ON_SERVICE_ORDER", "ORDER_DISCOUNT_ON_MARKETPLACE_ORDER", "ORDER_INVOICE_METHOD_OUTSTANDING_FACTURA", "ORDER_SERVICE_PERIOD_AFTER_INVOICE", "ORDER_ATTEMPT_COMMITTED", "ORDER_ATTEMPT_ABANDONED", "ORDER_ATTEMPT_KEY_EXPIRED", "ORDER_ATTEMPT_KEY_SCOPE_MISMATCH", "ORDER_COMPLETION_ATTEMPT_COMMITTED", "ORDER_COMPLETION_ATTEMPT_ABANDONED"];
 export type OrderErrorCode = (typeof ORDER_ERROR_CODES)[number];
 export {};

package/dist/order.js

@@ -103,7 +103,8 @@ const positiveUnits = (value) => (typeof value === 'number' && value > 0 ? value
  * The ONE reader of the per-line fulfilment ledger (`OrderLine.fulfilledQuantity`).
  *
  * - A missing `fulfilledQuantity` counts as 0; lines with no or zero `quantity`
- *   are ignored on both sides of the ratio.
+ *   are ignored on both sides of the ratio, and so is a freight line
+ *   (`lineKind: 'freight'` with no `productId`), which is never shipped.
  * - `deliveredAt > 0` with no `shipments` is `complete` — a whole-order delivery
  *   that never went through the shipment ledger.
  * - A `disabled` or cancelled row is `none`, whatever timestamps it carries: a
@@ -114,6 +115,12 @@ export const orderFulfilmentProgress = (order) => {
     let orderedUnits = 0;
     let fulfilledUnits = 0;
     for (const line of order.items ?? []) {
+        // A freight line is a charge, never handed over, so it would hold a
+        // fully shipped order at `partial` forever. The same test as
+        // `isFreightLine` (`stacks/helpers/discountCalculations.ts`), inlined
+        // because contracts import nothing from `stacks/`.
+        if (line?.lineKind === 'freight' && line.productId === undefined)
+            continue;
         const ordered = positiveUnits(line?.quantity);
         if (ordered === 0)
             continue;
@@ -272,6 +279,9 @@ export const orderFulfilmentProgress = (order) => {
  *   is refused after it, like every other refusal at commit.
  * - `ORDER_HAS_KIT_LINES` · 409 — `mode: 'edit'` on an order holding a kit line
  *   (`CartLine.kit`). Cancel or return the order instead. Nothing was written.
+ * - `ORDER_HAS_FREIGHT_LINE` · 409 — `mode: 'edit'` on an order holding a
+ *   freight line (`OrderLine.lineKind: 'freight'`). Cancel or return the order
+ *   instead. Nothing was written.
  * - `CART_PROMOTION_UNAVAILABLE` · 409 — the insert leg converting a STORED
  *   ticket whose promotion ended, was paused, deleted, has not started or is
  *   no longer cart-applicable; the `PromotionRefusal` rides `data.reason`. No
@@ -370,6 +380,15 @@ export const orderFulfilmentProgress = (order) => {
  * - `DELIVERY_METHOD_NOT_FOUND` · 400 — `deliveryMethod` is not in the store's
  *   delivery catalogue, including an absent/empty catalogue. `data: {}`;
  *   refused before reading the cart.
+ * - `DELIVERY_FEE_CURRENCY_UNSUPPORTED` · 409 — the chosen delivery method
+ *   carries a `fee` and the cart is not in the store's order currency
+ *   (`config.displayCurrency`, pesos when unset), the currency the fee is
+ *   stated in. `data: {}`; refused after the re-price.
+ * - `DELIVERY_FEE_CHANGED` · 409 — `expectedFreight` (absent reads as `0`)
+ *   differs from the freight the server computes for the chosen delivery
+ *   method. `data: DeliveryFeeChangedData` carries the server figure; show it
+ *   and confirm again. Refused after the re-price and the minimum purchase,
+ *   before any order id, coupon redemption or write.
  * - `ORDER_INVALID_CART` · 400 — the normalized cart has no finite numeric
  *   `totals.grandTotal`. `data: {}`; refused before repricing/allocation.
  * - `CART_CHANGED_SINCE_CONFIRM` · 409 — the body sent `expectedCartId` /
@@ -604,6 +623,8 @@ export const ORDER_ERROR_CODES = [
     'CART_PROMOTION_UNAVAILABLE',
     // `mode: 'edit'` on an order holding a kit line; cancel or return it instead.
     'ORDER_HAS_KIT_LINES',
+    // `mode: 'edit'` on an order holding a freight line; cancel or return it instead.
+    'ORDER_HAS_FREIGHT_LINE',
     // Create-leg refusals about the sale's source, already answered on the wire.
     'ORDER_TARGET_REQUIRED',
     'ORDER_SOURCE_CONFLICT',
@@ -643,6 +664,10 @@ export const ORDER_ERROR_CODES = [
     'CART_PRICES_CHANGED',
     'ORDER_ID_COLLISION',
     'DELIVERY_METHOD_NOT_FOUND',
+    // A priced delivery method (`Method.fee`): the freight moved since the shopper
+    // saw it, or the cart is not in the store's order currency.
+    'DELIVERY_FEE_CHANGED',
+    'DELIVERY_FEE_CURRENCY_UNSUPPORTED',
     'ORDER_BELOW_MINIMUM_PURCHASE',
     'ORDER_INVALID_CART',
     // The storefront's confirmed-cart pin (`StorefrontOrderCreateRequest.expectedCartId` / `expectedCartVersion`).

package/dist/store.d.ts

@@ -1599,6 +1599,29 @@ declare global {
         /** ISO date; stops applying on or after. Omitted => open-ended. */
         expiresAt?: string;
     }
+    /**
+     * An AFIP Iva Id — one of `IVA_TYPES` (`services/fiscalCatalogs.ts`): 3 (0 %),
+     * 9 (2,5 %), 8 (5 %), 4 (10,5 %), 5 (21 %), 6 (27 %). `number`, like every
+     * `ivaType` in this contract, so a line's stored rate and a configured one
+     * compare without a cast; the catalog, not this type, is the authority.
+     * ⚠️ Not every write path validates against it: `PATCH /store` does
+     * (`afipPatchSchema`), but `POST /store` and `POST /tenants` take `afip`
+     * unvalidated, so a reader falls back on an out-of-catalog value
+     * (`resolveFreightFiscal`) rather than trusting the row.
+     */
+    type IvaTypeId = number;
+    /**
+     * How the store's freight line (`OrderLine.lineKind: 'freight'`) is declared
+     * to ARCA. Configuration the store's accountant decides, not a fact the code
+     * can derive: whether delivery is a separate service or an accessory of the
+     * sale, and at which rate, depends on how the store sells.
+     */
+    interface AfipFreightFiscal {
+        /** The alícuota stamped on the freight line, and so declared in `Iva[]`. */
+        ivaType: IvaTypeId;
+        /** Whether the freight line counts as goods or as a service for `Concepto`. */
+        concepto: 'goods' | 'services';
+    }
     interface Afip {
         production: boolean;
         address?: string;
@@ -1669,6 +1692,14 @@ declare global {
         fceEnabled?: boolean;
         wscdcEnabled?: boolean;
         fceReceivedCheckpoint?: number;
+        /**
+         * The freight line's IVA rate and Concepto. Absent means the platform
+         * default, `ivaType` 5 (21 %) and `concepto` `'goods'`
+         * (`DEFAULT_FREIGHT_FISCAL`); read it through `resolveFreightFiscal`, never
+         * directly. ADMIN-tier on `PATCH /store` (`PRIVILEGED_AFIP_FIELDS`); `null`
+         * clears it back to the default.
+         */
+        freight?: AfipFreightFiscal;
     }
     /**
      * Write shape for the `afip` key of `PATCH /store`'s body. The wire accepts an
@@ -1683,6 +1714,7 @@ declare global {
         iibbTransparency?: Afip['iibbTransparency'] | null;
         iibbJurisdictions?: IibbJurisdictionConfig[] | null;
         actividades?: number[] | null;
+        freight?: AfipFreightFiscal | null;
     }
     /**
      * Write shape for the `config` key of `PATCH /store`'s body. Two things the
@@ -1812,6 +1844,45 @@ declare global {
          * is sent back without `availability`; sending a valid rule replaces it.
          */
         availability?: StorefrontDesignVisibility;
+        /**
+         * The price of this DELIVERY method, charged on a storefront order as one
+         * server-owned freight line (`OrderLine.lineKind: 'freight'`). ABSENT means
+         * unpriced: the order books no freight, exactly as before the key existed.
+         * Any delivery row may carry one, the pickup row included. Written by
+         * `POST /store`; carried by every read of a `deliveryMethods` row, the
+         * storefront `GET /store` and the CUSTOMER STORE frame included, because it
+         * is the price the shopper pays.
+         *
+         * DELIVERY rows only. The row type is shared, but `POST /store` refuses a
+         * `fee` on a `paymentMethods` row (`400 DELIVERY_FEE_INVALID`, `data.field`
+         * `paymentMethods[<row>].fee`), and every read drops one a legacy payment
+         * row still holds — nothing charges it there.
+         */
+        fee?: MethodFee;
+    }
+    /**
+     * A delivery method's price, in the store's order currency
+     * (`config.displayCurrency`, pesos when unset) and IVA-inclusive like every
+     * line price.
+     *
+     * `POST /store` refuses `400 DELIVERY_FEE_INVALID` (with `data.field`) unless
+     * both numbers are finite, at least `0`, and representable at that currency's
+     * ledger scale (2 decimals for every seeded currency). On read, a stored fee
+     * is dropped, never coerced, only when it breaks the SHAPE (a key other than
+     * these two, or an amount that is not a finite number of at least `0`); a
+     * stored amount off the ledger scale is still read, and checkout rounds it to
+     * the scale.
+     */
+    interface MethodFee {
+        /** What the method charges. `0` books a freight line at `0`. */
+        amount: number;
+        /**
+         * The goods total from which the method is free: when the cart's
+         * `grandTotal` (after every discount, freight never included) is at least
+         * this, the freight line books at `0` with `Order.freight.waivedBy:
+         * 'freeAbove'`. Absent means never free by amount.
+         */
+        freeAbove?: number;
     }
     interface FiscalCondition {
         CbteTipo: {
@@ -2412,6 +2483,14 @@ export type StoreModuleRefusalBody = {
  *   entry naming no list of the store, with `data: { field, value }` where
  *   `field` is `<catalog>[<row>].availability.priceLists[<entry>]`.
  *
+ * - `DELIVERY_FEE_INVALID` — `POST /store` only: a delivery row's `fee` carries
+ *   an amount or a `freeAbove` that is not a finite number of at least `0` at
+ *   the order currency's ledger scale, with `data: { field }` where `field` is
+ *   `deliveryMethods[<row>].fee.<key>`; or a `paymentMethods` row carries a
+ *   `fee` at all, with `field` `paymentMethods[<row>].fee`. A `fee` that is not
+ *   an object, or that carries a key other than those two, is
+ *   `VALIDATION_FAILED`.
+ *
  * Request refusal, `409`:
  * - `WHOLESALE_LIST_REQUIRED` — an `ecommerce` save turns
  *   `config.wholesaleRequests` on while the store holds no
@@ -2432,5 +2511,5 @@ export type StoreModuleRefusalBody = {
  * checks, the display-currency lock, the storefront fence) are not listed
  * either. Cross-cutting refusals: check `GATING_ERROR_CODES` as well.
  */
-export declare const STORE_PATCH_ERROR_CODES: readonly ["STORE_CONFIG_FORBIDDEN", "STORE_ECOMMERCE_FORBIDDEN", "STORE_FISCAL_FIELD_FORBIDDEN", "STORE_JURISDICTION_FORBIDDEN", "AFIP_RELACION_FLAG_FORBIDDEN", "FX_TABLE_FORBIDDEN", "FX_AUTO_UPDATE_FORBIDDEN", "FIELD_NOT_WRITABLE_HERE", "AFIP_POINT_OF_SALE_NOT_CLEARABLE", "CURRENCY_CATALOG_ID_UNKNOWN", "ARS_RATE_MUST_BE_ONE", "CURRENCY_RATE_ABOVE_CEILING", "FX_CATALOG_ID_UNKNOWN", "FX_SOURCE_ID_UNKNOWN", "DISPLAY_CURRENCY_NOT_INVOICEABLE", "PRODUCT_CURRENCY_NOT_INVOICEABLE", "PRICE_LIST_NOT_FOUND", "WHOLESALE_LIST_REQUIRED", "FORBIDDEN", "STORE_NOT_FOUND"];
+export declare const STORE_PATCH_ERROR_CODES: readonly ["STORE_CONFIG_FORBIDDEN", "STORE_ECOMMERCE_FORBIDDEN", "STORE_FISCAL_FIELD_FORBIDDEN", "STORE_JURISDICTION_FORBIDDEN", "AFIP_RELACION_FLAG_FORBIDDEN", "FX_TABLE_FORBIDDEN", "FX_AUTO_UPDATE_FORBIDDEN", "FIELD_NOT_WRITABLE_HERE", "AFIP_POINT_OF_SALE_NOT_CLEARABLE", "CURRENCY_CATALOG_ID_UNKNOWN", "ARS_RATE_MUST_BE_ONE", "CURRENCY_RATE_ABOVE_CEILING", "FX_CATALOG_ID_UNKNOWN", "FX_SOURCE_ID_UNKNOWN", "DISPLAY_CURRENCY_NOT_INVOICEABLE", "PRODUCT_CURRENCY_NOT_INVOICEABLE", "PRICE_LIST_NOT_FOUND", "DELIVERY_FEE_INVALID", "WHOLESALE_LIST_REQUIRED", "FORBIDDEN", "STORE_NOT_FOUND"];
 export type StorePatchErrorCode = (typeof STORE_PATCH_ERROR_CODES)[number];

package/dist/store.js

@@ -134,6 +134,14 @@ export const STORE_MODULE_ERROR_CODES = [
  *   entry naming no list of the store, with `data: { field, value }` where
  *   `field` is `<catalog>[<row>].availability.priceLists[<entry>]`.
  *
+ * - `DELIVERY_FEE_INVALID` — `POST /store` only: a delivery row's `fee` carries
+ *   an amount or a `freeAbove` that is not a finite number of at least `0` at
+ *   the order currency's ledger scale, with `data: { field }` where `field` is
+ *   `deliveryMethods[<row>].fee.<key>`; or a `paymentMethods` row carries a
+ *   `fee` at all, with `field` `paymentMethods[<row>].fee`. A `fee` that is not
+ *   an object, or that carries a key other than those two, is
+ *   `VALIDATION_FAILED`.
+ *
  * Request refusal, `409`:
  * - `WHOLESALE_LIST_REQUIRED` — an `ecommerce` save turns
  *   `config.wholesaleRequests` on while the store holds no
@@ -172,6 +180,7 @@ export const STORE_PATCH_ERROR_CODES = [
     'DISPLAY_CURRENCY_NOT_INVOICEABLE',
     'PRODUCT_CURRENCY_NOT_INVOICEABLE',
     'PRICE_LIST_NOT_FOUND',
+    'DELIVERY_FEE_INVALID',
     'WHOLESALE_LIST_REQUIRED',
     'FORBIDDEN',
     'STORE_NOT_FOUND',

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "platform-types",
-	"version": "1.10.779",
+	"version": "1.10.781",
 	"description": "Shared wire and entity contracts for the platform.",
 	"type": "module",
 	"main": "dist/index.js",