@tallyui/pos 3.2.1 → 3.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tallyui/pos",
-  "version": "3.2.1",
+  "version": "3.3.0",
   "type": "module",
   "description": "Shared POS business logic for Tally UI — tax, orders, payments, discounts, receipts",
   "main": "./dist/index.js",
@@ -27,20 +27,20 @@
     "directory": "packages/pos"
   },
   "peerDependencies": {
-    "@tallyui/core": "^3.2.1",
+    "@tallyui/core": "^3.3.0",
     "react": ">=18",
     "rxdb": "~17.5.0",
     "rxjs": ">=7"
   },
   "devDependencies": {
-    "@tallyui/core": "3.2.1",
+    "@tallyui/core": "3.3.0",
     "@types/react": ">=18",
     "react": "^19.2.4",
     "rxdb": "17.5.0",
     "rxjs": "7.8.2",
-    "@tallyui/connector-medusa": "3.2.1",
-    "@tallyui/connector-woocommerce": "3.2.1",
-    "@tallyui/database": "3.2.1"
+    "@tallyui/connector-medusa": "3.3.0",
+    "@tallyui/connector-woocommerce": "3.3.0",
+    "@tallyui/database": "3.3.0"
   },
   "scripts": {
     "build": "tsup",

package/src/index.ts

@@ -68,7 +68,7 @@ export { createRegisterOutbox, useRegisterOutbox } from './outbox';
 export type { RegisterOutboxOptions, RegisterOutbox, UseRegisterOutboxOptions, UseRegisterOutboxResult } from './outbox';
 export { createBackendNotFound } from './outbox/backend-not-found';
 export type { BackendNotFound } from './outbox/backend-not-found';
-export type { HttpTransportOptions, OrderOutboxOptions, OrderOutbox, TransportOutcome, CommandTransport, OutboxState, UseOrderOutboxOptions, UseOrderOutboxResult } from './outbox';
+export type { HttpTransportOptions, OrderOutboxOptions, OrderOutbox, TransportOutcome, CommandTransport, OrderTransportContext, OutboxState, UseOrderOutboxOptions, UseOrderOutboxResult } from './outbox';
 export { tenderReducer, initTenderState, initialTenderState, appliedMinor, changeMinor, quickTenderedAmounts, evenSplitShareMinor, activePlan, planLegs, MAX_TENDER_MINOR } from './tender';
 export type { PaymentTransport, TenderView, TenderLineId, TenderPlan, SplitTab, TenderState, TenderKey, TenderAction, PlanLeg } from './tender';
 

package/src/order/order-builder.ts

@@ -4,6 +4,7 @@ import type { TaxContext } from '../tax/types';
 import { taxMicros, roundMicrosToMinor, roundedTaxByRate } from '../tax/exact';
 import { taxLogger } from '../tax/tax-provider';
 import { allocateOrderDiscount } from './allocate-order-discount';
+import { woocommerceLine, woocommerceTotals } from './woocommerce-tax';
 import type {
   Order,
   LineItem,
@@ -96,6 +97,14 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
   const { taxContext } = options;
   const currency = options.currency.toUpperCase();
   const orderId = options.id ?? uid();
+  const woo = taxContext.rounding?.granularity === 'woocommerce' && taxContext.getTaxRates ? taxContext.rounding : undefined;
+  const wooLine = (amount: number, taxClass: string | undefined, inclusive: boolean, untaxed = false, shipping = false) =>
+    woocommerceLine(amount, untaxed ? [] : taxContext.getTaxRates!(taxClass, { shipping }), inclusive, currency, woo!.roundAtSubtotal, taxContext.pricesIncludeTax);
+  const displayAmount = (line: LineItem, amount: number) => {
+    if (!woo || line.taxInclusive === taxContext.pricesIncludeTax) return toDisplayMode(line, amount, taxContext.pricesIncludeTax);
+    const item = wooLine(amount, line.taxClass, line.taxInclusive, line.taxStatus === 'none');
+    return taxContext.pricesIncludeTax ? item.totalMinor : item.netMinor;
+  };
 
   let lineItems: LineItem[] = [];
   let fees: FeeLine[] = [];
@@ -124,6 +133,8 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
     const lineDiscountMinor = Math.min(grossMinor, recalcedDiscounts.reduce((sum, d) => sum + d.amountMinor, 0));
     const discountMinor = lineDiscountMinor + orderDiscountMinor;
     const netMinor = grossMinor - discountMinor;
+    if (woo) return { ...line, discounts: recalcedDiscounts, discountMinor, orderDiscountMinor,
+      ...wooLine(netMinor, line.taxClass, line.taxInclusive, line.taxStatus === 'none') };
     const combinedRate = line.taxLines.reduce((sum, tax) => sum + tax.ratePpm, 0);
     // Tax in the line's own mode, from its own unit price × quantity: never re-tax a rounded base.
     const inclusiveTax = line.taxInclusive ? taxMicros(netMinor, combinedRate, true) : 0n;
@@ -166,7 +177,7 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
     // parity). A fixed discount is computed on what remains, as before. Every discount is then capped at what
     // remains, which decreases as each is applied, and the total is allocated to the lines, which are then
     // taxed on what is left.
-    const lineAmounts = lineItems.map((li) => li.netMinor);
+    const lineAmounts = lineItems.map((li) => woo ? li.unitPriceMinor * li.quantity - li.discountMinor : li.netMinor);
     const base = lineAmounts.reduce((sum, amount) => sum + Math.max(0, amount), 0);
     let remaining = base;
     const recalcedOrderDiscounts = orderDiscounts.map((d) => {
@@ -177,11 +188,12 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
     const shares = allocateOrderDiscount(lineAmounts, recalcedOrderDiscounts.reduce((sum, d) => sum + d.amountMinor, 0));
     const lines = lineItems.map((li, index) => recalculateLine(li, shares[index]));
 
-    const { subtotalMinor } = sumLines(lines, taxContext.rounding);
+    const wooTotals = woo ? woocommerceTotals(lines, fees, shipping, currency, woo.roundAtSubtotal, taxContext.pricesIncludeTax) : undefined;
+    const { subtotalMinor } = wooTotals ?? sumLines(lines, taxContext.rounding);
     const charges = [...fees, ...shipping];
     const taxedLines = [...lines, ...charges.map((charge) => ({ ...charge, taxInclusive: taxContext.pricesIncludeTax,
       taxMicros: charge.taxLines.reduce((sum, tax) => sum + BigInt(tax.taxMicros), 0n).toString() }))];
-    const { taxMinor, totalMinor } = sumLines(taxedLines, taxContext.rounding);
+    const { taxMinor, totalMinor } = wooTotals ?? sumLines(taxedLines, taxContext.rounding);
     if (taxContext.rounding?.granularity === 'per_rate_group_items' && taxedLines.some((li) => li.taxInclusive) && !perRateGroupWarned.has(taxContext)) {
       perRateGroupWarned.add(taxContext);
       taxLogger.warn('per_rate_group_items with inclusive lines: using per_order figures until the display has a rounding row (#287, #310)');
@@ -198,11 +210,11 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
       // with no rows: its capped "discounts" are the negative gross cancelled, not money off.
       const returned = li.unitPriceMinor < 0;
       const discounts = returned ? [] : li.discounts.map((d) => ({
-        discountId: d.id, ...(d.label !== undefined ? { label: d.label } : {}), amountMinor: toDisplayMode(li, d.amountMinor, taxInclusive),
+        discountId: d.id, ...(d.label !== undefined ? { label: d.label } : {}), amountMinor: displayAmount(li, d.amountMinor),
       }));
-      const shareMinor = toDisplayMode(li, li.orderDiscountMinor, taxInclusive);
-      const remainingMinor = toDisplayMode(li, li.netMinor, taxInclusive);
-      const amountMinor = li.taxInclusive === taxInclusive && !returned ? li.unitPriceMinor * li.quantity
+      const shareMinor = displayAmount(li, li.orderDiscountMinor);
+      const remainingMinor = woo ? taxInclusive ? li.totalMinor! : li.netMinor : toDisplayMode(li, li.netMinor, taxInclusive);
+      const amountMinor = !woo && li.taxInclusive === taxInclusive && !returned ? li.unitPriceMinor * li.quantity
         : discounts.reduce((sum, d) => sum + d.amountMinor, remainingMinor + shareMinor);
       return { line: { lineId: li.id, amountMinor, discounts }, shareMinor, remainingMinor, returned };
     });
@@ -210,9 +222,20 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
     const orderDiscountDisplay = figures.reduce((sum, f) => sum + f.shareMinor, 0);
     const displayDiscount = displayLines.reduce(
       (sum, line) => line.discounts.reduce((lineSum, d) => lineSum + d.amountMinor, sum), orderDiscountDisplay);
-    const displaySubtotal = (taxInclusive ? totalMinor : totalMinor - taxMinor) + displayDiscount
-      - charges.reduce((sum, charge) => sum + charge.amountMinor, 0);
-    const residue = displaySubtotal - displayLines.reduce((sum, line) => sum + line.amountMinor, 0);
+    const chargeRows = (items: ChargeLine[]) => items.map(({ id, name, amountMinor, netMinor, totalMinor }) =>
+      ({ id, name, amountMinor: woo ? taxInclusive ? totalMinor! : netMinor : amountMinor }));
+    const displayFees = chargeRows(fees), displayShipping = chargeRows(shipping);
+    let displaySubtotal = (taxInclusive ? totalMinor : totalMinor - taxMinor) + displayDiscount
+      - [...displayFees, ...displayShipping].reduce((sum, charge) => sum + charge.amountMinor, 0);
+    let residue = displaySubtotal - displayLines.reduce((sum, line) => sum + line.amountMinor, 0);
+    if (woo) {
+      // ADR-076: the last shipping row, else fee, else product takes either sign of residue.
+      const charge = displayShipping.at(-1) ?? displayFees.at(-1);
+      const last = charge ?? displayLines.at(-1);
+      if (last) last.amountMinor += residue;
+      if (charge) displaySubtotal -= residue;
+      residue = displaySubtotal - displayLines.reduce((sum, line) => sum + line.amountMinor, 0);
+    }
     const converted = lines.flatMap((li, index) => li.taxInclusive === taxInclusive ? [] : [index]);
     const conversions = converted.reduce((count, index) => count + [lines[index].netMinor, lines[index].orderDiscountMinor,
       ...lines[index].discounts.map((d) => d.amountMinor)].filter((x) => x !== 0).length, 0);
@@ -235,7 +258,7 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
     if (displayDiscount < 0) throw new Error(`Display discount ${displayDiscount} is negative (ADR-063)`);
     for (const { line, shareMinor, returned } of figures) {
       if (returned && line.discounts.length > 0) throw new Error(`Return line ${line.lineId} shows discount rows (ADR-063)`);
-      if (returned) continue;
+      if (returned || woo) continue;
       const rows = line.discounts.reduce((sum, d) => sum + d.amountMinor, 0);
       if (shareMinor < 0 || line.discounts.some((d) => d.amountMinor < 0) || line.amountMinor < rows + shareMinor) {
         throw new Error(`Display line ${line.lineId} shows ${line.amountMinor}, less than its rows ${rows} and share ${shareMinor} (ADR-063)`);
@@ -244,8 +267,8 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
     const display = {
       taxInclusive, subtotalMinor: displaySubtotal, discountMinor: displayDiscount, taxMinor, totalMinor,
       lines: displayLines, orderDiscountMinor: orderDiscountDisplay,
-      ...(fees.length ? { fees: fees.map(({ id, name, amountMinor }) => ({ id, name, amountMinor })) } : {}),
-      ...(shipping.length ? { shipping: shipping.map(({ id, name, amountMinor }) => ({ id, name, amountMinor })) } : {}),
+      ...(fees.length ? { fees: displayFees } : {}),
+      ...(shipping.length ? { shipping: displayShipping } : {}),
     };
     const paidMinor = payments.reduce((sum, p) => sum + p.amountMinor, 0);
     const balanceDueMinor = Math.max(0, totalMinor - paidMinor);
@@ -281,11 +304,16 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
     subject.next(buildOrder());
   }
 
-  function recalculateCharge(id: string, input: ChargeInput): ChargeLine {
+  function recalculateCharge(id: string, input: ChargeInput, shipping = false): ChargeLine {
     if (!Number.isInteger(input.amountMinor)) throw new RangeError('Amount must be integer minor units');
     if (input.amountMinor < 0) throw new RangeError('Amount must be >= 0');
     if (!input.name.trim()) throw new RangeError('Name must not be empty');
     const taxStatus = input.taxStatus ?? 'taxable';
+    if (woo) {
+      const line = wooLine(input.amountMinor, input.taxClass, taxContext.pricesIncludeTax, taxStatus === 'none', shipping);
+      return { id, name: input.name, amountMinor: input.amountMinor, taxClass: input.taxClass, taxStatus,
+        ...line };
+    }
     const code = taxContext.getTaxRateCode?.(input.taxClass);
     const line = recalculateLine({
       id, productId: id, name: input.name, sku: '', unitPriceMinor: input.amountMinor, quantity: 1,
@@ -295,7 +323,7 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
       taxInclusive: taxContext.pricesIncludeTax,
     });
     return { id, name: input.name, amountMinor: input.amountMinor, taxClass: input.taxClass, taxStatus,
-      taxLines: line.taxLines, netMinor: line.netMinor, taxMicros: Number(line.taxMicros) };
+      taxLines: line.taxLines, netMinor: line.netMinor, taxMicros: line.taxMicros };
   }
 
   function addLine(input: AddLineInput): string {
@@ -305,13 +333,15 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
     if (!Number.isInteger(unitPrice.amount)) throw new RangeError('Price must be integer minor units');
     if (!Number.isInteger(quantity) || quantity < 1) throw new RangeError('Quantity must be an integer >= 1');
     // A rate from the tax class carries the backend's name for it when one is mapped (#287, #288).
-    const code = input.taxRates ? undefined : taxContext.getTaxRateCode?.(input.taxClass);
-    const taxRates = input.taxStatus === 'none' ? [{ ...(code !== undefined ? { code } : {}), ratePpm: 0 }]
+    const code = woo || input.taxRates ? undefined : taxContext.getTaxRateCode?.(input.taxClass);
+    const taxRates = woo ? wooLine(unitPrice.amount * quantity, input.taxClass, unitPrice.taxInclusive ?? taxContext.pricesIncludeTax, input.taxStatus === 'none').taxLines
+      : input.taxStatus === 'none' ? [{ ...(code !== undefined ? { code } : {}), ratePpm: 0 }]
       : input.taxRates ?? [{ ...(code !== undefined ? { code } : {}), ratePpm: taxContext.getTaxRatePpm(input.taxClass) }];
     const taxInclusive = unitPrice.taxInclusive ?? taxContext.pricesIncludeTax;
 
     const existing = lineItems.find(
       (li) => !input.custom && !li.custom && li.productId === productId && li.variantId === variantId && li.taxInclusive === taxInclusive
+        && (!woo || li.taxClass === input.taxClass && (li.taxStatus === 'none') === (input.taxStatus === 'none'))
         && li.unitPriceMinor === unitPrice.amount && li.taxLines.length === taxRates.length
         && li.taxLines.every((tax, index) => tax.code === taxRates[index].code && tax.ratePpm === taxRates[index].ratePpm),
     );
@@ -327,6 +357,7 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
     const lineId = uid();
     const line: LineItem = {
       id: lineId,
+      ...((input.custom ? input.taxClass !== undefined : woo) ? { taxClass: input.taxClass } : {}),
       productId,
       ...(input.custom ? { custom: true as const } : {}),
       ...(input.taxStatus === 'none' ? { taxStatus: 'none' as const } : {}),
@@ -377,14 +408,14 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
       fees = fees.filter((entry) => entry.id !== id); emit();
     },
     addShipping(input) {
-      const charge = { ...recalculateCharge(uid(), input), methodId: input.methodId };
+      const charge = { ...recalculateCharge(uid(), input, true), methodId: input.methodId };
       shipping = [...shipping, charge]; emit(); return charge.id;
     },
     updateShipping(id, patch) {
       const charge = shipping.find((entry) => entry.id === id);
       if (!charge) throw new Error(`Unknown shipping ${id}`);
       const input = { ...charge, ...patch };
-      const updated = { ...recalculateCharge(id, input), methodId: input.methodId };
+      const updated = { ...recalculateCharge(id, input, true), methodId: input.methodId };
       shipping = shipping.map((entry) => entry.id === id ? updated : entry); emit();
     },
     removeShipping(id) {
@@ -410,6 +441,7 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
         unitPrice,
         quantity: opts?.quantity,
         taxClass: traits.getTaxClass?.(doc, opts?.variantId),
+        ...(traits.getTaxStatus?.(doc, opts?.variantId) === 'none' ? { taxStatus: 'none' as const } : {}),
       });
     },
 

package/src/order/order-drafts.ts

@@ -67,6 +67,7 @@ export function restoreOrderDraft(saved: Order, options: { currency: string; tax
       productId: line.productId,
       custom: line.custom,
       taxStatus: line.taxStatus,
+      ...(taxContext.rounding?.granularity === 'woocommerce' ? { taxClass: line.taxClass } : {}),
       variantId: line.variantId,
       name: line.name,
       sku: line.sku,

package/src/order/types.ts

@@ -49,12 +49,16 @@ export interface DisplayTotals {
 /** One line in the display mode (ADR-063): before any discount, with its own discounts as sub-rows. */
 export interface DisplayLine {
   lineId: string;
-  amountMinor: number;        // quantity × unit price in the display mode; the last converted line also carries the rounding residue
+  amountMinor: number;        // quantity × unit price, or WooCommerce's line figure; a residue recipient may adjust it
   discounts: { discountId: string; label?: string; amountMinor: number }[]; // this line's own discounts, each converted on its own
 }
 
 export interface LineItem {
   id: string;
+  taxClass?: string;
+  /** WooCommerce's stored net at rounding precision, in integer micro-minor units, and its rounded gross. */
+  netMicros?: string;
+  totalMinor?: number;
   custom?: true;
   taxStatus?: 'none';
   productId: string;
@@ -68,7 +72,7 @@ export interface LineItem {
   discounts: AppliedDiscount[];
   discountMinor: number;      // line discounts + orderDiscountMinor, in the line's own mode
   orderDiscountMinor: number; // this line's allocated share of the order discounts (ADR-062)
-  netMinor: number;           // unitPriceMinor × quantity − discountMinor; the taxed base
+  netMinor: number;           // unitPriceMinor × quantity − discountMinor; under WooCommerce, the rounded exclusive net
   taxMicros: string;          // Σ taxLines[].taxMicros, decimal string of a bigint
   taxInclusive: boolean;      // the price's own tax mode; the order's when the price has none
   /** Set only when the price's tax mode differs from the order's; named price mode → order mode. */
@@ -77,13 +81,15 @@ export interface LineItem {
 
 export interface ChargeLine {
   id: string;
+  netMicros?: string;
+  totalMinor?: number;
   name: string;
   amountMinor: number; // integer >= 0, in the order's tax mode (ADR-075)
   taxClass?: string;
   taxStatus: 'taxable' | 'none';
   taxLines: LineItem['taxLines'];
   netMinor: number;
-  taxMicros: number;
+  taxMicros: string;
 }
 export interface FeeLine extends ChargeLine {}
 export interface ShippingLine extends ChargeLine { methodId?: string }
@@ -91,6 +97,8 @@ export interface ChargeInput { name: string; amountMinor: number; taxClass?: str
 
 export interface LineTaxLine {
   code?: string;
+  rateId?: number;
+  compound?: boolean;
   ratePpm: number;
   taxMicros: string;          // exact, decimal string of a bigint
 }

package/src/order/woocommerce-tax.ts

@@ -0,0 +1,68 @@
+import { minorUnitDigits, woocommerceTax } from '@tallyui/core';
+import type { WooRate } from '../tax/types';
+import type { RateTaxLine } from '../tax/exact';
+import type { ChargeLine, LineItem, LineTaxLine } from './types';
+
+/** ADR-076: all WooCommerce float arithmetic stays here; only integer money leaves this module. */
+export function woocommerceLine(amountMinor: number, rates: readonly WooRate[], inclusive: boolean, currency: string,
+  roundAtSubtotal: boolean, pricesIncludeTax = inclusive) {
+  const dp = minorUnitDigits(currency), factor = 10 ** dp;
+  const precision = woocommerceTax.getRoundingPrecision(dp);
+  const input = { amount: amountMinor / factor, rates: rates.map((rate) => ({ ...rate, order: rate.priority })),
+    amountIncludesTax: inclusive, dp, perRatePrecision: precision };
+  let result = woocommerceTax.calculateTaxes(input);
+  const net = woocommerceTax.roundHalfUp(input.amount - (inclusive ? result.total : 0), precision);
+  // WC_Order_Item_Product::calculate_taxes re-derives from the stored net (#2333 B).
+  if (inclusive && rates.length) result = woocommerceTax.calculateTaxes({ ...input, amount: net, amountIncludesTax: false });
+  const taxLines: LineTaxLine[] = result.taxes.map((tax) => {
+    const rate = rates.find((rate) => rate.id === tax.id)!;
+    return { code: rate.code, rateId: rate.id, compound: rate.compound, ratePpm: Math.round(Number(rate.rate) * 10000),
+      taxMicros: String(Math.round(tax.total * factor * 1e6)) };
+  });
+  const tax = result.taxes.reduce((sum, rate) => sum + (roundAtSubtotal ? rate.total
+    : woocommerceTax.roundTaxTotal(rate.total, dp, pricesIncludeTax)), 0);
+  return { netMinor: Math.round(woocommerceTax.roundHalfUp(net, dp) * factor), netMicros: String(Math.round(net * factor * 1e6)),
+    totalMinor: Math.round(woocommerceTax.roundHalfUp(net + tax, dp) * factor), taxLines,
+    taxMicros: taxLines.reduce((sum, rate) => sum + BigInt(rate.taxMicros), 0n).toString() };
+}
+
+/** calculateOrderTotals: products round conditionally, fees stay raw, shipping always rounds per item. */
+export function woocommerceTotals(lines: readonly LineItem[], fees: readonly ChargeLine[], shipping: readonly ChargeLine[],
+  currency: string, roundAtSubtotal: boolean, inclusive: boolean) {
+  const dp = minorUnitDigits(currency), factor = 10 ** dp;
+  const net = (line: LineItem | ChargeLine) => Number(line.netMicros) / (factor * 1e6);
+  const productNet = lines.reduce((sum, line) => sum + (roundAtSubtotal ? net(line) : woocommerceTax.roundHalfUp(net(line), dp)), 0);
+  const amount = productNet + fees.reduce((sum, line) => sum + net(line), 0)
+    + shipping.reduce((sum, line) => sum + woocommerceTax.roundHalfUp(net(line), dp), 0);
+  const taxes = (items: readonly (LineItem | ChargeLine)[]) => woocommerceTax.roundHalfUp(items.reduce((sum, line) =>
+    line.taxLines.reduce((sum, tax) => sum + (roundAtSubtotal ? Number(tax.taxMicros) / (factor * 1e6)
+      : woocommerceTax.roundTaxTotal(Number(tax.taxMicros) / (factor * 1e6), dp, inclusive)), sum), 0), woocommerceTax.getRoundingPrecision(dp));
+  const tax = woocommerceTax.roundHalfUp(taxes([...lines, ...fees]) + taxes(shipping), 6);
+  return { subtotalMinor: Math.round(woocommerceTax.roundHalfUp(productNet, dp) * factor),
+    taxMinor: Math.round((roundAtSubtotal ? woocommerceTax.roundHalfUp(tax, dp) : woocommerceTax.roundTaxTotal(tax, dp, inclusive)) * factor),
+    totalMinor: Math.round(woocommerceTax.roundHalfUp(woocommerceTax.roundHalfUp(amount + tax, 6), dp) * factor) };
+}
+
+/** Order-math's rate buckets, including zero rows; the last row takes the bounded order tax residue. */
+export function woocommerceTaxByRate(lines: readonly { netMinor: number; taxInclusive: boolean; taxLines: readonly LineTaxLine[] }[],
+  roundAtSubtotal: boolean, taxLabels?: Record<number, string>, orderTaxMinor?: number): RateTaxLine[] {
+  const groups = new Map<string, RateTaxLine & { amount: number; inclusive: boolean }>();
+  for (const line of lines) for (const tax of line.taxLines) {
+    const key = JSON.stringify([tax.rateId, tax.code, tax.ratePpm]);
+    const row = groups.get(key) ?? { code: tax.code, ratePpm: tax.ratePpm, label: taxLabels?.[tax.ratePpm] ?? `Tax ${tax.ratePpm / 10000}%`,
+      netMinor: 0, amountMinor: 0, amount: 0, inclusive: line.taxInclusive };
+    const amount = Number(tax.taxMicros) / 1e6;
+    row.amount += roundAtSubtotal ? amount : woocommerceTax.roundTaxTotal(amount, 0, line.taxInclusive);
+    row.netMinor += line.netMinor;
+    groups.set(key, row);
+  }
+  const rows = [...groups.values()].map(({ amount, inclusive, ...row }) => ({ ...row,
+    amountMinor: woocommerceTax.roundTaxTotal(woocommerceTax.roundHalfUp(amount, 6), 0, inclusive) }));
+  if (orderTaxMinor !== undefined && rows.length) {
+    const residue = orderTaxMinor - rows.reduce((sum, row) => sum + row.amountMinor, 0);
+    const bound = Math.floor(rows.length / 2) + 1;
+    if (Math.abs(residue) > bound) throw new Error(`woocommerce tax by rate: residue ${residue} exceeds its bound ${bound} (ADR-076)`);
+    rows[rows.length - 1].amountMinor += residue;
+  }
+  return rows;
+}

package/src/outbox/index.ts

@@ -6,6 +6,6 @@ export { createRegisterOutbox } from './register-outbox';
 export type { RegisterOutboxOptions, RegisterOutbox } from './register-outbox';
 export { useRegisterOutbox } from './use-register-outbox';
 export type { UseRegisterOutboxOptions, UseRegisterOutboxResult } from './use-register-outbox';
-export type { TransportOutcome, CommandTransport, OutboxState } from './types';
+export type { TransportOutcome, CommandTransport, OrderTransportContext, OutboxState } from './types';
 export { useOrderOutbox, outboxLogger } from './use-order-outbox';
 export type { UseOrderOutboxOptions, UseOrderOutboxResult } from './use-order-outbox';

package/src/outbox/order-outbox.ts

@@ -268,6 +268,7 @@ export function createOrderOutbox(options: OrderOutboxOptions): OrderOutbox {
       const firstSend = orders.some((order) => order.sentVersion === undefined);
       const serverMax = (firstSend && validMax(await Promise.resolve().then(() => options.getMaxOrderCreateVersion?.())
         .catch((cause) => { outboxLogger.warn('Failed to read capabilities', { cause }); }))) || 3;
+      const localOrders = new Map<string, PosOrder>();
       const batch = await Promise.all(orders.map(async (order) => {
         const frozen = freezeSentForm(order);
         const attempt = (attempts.get(order.commandId) ?? 0) + 1;
@@ -276,9 +277,9 @@ export function createOrderOutbox(options: OrderOutboxOptions): OrderOutbox {
         try {
           envelope = toOrderCreateEnvelope(frozen, deviceId, attempt, { maxVersion: order.sentVersion ?? serverMax });
         } catch (cause) {
-          // A discounted order the server can take only at 1 goes as before (at most 3): the refusal rejects it.
+          // Content that cannot downgrade goes at its required version: the server's refusal rejects it.
           if (!(cause instanceof UnsupportedOrderVersionError)) throw cause;
-          envelope = toOrderCreateEnvelope(frozen, deviceId, attempt, { maxVersion: 3 });
+          envelope = toOrderCreateEnvelope(frozen, deviceId, attempt, { maxVersion: cause.needed === 5 ? 5 : 3 });
         }
         // Bounds apply when frozen: persist older tills' sent forms before sending (Front desk, 2026-09-29). A first
         // send's version is stored, awaited, before the batch request leaves, so a crash in between keeps it.
@@ -286,9 +287,10 @@ export function createOrderOutbox(options: OrderOutboxOptions): OrderOutbox {
           await (await collection.findOne(order.id).exec())?.incrementalModify((data) =>
             ({ ...freezeSentForm(data), sentVersion: data.sentVersion ?? envelope.version }));
         }
+        localOrders.set(envelope.id, frozen);
         return envelope;
       }));
-      let outcome = await transport.send(batch);
+      let outcome = await transport.send(batch, { local: { orders: localOrders } });
       // A 404 answers the whole batch (the route is missing); any other answer resets the count. Offline changes nothing.
       backendNotFound.record(outcome, now());
       if (outcome.kind !== 'retry' || outcome.reason !== 'network') {

package/src/outbox/types.ts

@@ -1,4 +1,11 @@
 import type { AnyCommandEnvelope, CommandEnvelope, CommandResult, OrderCreatePayload } from '@tallyui/core';
+import type { PosOrder } from '../pos-order';
+
+/** Local-only context for a transport (ADR-076 amendment 1): never serialised, never part of a payload. */
+export interface OrderTransportContext {
+  /** The stored (frozen) order of each envelope in the batch, keyed by the envelope's `id` (its commandId). */
+  local: { orders: ReadonlyMap<string, PosOrder> };
+}
 
 export type TransportOutcome =
   | { kind: 'results'; results: CommandResult[] }
@@ -9,7 +16,7 @@ export type TransportOutcome =
   | { kind: 'retry'; reason: string; retryAfterMs?: number };
 
 export interface CommandTransport<E extends AnyCommandEnvelope = CommandEnvelope<OrderCreatePayload>> {
-  send(batch: E[]): Promise<TransportOutcome>;
+  send(batch: E[], context?: OrderTransportContext): Promise<TransportOutcome>;
 }
 
 export interface OutboxState {

package/src/pos-order/command.ts

@@ -55,9 +55,10 @@ function netDiscountMinor(line: PosOrderLine, pricesIncludeTax: boolean): number
 
 /**
  * The order.create version an order's stored content makes: 3 with ADR-065's figures, else 2 when its lines are
- * discounted (ADR-062), else 1. The builder's, and pos_orders v5's migration's for a row with no `sentVersion`.
+ * discounted (ADR-062), else 1; fees, shipping or custom lines need 5. Also used by pos_orders v5's migration.
  */
-export function contentVersion(order: Pick<PosOrder, 'display' | 'taxByRate' | 'lines'>): 1 | 2 | 3 {
+export function contentVersion(order: Pick<PosOrder, 'display' | 'taxByRate' | 'lines' | 'fees' | 'shipping'>): 1 | 2 | 3 | 5 {
+  if (order.fees?.length || order.shipping?.length || order.lines.some((line) => line.custom)) return 5;
   return order.display && order.taxByRate ? 3 : order.lines.reduce((sum, line) => sum + line.discountMinor, 0) > 0 ? 2 : 1;
 }
 
@@ -73,11 +74,12 @@ export function toOrderCreateEnvelope(order: PosOrder, deviceId: string, attempt
   const grossMinor = order.lines.reduce((sum, line) => sum + line.discountMinor, 0);
   const content = contentVersion(order);
   const cap = options?.maxVersion === undefined ? order.sentVersion : Math.min(options.maxVersion, order.sentVersion ?? options.maxVersion);
+  if (content === 5 && cap !== undefined && cap < 5) throw new UnsupportedOrderVersionError(5, cap);
   if (grossMinor > 0 && cap !== undefined && cap < 2) throw new UnsupportedOrderVersionError(2, cap);
   // Version 4 only when the cap allows it (the server advertises 4, and no sentVersion holds the order lower).
   const version = (content === 3 && cap !== undefined && cap >= 4 ? 4
     : Math.min(content, cap ?? content)) as OrderCreateEnvelope['version'];
-  const lineDiscounts = order.lines.map((line) => version === 4 ? netDiscountMinor(line, order.pricesIncludeTax) : line.discountMinor);
+  const lineDiscounts = order.lines.map((line) => version >= 4 ? netDiscountMinor(line, order.pricesIncludeTax) : line.discountMinor);
   // The order's discount is the sum of its lines', on one basis, so the payload's two always agree.
   const discountMinor = lineDiscounts.reduce((sum, discount) => sum + discount, 0);
   const email = order.customer?.email;
@@ -85,16 +87,26 @@ export function toOrderCreateEnvelope(order: PosOrder, deviceId: string, attempt
   // These are the pre-#222 customerId and sessionId checks, kept byte-exact so stored orders resend older tills' bytes; don't replace with sendable.
   const customerId = typeof id === 'string' && id.length > 0 && id.length <= 64 ? id : undefined;
   const sessionId = order.sessionId ?? order.lateSessionId;
+  const { fees: _fees, shipping: _shipping, ...storedDisplay } = { ...order.display! };
   return {
     id: order.commandId, type: 'order.create', version, createdAt: order.createdAt, deviceId, attempt,
     payload: {
       clientOrderId: order.id, createdAt: order.createdAt, currency: order.currency, pricesIncludeTax: order.pricesIncludeTax,
       lines: order.lines.map((line, i) => ({
-        clientLineId: line.id, variantId: line.variantId ?? line.productId, title: line.name,
+        clientLineId: line.id, ...(line.custom ? { custom: { ...line.custom } } : { variantId: line.variantId ?? line.productId }), title: line.name,
         quantity: line.quantity, unitPriceMinor: line.unitPriceMinor,
         ...(line.taxInclusive !== undefined ? { taxInclusive: line.taxInclusive } : {}),
         ...(lineDiscounts[i] > 0 ? { discountMinor: lineDiscounts[i] } : {}),
       })),
+      ...(version === 5 && order.fees?.length ? { fees: order.fees.map((fee) => ({
+        clientFeeId: fee.id, name: fee.name, amountMinor: fee.amountMinor, taxStatus: fee.taxStatus,
+        ...(fee.taxClass !== undefined ? { taxClass: fee.taxClass } : {}), taxMinor: roundMicrosToMinor(BigInt(fee.taxMicros)),
+      })) } : {}),
+      ...(version === 5 && order.shipping?.length ? { shipping: order.shipping.map((charge) => ({
+        clientShippingId: charge.id, name: charge.name, ...(charge.methodId !== undefined ? { methodId: charge.methodId } : {}),
+        amountMinor: charge.amountMinor, taxStatus: charge.taxStatus,
+        ...(charge.taxClass !== undefined ? { taxClass: charge.taxClass } : {}), taxMinor: roundMicrosToMinor(BigInt(charge.taxMicros)),
+      })) } : {}),
       payments: order.payments.map((payment) => ({
         clientPaymentId: payment.id, method: payment.method, amountMinor: payment.amountMinor,
         ...(payment.tenderedMinor !== undefined ? { tenderedMinor: payment.tenderedMinor } : {}),
@@ -105,9 +117,12 @@ export function toOrderCreateEnvelope(order: PosOrder, deviceId: string, attempt
       ...(discountMinor > 0 ? { discountMinor } : {}),
       taxMinor: order.taxMinor, totalMinor: order.totalMinor,
       ...(version >= 3 ? {
-        display: { ...order.display!, lines: order.display!.lines.map(({ lineId, amountMinor, discounts }) => ({
+        display: { ...storedDisplay, lines: order.display!.lines.map(({ lineId, amountMinor, discounts }) => ({
           clientLineId: lineId, amountMinor, discounts,
-        })) },
+        })),
+        ...(version === 5 && order.display!.fees ? { fees: order.display!.fees.map(({ id, amountMinor }) => ({ clientFeeId: id, amountMinor })) } : {}),
+        ...(version === 5 && order.display!.shipping ? { shipping: order.display!.shipping.map(({ id, amountMinor }) => ({ clientShippingId: id, amountMinor })) } : {}),
+        },
         taxByRate: order.taxByRate!.map(({ ratePpm, code, netMinor, amountMinor, grossMinor }) => ({
           ratePpm, ...(code !== undefined ? { code } : {}), netMinor, taxMinor: amountMinor, grossMinor,
         })),

package/src/pos-order/finalize.ts

@@ -29,7 +29,11 @@ export function withSentForm(order: Order, posOrder: PosOrder): SentOrder {
   if (customer && posOrder.customer?.id === undefined) delete customer.id;
   return { ...order, customer,
     lineItems: order.lineItems.map((line, i) => ({ ...line, name: posOrder.lines[i].name })),
+    ...(order.fees ? { fees: order.fees.map((fee, i) => ({ ...fee, name: posOrder.fees![i].name })) } : {}),
+    ...(order.shipping ? { shipping: order.shipping.map((charge, i) => ({ ...charge, name: posOrder.shipping![i].name })) } : {}),
     display: posOrder.display ? { ...order.display,
+      ...(order.display.fees ? { fees: order.display.fees.map((row, i) => ({ ...row, name: posOrder.display!.fees![i].name })) } : {}),
+      ...(order.display.shipping ? { shipping: order.display.shipping.map((row, i) => ({ ...row, name: posOrder.display!.shipping![i].name })) } : {}),
       lines: order.display.lines.map((line, i) => ({ ...line,
         discounts: line.discounts.map((discount, j) => ({ ...discount, label: posOrder.display!.lines[i].discounts[j].label })),
       })),
@@ -43,7 +47,15 @@ export function freezeSentForm(order: PosOrder): PosOrder {
   const lines = order.lines.map((line) => {
     const name = cutText(line.name, PAYLOAD_STRING_MAX);
     changed ||= name !== line.name;
-    return { ...line, name };
+    const custom = line.custom && { ...line.custom, name: cutText(line.custom.name, PAYLOAD_STRING_MAX) };
+    changed ||= custom !== undefined && custom.name !== line.custom!.name;
+    return { ...line, name, ...(custom ? { custom } : {}) };
+  });
+  const charges = { fees: order.fees, shipping: order.shipping };
+  for (const field of ['fees', 'shipping'] as const) if (charges[field]) charges[field] = charges[field]!.map((charge) => {
+    const name = cutText(charge.name, PAYLOAD_STRING_MAX);
+    changed ||= name !== charge.name;
+    return { ...charge, name };
   });
   const display = order.display && { ...order.display, lines: order.display.lines.map((line) => ({ ...line,
     discounts: line.discounts.map((discount) => {
@@ -53,6 +65,11 @@ export function freezeSentForm(order: PosOrder): PosOrder {
       return { ...discount, label };
     }),
   })) };
+  for (const field of ['fees', 'shipping'] as const) if (display?.[field]) display[field] = display[field]!.map((row) => {
+    const name = cutText(row.name, PAYLOAD_STRING_MAX);
+    changed ||= name !== row.name;
+    return { ...row, name };
+  });
   const payments = order.payments.map((payment) => {
     if (payment.reference === undefined) return payment;
     const reference = cutText(payment.reference, PAYLOAD_STRING_MAX);
@@ -67,7 +84,8 @@ export function freezeSentForm(order: PosOrder): PosOrder {
       if (!localWarnings.some((warning) => warning.code === 'customer_omitted' && warning.field === field)) localWarnings.push({ code: 'customer_omitted', field });
     }
   }
-  return changed ? { ...order, lines, payments, customer, ...(display ? { display } : {}), ...(localWarnings.length ? { localWarnings } : {}) } : order;
+  return changed ? { ...order, lines, payments, customer, ...(charges.fees ? { fees: charges.fees } : {}),
+    ...(charges.shipping ? { shipping: charges.shipping } : {}), ...(display ? { display } : {}), ...(localWarnings.length ? { localWarnings } : {}) } : order;
 }
 
 /**
@@ -94,8 +112,9 @@ export function referenceReason(value: string | undefined): 'long' | 'nul' | nul
  * customer email or id the shape check would refuse is left out, so `toOrderCreateEnvelope` sends it unchanged.
  */
 export function finalizeOrder(order: Order, options: FinalizeOptions = {}): PosOrder {
-  if (order.fees?.length || order.shipping?.length || order.lineItems.some((line) => line.custom)) {
-    throw new Error('finalize: fees, shipping and custom lines need order.create version 5, which this release does not send yet');
+  if ((order.fees?.length || order.shipping?.length || order.lineItems.some((line) => line.custom))
+    && (options.capabilities?.orderCreate ?? 1) < 5) {
+    throw new Error("finalize: fees, shipping and custom lines need the store to accept order.create version 5; update the store's TallyUI plugin");
   }
   if (!order.lineItems.length) throw new Error('finalize: no lines');
   // Defence in depth: the builder already clamps every discount to >= 0, so this should never fire.
@@ -139,14 +158,20 @@ export function finalizeOrder(order: Order, options: FinalizeOptions = {}): PosO
   }
   const newId = options.newId ?? uuidv7;
   const id = newId();
-  const lines = order.lineItems.map((line) => ({
+  const lines: PosOrder['lines'] = order.lineItems.map((line) => ({
     id: newId(), productId: line.productId,
     ...(line.variantId !== undefined ? { variantId: line.variantId } : {}),
+    ...(line.custom ? { custom: { name: line.name, ...(line.sku ? { sku: line.sku } : {}),
+      ...(line.taxClass !== undefined ? { taxClass: line.taxClass } : {}), taxStatus: line.taxStatus ?? 'taxable' } } : {}),
+    ...(line.taxStatus !== undefined ? { taxStatus: line.taxStatus } : {}),
     name: line.name, sku: line.sku, quantity: line.quantity, unitPriceMinor: line.unitPriceMinor,
     discountMinor: line.discountMinor, netMinor: line.netMinor,
+    ...(order.taxRounding?.granularity === 'woocommerce' ? { netMicros: line.netMicros } : {}),
     taxLines: line.taxLines.map((tax) => ({ ...tax })),
     ...(line.priceTaxModeConverted ? { taxInclusive: line.taxInclusive } : {}),
   }));
+  const fees = order.fees?.map((charge) => ({ ...charge, id: newId(), taxLines: charge.taxLines.map((tax) => ({ ...tax })) }));
+  const shipping = order.shipping?.map((charge) => ({ ...charge, id: newId(), taxLines: charge.taxLines.map((tax) => ({ ...tax })) }));
   const payments: PosOrderPayment[] = order.payments.map((payment) => ({
     id: newId(), method: payment.method as PosOrderPayment['method'], amountMinor: payment.amountMinor,
     ...(payment.reference !== undefined ? { reference: payment.reference } : {}),
@@ -182,6 +207,8 @@ export function finalizeOrder(order: Order, options: FinalizeOptions = {}): PosO
       throw new Error('finalize: display lines do not match the order lines');
     }
     display = { currency: order.currency, exponent: minorUnitDigits(order.currency), ...order.display,
+      ...(fees?.length ? { fees: order.display.fees!.map((row, i) => ({ ...row, id: fees[i].id })) } : {}),
+      ...(shipping?.length ? { shipping: order.display.shipping!.map((row, i) => ({ ...row, id: shipping[i].id })) } : {}),
       lines: order.display.lines.map((line, i) => ({
         lineId: lines[i].id, amountMinor: line.amountMinor,
         discounts: line.discounts.map(({ discountId, label, amountMinor }) => ({
@@ -189,7 +216,9 @@ export function finalizeOrder(order: Order, options: FinalizeOptions = {}): PosO
         })),
       })),
     };
-    taxByRate = taxLinesByRate(order.lineItems, order.taxMinor, undefined, order.taxRounding).map(({ ratePpm, code, netMinor, amountMinor }) => ({
+    const taxedLines = [...order.lineItems, ...[...(order.fees ?? []), ...(order.shipping ?? [])]
+      .map((charge) => ({ ...charge, taxInclusive: order.pricesIncludeTax }))];
+    taxByRate = taxLinesByRate(taxedLines, order.taxMinor, undefined, order.taxRounding).map(({ ratePpm, code, netMinor, amountMinor }) => ({
       ratePpm, ...(code !== undefined ? { code } : {}), netMinor, amountMinor, grossMinor: netMinor + amountMinor,
     }));
     if (display.totalMinor !== order.totalMinor || display.taxMinor !== order.taxMinor
@@ -204,11 +233,13 @@ export function finalizeOrder(order: Order, options: FinalizeOptions = {}): PosO
   // absent on the snapshot is the default the figures used; `custom` computes as the default but records itself.
   const rounding = order.taxRounding ?? DEFAULT_TAX_ROUNDING;
   const taxRounding: TaxRounding = rounding.granularity === 'custom' ? { granularity: 'custom' }
+    : rounding.granularity === 'woocommerce' ? { granularity: 'woocommerce', roundAtSubtotal: rounding.roundAtSubtotal }
     : { granularity: rounding.granularity, mode: rounding.mode };
   const now = (options.now ?? new Date()).toISOString();
   return freezeSentForm({
     id, saleId: order.id, createdAt: now, updatedAt: now, commandId: newId(), syncStatus: 'pending',
     currency: order.currency, pricesIncludeTax: order.pricesIncludeTax, lines, payments,
+    ...(fees?.length ? { fees } : {}), ...(shipping?.length ? { shipping } : {}),
     subtotalMinor: order.subtotalMinor, discountMinor: order.discountMinor,
     taxMinor: order.taxMinor, totalMinor: order.totalMinor, taxRounding,
     ...(display && taxByRate ? { display, taxByRate } : {}),