Data model

The relationships between the top-level resources. Cardinality is shown next to the line; 1..n means one customer can have many orders, never the inverse.

{"meta":"placeholder — this fenced block is rendered by the drawio escape hatch on the live server. The local app exposes an in-app editor for it."}

A textual version of the same shape, for screen readers and grep-ability:

  • A tenant owns everything below.
  • A customer belongs to one tenant. Has 1..n orders, 1..n carts, 0..n payment methods, 1..n addresses.
  • A product belongs to one tenant. Has 1..n variants. Variants carry the price and the inventory.
  • A cart belongs to one tenant, optionally to one customer. Has 1..n line items, each pointing at a variant.
  • A checkout session belongs to one cart. Is the immutable, signed handoff to the hosted payment page.
  • An order is the immutable promotion of a cart at the moment of payment. It carries a snapshot of the line items, not a reference, so price changes do not retroactively alter historical orders.
  • A refund belongs to one order. Up to N refunds can sum to ≤ the order total.

Invariants

  • Currency is set on the cart at creation and cannot change. A cart cannot mix currencies.
  • A product's currency does not constrain the cart's currency — pricing tables handle the cross-product per-currency price.
  • Order line items snapshot product name, SKU, and unit price at the moment the order is created. Editing the product after the fact does not retroactively change the order.
  • Customer email is unique per tenant, case-folded.