Domain vocabulary

Domain vocabulary

The single source of truth for terms used across this package. Every other skill imports its definitions from here. When a term appears here, other skills use it with the meaning defined here — not with a platform-specific or colloquial meaning.

The goal is not to invent terminology. It is to converge on the least-ambiguous definition observable across recognized sources, and to flag where sources disagree so the reader knows when a choice is being made.

How to use this skill

1. Define before using. When a skill introduces a term, link the reader to this skill if the definition lives here. Do not redefine.
2. Disambiguate explicitly. If a platform uses one of these terms differently (Shopify's fulfillment_status ≠ this skill's fulfillment), say so once and continue with the canonical definition.
3. When in doubt, prefer the more restrictive definition. If "stock" could mean on-hand or available, force the choice — never use "stock" alone.

---

Vocabulary

Organized by domain area. Cross-references use italic.

Customers and accounts

Customer — A real-world buyer the system serves. Modeled as a record holding identity (name, contact info), addresses, payment methods, and order history. A customer exists whether or not the buyer is authenticated; the system can create a customer record from a guest checkout. Shopify, Medusa, and commercetools all use "customer" as the top-level commerce identity. (Shopify, Medusa)

Account — The customer's authenticated record in the system; the persistent state across sessions. "Account" is sometimes used interchangeably with customer, but the distinction matters when the customer can exist without an account (guest purchase) or when one account represents multiple customers (B2B parent company with branch buyers).

User — The authentication principal — the entity that logs in. A user is often linked to an account but is not the same: an admin user is not a customer; one user may switch between multiple customer contexts (B2B sales rep impersonating a customer); a guest customer has no user at all. Treat user, account, and customer as three orthogonal concepts and only collapse them when the business model truly requires only one.

Guest — A customer state in which no account has been created. Most platforms attach the order to an email-addressable customer record without persistent credentials; some delete the record after the order completes.

B2B account hierarchy — A modeling pattern where a parent legal entity (the company) contains child entities (branches, departments, individual buyers), each with their own addresses, price lists, and approval rules. commercetools formalizes this as "business units." (commercetools)

Catalog and products

Product — A sellable concept. Carries a name, description, category, and marketing media. A product itself is not always stockable; in most platforms the stockable unit is a variant. (Medusa, Shopify)

Variant — A specific configuration of a product (size, color, material). Each variant has its own price, inventory, and SKU. A product with no configurable options still typically has exactly one variant under the hood — the variant is the unit of stock and price, not the product.

SKU (Stock Keeping Unit) — The identifier of a stockable unit. Conventionally the variant carries the SKU. SKUs must be unique within their scope (typically the store or tenant). "SKU" is also used colloquially to mean "the variant," but strictly it is the identifier, not the entity.

Bundle (kit) — A sellable unit composed of multiple variants sold together. Two main modeling approaches: as a product with its own SKU whose inventory is derived from component availability ("virtual bundle"), or as a separately stocked unit assembled in advance ("physical bundle"). The distinction matters for inventory and fulfillment.

Configurable product — A product exposing options the buyer selects to reach a specific variant. Sylius models this explicitly; Shopify exposes it through option values. (Sylius)

Attribute vs option — Attributes are descriptive (material: cotton; weight: 200g). Options generate variants (size: S/M/L). The same data point can be either depending on whether it differentiates a variant. Confusing the two leads to either combinatorial variant explosion (every attribute becomes a variant) or under-modeling (size is treated as a description and you cannot sell each size separately).

Category, taxonomy, collection — Category is a hierarchical placement (Clothing > Shirts > T-shirts). Taxonomy is the whole tree. Collection is a curated grouping that need not be hierarchical (Summer Sale, Staff Picks). Treat them as separate concerns; one product belongs to one place in the taxonomy but can belong to many collections.

Pricing and money

List price (regular price) — The reference price for a variant, independent of promotions. Sometimes called "compare-at price" when shown struck-through next to a sale price.

Sale price (promotional price) — A reduced price effective for a period or condition. Distinct from a discount applied at the cart level: a sale price is intrinsic to the variant in a price list; a discount is computed during cart evaluation.

Price list — A scoped set of prices, typically keyed by channel, customer group, currency, and effective date. commercetools and Shopify B2B both expose price lists as first-class objects. (commercetools, Shopify)

