Entity Relationship Model
This page describes the core data model that powers the Quark Commerce API. Understanding these relationships is essential for building a storefront.
Core Product Model
Dual Category System
Quark Commerce has two types of categories serving different purposes:
| Type | CatalogType | Purpose | Storefront Visible |
|---|---|---|---|
| Master | Master | Internal product management taxonomy | No (admin only) |
| Sales | Sales | Storefront browsing categories | Yes |
Sales Category Subtypes
SalesCategoryType | Purpose |
|---|---|
Taxonomy | Hierarchical browsing (Shop All → Tops, Bottoms, etc.) |
Promotional | Cross-cutting collections (New Arrivals, Sale) |
Key point: A product has one master category (for internal management) and multiple sales categories (for storefront display). The storefront should use Sales categories for navigation.
Product → Variant → Configuration
Every product has one or more variants. Each variant represents a specific combination of attributes (e.g., "Red / Size M"):
- Product — the parent entity (name, description, category, brand)
- ProductVariant — a purchasable SKU (has its own price, stock, images, slug)
- VariantConfiguration — links a variant to its attribute values (Color=Red, Size=M)
- DefaultProductVariant — the variant shown by default on the product detail page
Pricing Model
Prices are set per variant, per currency:
Price— current selling priceCompareAtPrice— original/strikethrough price (for showing discounts)CostPrice— internal cost (not exposed to storefront)
The API automatically returns the price matching the X-Currency-Code header.
Inventory Model
Stock is tracked per variant, per warehouse:
The storefront availability endpoint aggregates stock across all warehouses assigned to the current store.
Order Model
Shopping Basket
Baskets can be anonymous (identified by a client-generated string ID) or associated with a user. See Shopping Basket for the full flow.