---
title: Data model
sort: 2
---

# 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.

```drawio
{"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.