Tax-inclusive vs tax-exclusive pricing — Whether the displayed price already includes tax (typical in EU B2C, AU, NZ) or excludes it (typical in US, B2B in most regions). The choice cascades through the entire stack: cart totals, invoices, refunds, reporting. (Stripe Tax)

Tiered pricing — Different unit prices at different quantity thresholds. Volume discount is the common case (10+ units = 5% off per unit); graduated tiers add complexity (first 10 at one price, next 90 at another).

Money — Per Fowler's pattern, a value composed of an amount and a currency, never a bare float. Currency math requires fixed-point or integer-minor-units arithmetic to avoid rounding errors. Currency codes follow ISO 4217. (Fowler, ISO 4217)

Inventory

These four states are the foundation; conflating them is the most common source of inventory bugs.

On-hand — Physical units present at a location. This count changes only when goods physically arrive (receiving) or leave (shipping, damage, theft, count adjustment). It does not decrement when a customer places an order. (Shopify)

Committed — Units of on-hand that have been reserved against confirmed orders not yet shipped. The customer's order is "promised" these units but they are still physically present. Shopify uses this term explicitly.

Reserved — Units held against a cart or checkout that has not yet become an order. Reservations are short-lived and typically expire. Some platforms collapse this with committed and only track post-order reservations; the distinction matters when reservation policy differs by stage.

Available (available-to-promise, ATP) — The count the storefront shows as buyable. Computed as on_hand − committed − reserved − safety_stock. Available is a derived value; never store it directly.

Safety stock — A buffer subtracted from available to absorb forecast error, demand spikes, or counting drift. The threshold may vary by variant and location.

Location (warehouse, store, fulfillment center) — A physical place that holds on-hand inventory. Multi-location inventory means a single variant has independent counts per location. Available stock can be computed per-location or aggregated, depending on whether the storefront promises shipment from a specific location.

Backorder — An order placed when available is zero, accepted with the promise to fulfill once stock arrives. The order accumulates a committed claim that exceeds on-hand.

Oversell — When the system accepts more orders than available allows, by accident or by policy. "By policy" is acceptable (backorders, pre-orders); "by accident" is a bug, usually caused by reading stale available without coordination.

Cart, quote, and order

These three are the core lifecycle artifacts. Treat them as three states of one underlying intent, not three independent concepts.

Cart — A buyer's working draft of an intended purchase. Mutable: line items can be added, removed, or quantity-adjusted; prices can re-evaluate as the cart changes. A cart belongs either to a customer or to an anonymous session. Carts expire. (Medusa)

Quote — A B2B-specific artifact: a cart that has been priced and offered to the buyer under specific terms (price, payment, validity period), pending acceptance. Distinguishing feature from a cart: a quote freezes terms; a cart re-evaluates. (Spryker)

Order — A cart or quote that has been committed: the buyer has agreed to purchase under specific terms. Orders are append-only in the sense that the original commitment is preserved; subsequent state changes (cancellation, refund, fulfillment) attach to the order rather than replacing it. (Sylius)

Line item — One row in a cart, quote, or order: a variant with a quantity, a unit price, applicable taxes, and discounts. The same word is used at all three stages; some platforms suffix with the stage (cart_item, order_item) for code clarity.

Order item — The order-stage version of a line item. Carries the price as of order commitment ("price at time of order"), which must not change even if the list price of the variant changes later.

Sub-order (fulfillment group) — A subset of an order's line items fulfilled together — typically because they ship from different locations, ship at different times, or belong to different vendors in a marketplace. Some platforms model this as separate orders; others as fulfillment groups within one order. Be explicit about which model is in use.

Order state — payment and fulfillment as orthogonal axes

An order has at least two independent state machines: payment and fulfillment. Treating them as one combined status leads to invalid states ("paid but unfulfillable") becoming hard to represent. Shopify exposes both: financial_status and fulfillment_status. (Shopify)

Payment status — Where the order stands financially: pending, authorized, paid, partially_paid, partially_refunded, refunded, voided. Names vary by platform.

Fulfillment status — Where the goods stand physically: unfulfilled, partially_fulfilled, fulfilled, shipped, delivered, returned. Some platforms split shipped/delivered; some collapse them.

Order status (lifecycle status) — The high-level rollup: draft, pending, confirmed, in_progress, completed, cancelled. Treat as a view over the underlying machines, not as the authoritative source.

Payments

