Skip to content

Money and ledgers

Adocommerce Kit treats money as an integer amount plus an ISO 4217 currency. It never stores floating-point prices and never silently combines currencies.

Adocommerce Kit treats money as an integer amount plus an ISO 4217 currency. It never stores floating-point prices and never silently combines currencies.

Minor units, explicit currency

import { Money } from "@adocommercekit/core";

const shirt = Money.of(2_500n, "USD");
const twoShirts = shirt.multiply(2n);

shirt.add(Money.of(500n, "EUR")); // throws E_CURRENCY_MISMATCH

amount is a bigint in domain code and a decimal string in JSON. The storefront transformer shape is stable:

{
  "amount": "2500",
  "currency": "USD",
  "formatted": "$25.00"
}

Formatting is presentation only. Arithmetic always uses the integer amount.

Rows are the source of truth

Cart and order totals are cached columns for fast reads. Line and adjustment rows are the ledger that can reconstruct those caches.

subtotal = Σ(line.unitPrice × line.quantity)
grand    = subtotal + Σ(eligible, non-included adjustments)

Adjustments are signed money rows with a source, label, eligibility flag, inclusion flag, and position. Tax, shipping, promotions, and gift-card tender use the same primitive. They do not add unrelated total columns.

  • Included adjustment: represented in the displayed line price; excluded from the grand-total addition.
  • Eligible adjustment: participates in totals. Ineligible history may remain for auditability.
  • Negative adjustment: reduces the total and contributes to discountTotal.

Recalculation owns writes

Every cart mutation locks the cart, changes one input, and calls the processor pipeline. Price resolution runs before shipping and tax processors. The service replaces generated adjustments, recomputes the ledger, and writes cached totals in one transaction.

Never edit grandTotalAmount directly. Extend a processor or resolver so the ledger remains explainable.

Allocation without lost cents

When a total must be distributed across lines, Adocommerce Kit allocates integer minor units. The invariant is:

$$ \sum_i allocation_i = total $$

Remainders are distributed deterministically. This matters for inclusive tax, proportional discounts, partial refunds, and reconciliation: repeated calculation must produce the same rows.

Capture and refund ledgers

Captures and refunds retain their own rows with pending, succeeded, or failed state. A refund is associated with a succeeded capture; pending refunds reserve that capture’s remaining refundable capacity, while failed refunds do not consume it. Payment and intent refund totals reflect successful refunds, not merely a provider accepting a request.

External capture/refund claims have a separate started, completed, failed, or uncertain lifecycle. An uncertain network response is not proof of failure: reconcile provider state before retrying or recording another money movement. Migration 017_payment_reconciliation backfills legacy captures and unambiguous single-capture refund associations, preserving the backfilled ledger on rollback.

Gift tender and preorder deposits

Gift cards run at position 1100, after tax, and reduce the provider-payable amount through a negative gift_card adjustment. This is tender, not a product-price discount. A hold debits the card balance; capture has a zero balance delta because the debit already happened; release/refund credits balance. Refund credit cannot exceed captured gift tender minus prior credits. References protect those ledger operations against replay. See gift cards and store credit for one-time bearer-code handling and safe amount ranges.

Preorder deposits do not reduce the order’s ledger value. Placement captures deposits plus non-preorder amounts and retains the outstanding allocation balance for later capture. Deposit percentages use at most two decimal places and round up to minor units; fixed deposits are minor-unit integers capped at allocation value. Without a deposit setting, payment is full. See preorder lifecycle.

Return refunds preserve the accepted-line value and its adjustment allocation. ReturnRefunded contains amount (total), paymentAmount (provider-paid portion), and nonPaymentAmount (gift/store-credit portion), with amount = paymentAmount + nonPaymentAmount. refundId is nullable when no payment refund exists. Do not report a gift-only refund as a provider transfer, or credit gift tender twice from both return and payment-refund events.

Persistence conventions

@moneyColumn() maps a domain Money value to <prefix>_amount and <prefix>_currency columns. Host-owned model subclasses inherit this mapping. Database amounts are strings or integer-compatible values on write and normalize to bigint on read.

Use serializeMoney only at HTTP boundaries. Drivers and services should accept and return Money.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close