Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 33 ยท Commerce Modules and the Data Model

The Commerce Modules

Tour the Medusa 2 commerce modules: Product, Pricing, Inventory, Cart, Order, Customer, Payment, Fulfillment, Tax, Promotion, Region and how they compose.

Medusa's commerce features are not one big service. They are a set of commerce modules, each responsible for one slice of the business: what you sell, what it costs, where it is stocked, what a shopper is buying, what they bought. Learning what each module owns, and what it deliberately does not own, is the key to understanding the data model and to knowing where your own code should plug in.

This lesson walks through the modules, shows how they refer to each other with IDs instead of shared tables, and ends with two runnable stand-ins: a small catalog, cart and order model in plain objects, and a mini "query" that stitches module data together. Module names, fields and APIs here describe Medusa 2 in general terms; check the documentation of your installed version for exact field lists.

The modules at a glance

Module Owns Typical records
Product The catalog products, variants, options, collections, categories, tags
Pricing Prices and rules price sets, prices, price lists, price rules
Inventory Stock quantities inventory items, inventory levels, reservations
Stock Location Where stock lives warehouses, shops, addresses
Sales Channel Where products are sold web store, mobile app, B2B portal
Region Markets currency, countries, payment providers
Customer Shoppers customers, addresses, customer groups
Cart The shopping session carts, line items, shipping methods, adjustments
Promotion Discount rules promotions, campaigns, application methods
Tax Tax rules tax regions, tax rates, providers
Payment Money movement payment collections, sessions, payments, refunds
Fulfillment Shipping shipping options, profiles, fulfillments, service zones
Order The record of a sale orders, items, transactions, returns, claims, changes
Auth, User, API Key Access identities, admin users, publishable and secret keys

Others handle notifications, files, caching, events and workflow storage (Notifications, Email and File Providers). Not every project uses every module, and you can swap the implementation behind several of them.

Modules know only their own world

The most important rule: a module stores only its own data and refers to other modules by ID. A cart line item holds a variant_id and a title and price snapshot. It does not contain a product object, and the cart table has no foreign key into the product table.

flowchart LR
    CUST["Customer"] -. "customer_id" .-> CART["Cart"]
    REG["Region"] -. "region_id" .-> CART
    SC["Sales Channel"] -. "sales_channel_id" .-> CART
    PROD["Product<br/>variants"] -. "variant_id" .-> CART
    CART -->|"completed into"| ORD["Order"]
    PS["Pricing<br/>price sets"] -. "linked to variants" .-> PROD
    INV["Inventory<br/>items"] -. "linked to variants" .-> PROD
    CART --> PAY["Payment collection"]

Dotted arrows are references by ID or by a link; no module reads another module's tables.

Some of these relationships are stored directly as ID columns (a cart's region_id). Others are links, separate records that connect two modules' entities, such as a product variant and its price set or its inventory item. Links let Medusa keep the Product module ignorant of Pricing and Inventory while still showing prices and stock on a product page. Module Links covers them in detail, and Query: Fields, Filters and Pagination shows how to read across them.

How a sale moves through the modules

Follow one purchase:

  1. The Product module holds a T-shirt with variants. The Pricing module holds a price set per variant. The Inventory module tracks units in a Stock Location.
  2. A shopper in a Region and Sales Channel creates a Cart and adds a variant. The cart module records a line item and asks pricing for a calculated price.
  3. A Promotion may add an adjustment; the Tax module computes tax lines; the Fulfillment module lists shipping options for the address.
  4. A Payment collection and session are created with a payment provider.
  5. Completing the cart runs a workflow that authorizes the payment, reserves Inventory, creates the Order, and emits events. The cart is marked completed.

Steps 2 to 5 cross several modules, which is exactly why they are orchestrated by workflows (Hooks and Built-in Workflows) rather than by one module calling another's tables. The business side of this journey, including why an order keeps its own copy of prices, is described in The Order Lifecycle and State Machines and The E-commerce Domain Model.

Where your code fits

You rarely edit a commerce module. Instead you:

  • extend through workflow hooks and subscribers when core behavior needs a tweak;
  • add a custom module for new data, and link it to core records;
  • replace a provider (payment, fulfillment, tax, notification, file) when you need another vendor.

Stand-in 1: catalog, cart and order as plain objects

This model is not Medusa's schema. It mimics the relationships: separate "modules" (plain objects) that reference each other only by ID, and an order that snapshots what was sold. Money is in integer cents (Representing Money Correctly).

JS Three modules that reference each other by ID

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The cart kept the price it was given when the item was added. In real Medusa, cart prices can be refreshed when the cart changes, but a completed order never changes just because the catalog does.

Stand-in 2: composing module data with a mini query

When a page needs data from several modules, nobody joins their tables. A query layer asks each module for its slice and merges the results using IDs. Medusa's Query does this with links; this stand-in does the same with a hand-written link table.

JS Stitching module data together

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How does the Cart module refer to a product variant?

    Modules refer to each other by ID. The cart keeps the variant ID and the data it needs, never a join into another module's tables.
  2. 2. Which module is responsible for stock quantities?

    Inventory owns inventory items, levels per stock location and reservations. Products and variants are linked to inventory items rather than storing quantities.
  3. 3. Why does completing a cart run as a workflow rather than one module function?

    Completing a cart involves payment, inventory, order creation and events across modules. A workflow coordinates these steps and can compensate if one fails.
  4. 4. What should you do first when core behavior needs a small change?

    Extension points keep you upgradable. Hooks, subscribers, custom modules and links change behavior without modifying core code.

Summary

  • Commerce modules each own one area: catalog, pricing, inventory, cart, order, customer, payment, fulfillment, tax, promotion, region and more.
  • Modules store only their own data and refer to others by ID or by links; no module reads another's tables.
  • A sale crosses many modules and is coordinated by workflows; the order keeps its own snapshot of what was sold.
  • Extend Medusa through hooks, subscribers, custom modules and providers instead of changing core code.
  • The plain-object models here are stand-ins that show the relationships, not Medusa's real schema.

Next: Products, Variants and Options