Payment terminology converges around Stripe's vocabulary because Stripe formalized it most clearly. Other processors map onto these terms with minor naming differences.

Authorization — A confirmed reservation of funds on the buyer's payment method, valid for a limited period (typically 7–30 days for cards). The merchant has not yet received the money. (Stripe)

Capture — Conversion of an authorization into a settled charge. The funds begin moving to the merchant. Capture can be full or partial; partial capture forfeits the remaining authorization.

Sale (auth + capture) — Single-step charge that authorizes and captures simultaneously. Use when goods ship immediately; prefer separate auth + capture when fulfillment is delayed.

Void — Cancellation of an authorization before capture. Releases the held funds without a charge. Once captured, void is no longer possible — only refund.

Refund (full / partial) — Return of captured funds to the buyer. Partial refunds reduce the captured amount. Refunds are not the inverse of capture financially — they may involve different fees and timing. (Stripe Refunds)

Chargeback (dispute) — A buyer-initiated reversal through their bank, bypassing the merchant. Disputes have their own lifecycle (needs response, under review, won/lost) and incur fees regardless of outcome. (Stripe Disputes)

Hosted checkout — Payment captured on the processor's domain (Stripe Checkout, PayPal redirect). The merchant never touches card data; PCI scope is minimal.

Embedded checkout — Payment fields rendered in the merchant's UI using processor-provided tokenizing components (Stripe Elements, Payment Element). Card data goes from the buyer's browser directly to the processor; PCI scope is reduced but not eliminated. (Stripe)

Tokenization — Replacement of sensitive payment data with a non-sensitive token redeemable by the processor. The merchant stores the token; the actual PAN never reaches merchant systems.

Fulfillment and shipping

Fulfillment — The process of preparing and dispatching ordered goods. Encompasses pick, pack, label, hand off to carrier. A single order may have one or many fulfillments. (Medusa)

Shipment — A single physical parcel handed to a carrier. One fulfillment may produce one shipment or multiple (split shipments).

Carrier — The shipping company (UPS, FedEx, DHL, local courier).

Tracking number — The carrier's identifier for a shipment. Tied to a tracking URL the customer can use.

Pick-pack-ship — The warehouse workflow: pick items off shelves, pack them into a parcel, generate label, ship.

Split shipment — When one order is divided across multiple shipments, typically because items ship from different locations or at different times.

Channels and stores

Channel (sales channel) — A surface where the storefront is exposed: web, mobile app, marketplace integration (Amazon, eBay), physical POS, social commerce. Pricing, inventory, and tax policies can vary per channel. (Medusa)

Store (tenant) — An isolated commerce instance within a multi-store deployment. May correspond to a brand, a country, or a customer segment. Sharing of catalog, customers, and orders across stores is a design decision, not a default.

Region — A geographic scope for pricing, currency, tax rules, and shipping options. A store may serve one or many regions.

Cross-cutting

Idempotency — Property of an operation that produces the same result whether executed once or many times. Idempotency keys are client-supplied tokens that make non-idempotent operations safe to retry. See the idempotency skill. (Stripe, RFC 7231 §4.2)

Webhook — An HTTP callback from one system to another, used to notify the merchant of asynchronous events (payment confirmed, dispute opened). Webhooks require signature verification, retry handling, and consumer-side deduplication. See the webhooks skill. (Standard Webhooks)

Domain event — A record that something significant happened in the domain, named in past tense (OrderPlaced, PaymentCaptured). Used to integrate bounded contexts asynchronously. Distinct from a command, which requests something happen. (Fowler)

State machine — A model of allowed transitions between states. Both order and cart are naturally state-machine-shaped; encoding transitions explicitly (as Sylius does) prevents invalid state combinations.

---

Canonical model

The terms above describe one underlying mental model: commerce as a sequence of intent-becoming-commitment.

1. A customer (possibly guest) browses a catalog of products with variants.
2. They assemble a cart of line items, priced according to a price list scoped to a channel and possibly a customer group.
3. Inventory tracks four states (on-hand, committed, reserved, available); the storefront promises only available stock.
4. The cart converts to an order at checkout. The order locks in prices, addresses, and payment instrument.
5. The order moves on two orthogonal state machines: payment (authorize → capture → refund) and fulfillment (unfulfilled → fulfilled → shipped → delivered).
6. Asynchronous integration happens through webhooks and domain events; reliability comes from idempotency.

