Data model

The entities you work with through the API, and how they relate. This is the conceptual model — the API Reference has the exact field shapes.

Everything belongs to exactly one tenant. Every entity below is owned by a single store (tenant) and is invisible to every other tenant. You never pass a tenant id — it’s derived server-side from your API key (see Authentication).

The entities

Entity	What it is
Tenant	A store. The isolation boundary that owns everything below.
Product	A catalog item — name, description, SEO, a `metadata` JSON field for category-specific attributes.
Variant	A specific purchasable version of a product (size, color, SKU, price).
Image	A product image (ordered).
Review	A customer review of a product, with votes.
Customer	A shopper account, scoped to this tenant. Passwordless (magic-link).
Cart	A shopper’s in-progress cart and its line items; can hold promo / gift-card.
Order	A completed purchase — line items, totals, status, fulfillment.
Refund	A full or partial refund recorded against an order.
Subscription	A recurring purchase, backed by Stripe.
Inventory	Stock for a variant. Externally you see a coarse status, not raw counts.
Content	Published articles, recipes, and announcements.
Lead	A captured email (e.g. newsletter signup).
Return (RMA)	A return request and its lifecycle.
Wholesale inquiry	A B2B / trade-account inquiry.

How they relate

Tenant ─┬─ Product ─┬─ Variant ─── Inventory
        │           ├─ Image
        │           └─ Review ─── (votes)
        │
        ├─ Customer ─┬─ Cart ─── (cart items → Variant)
        │            ├─ Order ─┬─ Order item ─── Variant
        │            │         └─ Refund
        │            └─ Subscription
        │
        ├─ Content
        ├─ Lead
        ├─ Return (RMA) ─── Order
        └─ Wholesale inquiry

A Product has many Variants, Images, and Reviews. The price and SKU live on the Variant; a single-variant product is the common case.
An Order has many Order items, each referencing the Variant purchased; an order may have one or more Refunds.
A Customer owns their Carts, Orders, and Subscriptions within this tenant. The same email at another tenant is a completely separate, unrelated customer.
Inventory tracks stock per Variant. Through the API you get a coarse status_key (in_stock / low_stock / out_of_stock) rather than exact counts.

Conventions

IDs are UUIDs.
Money is an integer in the smallest currency unit plus a currency code — e.g. { "amount": 4200, "currency": "usd" } is $42.00.
metadata (on products and some other entities) is a free-form JSON object for attributes Orchard doesn’t model natively — the extension point for category-specific fields without a schema change.
Timestamps are ISO-8601 UTC.

Where to go next

API Reference — exact field shapes for each entity.
Architecture — how these are served and isolated.
Webhooks — react to changes on orders and subscriptions.

Core concepts Architecture