Treat this as one mental model with consistent vocabulary, not as a stack of independent concepts.

---

Variation dimensions

Vocabulary stays constant across these dimensions; the meaning of certain terms shifts within them. Be explicit about which point in the space the system occupies.

• Business model — B2C, B2B, marketplace, subscription, hybrid. B2B introduces quote and account hierarchy; marketplace introduces vendor and sub-order; subscription redefines order as recurring.
• Product type — Physical, digital, service, mixed. Physical needs fulfillment and shipment; digital needs entitlement and license key; service needs booking and appointment.
• Geography — Single-region vs multi-region. Multi-region multiplies price list, tax rules, currency, and channel.
• Customer model — Guest-only, account-required, hybrid, B2B hierarchy. Affects whether customer and account must be distinguished and whether user is meaningful.
• Inventory model — Single-location, multi-location, drop-shipped (third-party fulfills), virtual (digital, no stock). Affects whether on-hand and location are needed at all.

---

Decision frameworks

When two terms seem interchangeable, pick the more specific one

• "Stock" — never use alone. Say on-hand, available, committed, or reserved.
• "Customer" vs "account" vs "user" — collapse only if the system truly has no need for the distinction. Most non-trivial systems eventually need all three.
• "Status" vs "state" — synonymous in casual use; choose one and apply consistently. This package uses status for the buyer-visible label and state for the engineering enum that drives transitions.
• "Line item" vs "order item" vs "cart item" — use the stage-specific name (cart_item, order_item) in code; use line item in prose when the stage is unambiguous.

When a platform overloads a term

• Shopify uses fulfillment_status on the order level, not on individual line items, and treats partial fulfillment as a top-level state. Other platforms model fulfillment as a separate aggregate. Document which model the codebase uses and translate vocabulary at the boundary.
• Stripe's Charge and PaymentIntent are not synonymous: a PaymentIntent is a higher-level lifecycle wrapping zero or more Charges. Map to canonical authorization and capture terms in commerce code.
• Medusa's Order includes returns and exchanges as sub-modules of the order aggregate. Other platforms make returns top-level. The canonical vocabulary here puts returns adjacent to orders, not inside them; map at the boundary.

When in doubt

Prefer the definition observed across two or more recognized sources. If only one source supports a definition, label it as platform-specific in the skill that uses it.

---

Cross-platform vocabulary mapping

The canonical terms above are not invented for this package; they are the convergent vocabulary across commerce platforms, cloud providers, and academic references. The table below highlights how the canonical term maps onto specific systems, so the reader can translate at integration boundaries.

Canonical	Stripe	Shopify	commercetools	AWS retail patterns	Alibaba Cloud retail
Customer	Customer	Customer	Customer	"buyer profile"	"buyer" / "member"
Variant	(n/a — no catalog)	ProductVariant	ProductVariant	"stockable unit"	"SKU"
SKU	(n/a)	sku field on variant	sku field on variant	"stockable identifier"	"SKU code"
Order	Order (Stripe Orders beta) or implied via PaymentIntent	Order	Order	"order record"	"order" / "dingdan"
Cart	(Checkout Session covers cart concerns)	Cart (Storefront)	Cart	"cart" — usually DynamoDB-backed	"shopping cart"
Authorization	PaymentIntent (status requires_capture)	financial_status authorized	Payment with Authorization transaction	(depends on processor)	Alipay "authorization"
Capture	PaymentIntent.capture() / Charge captured=true	financial_status paid	Payment with Charge transaction	(depends on processor)	Alipay "settlement"
On-hand	(n/a)	available on InventoryLevel — see anti-pattern below about Shopify's naming	quantityOnStock	"physical inventory"	"shíhuò" (现货)
Available	(n/a)	computed from on_hand minus reservations	availableQuantity	"available-to-promise"	"kěxiāo" (可销)
Reserved	(n/a)	"reserved" in fulfillment service apps	Reservation (custom)	"reservation"	"yùzhàn" (预占)
Committed	(n/a)	committed on InventoryLevel	implied via order allocation	"committed inventory"	"yǐzhàn" (已占)

Important divergence: Shopify's available field on InventoryLevel is what most platforms call on_hand — it is the count of units not yet committed to fulfillment but does include units reservable. Shopify's committed is closest to the canonical reserved + committed. Translate at integration boundaries; do not let the platform's naming leak into domain code.

Other notable divergences:

• commercetools "Inventory entry" carries availableQuantity directly; the system computes it from on-hand minus reservations, but the API exposes it as a stored field. Treat as a read-through cache when wiring against it.
• AWS retail reference architectures typically model the cart and order as separate DynamoDB tables, with state transitions handled by Step Functions when the workflow spans multiple services.
• Alibaba's commerce stack (Taobao/Tmall) separates the "trading center" (cart, order, payment) from the "merchandising center" (catalog, inventory) — a natural bounded-context split that the canonical vocabulary above aligns with.

Anti-patterns

• Conflating on-hand with available. Causes oversell when the storefront shows on-hand counts. Always derive available from on-hand minus commitments.
• Treating customer, account, and user as one entity. Works until the business needs guest checkout, multi-user accounts (B2B), or admin impersonation. Refactoring three months later costs more than modeling them separately on day one.
• Storing prices as floats. Causes rounding bugs in totals, taxes, and refunds. Use integer minor units or a decimal/Money type from the start.
• Using "shipped" as the order completion signal. Order completion happens after delivery, returns window, and dispute window — sometimes weeks after shipment. "Shipped" is a fulfillment state, not an order state.
• Treating cart and order as one entity with a flag. Causes invalid states ("a cart with a payment intent") and ambiguous business rules ("can the customer still edit?"). Model them as separate aggregates with an explicit conversion event.
• Naming events as commands. CreateOrder is a command (intent to do something). OrderCreated is an event (something happened). Mixing them produces unclear contracts in event-driven integrations.
• Calling everything a "transaction." "Transaction" overloads database transaction, payment transaction, business transaction, audit log entry. Pick one meaning per context and use a different word for the others.
• Reusing variant SKUs across stores. Causes accidental cross-store inventory bleed when integrations key on SKU alone. Either scope SKU to store or use a system-generated stockable ID and treat SKU as a label.
• Treating refund as the financial inverse of capture. A refund is a new operation with its own fees, timing, and failure modes. Modeling it as "undo capture" makes reconciliation impossible.

---

Sources

• Medusa documentation — https://docs.medusajs.com/
• Sylius core concepts — https://docs.sylius.com/the-book/index.html
• Shopify Admin API — https://shopify.dev/docs/api/admin
• Shopify inventory states — https://shopify.dev/docs/apps/build/orders-fulfillment/inventory-management-apps
• Stripe API reference — https://docs.stripe.com/api
• Stripe payment intents — https://docs.stripe.com/payments/payment-intents
• Stripe refunds — https://docs.stripe.com/refunds
• Stripe disputes — https://docs.stripe.com/disputes
• Stripe Tax — https://docs.stripe.com/tax
• Stripe idempotent requests — https://docs.stripe.com/api/idempotent_requests
• commercetools business units — https://docs.commercetools.com/api/projects/business-units
• commercetools prices — https://docs.commercetools.com/api/projects/products#prices
• Spryker quote approval — https://docs.spryker.com/docs/pbc/all/cart-and-checkout/202410.0/base-shop/feature-overviews/quote-approval-feature-overview.html
• Standard Webhooks — https://www.standardwebhooks.com/
• Fowler — Money pattern — https://martinfowler.com/eaaCatalog/money.html
• Fowler — Domain Event — https://martinfowler.com/eaaDev/DomainEvent.html
• Evans, Domain-Driven Design, Chapter 2 (Ubiquitous Language)
• ISO 4217 — https://www.iso.org/iso-4217-currency-codes.html
• RFC 7231 §4.2 — https://datatracker.ietf.org/doc/html/rfc7231#section-4.2
• AWS retail architecture (cross-reference for cloud-aligned terms) — https://aws.amazon.com/retail/architecture/
• Alibaba Cloud retail solutions (Taobao/Tmall vocabulary) — https://www.alibabacloud.com/solutions/retail
• Azure Architecture Center — e-commerce reference architecture — https://learn.microsoft.com/en-us/azure/architecture/
• MACH Alliance — composable commerce vocabulary — https://machalliance.org/
• Bryar & Carr, Working Backwards (2021) — Amazon's vocabulary discipline (PR/FAQ, six-pagers, ubiquitous language)
• Werner Vogels — All Things Distributed — https://www.allthingsdistributed.com/
• Vernon, Domain-Driven Design Distilled (2016) — concise reference for commerce modelers