Glossary
Definitions for the core domain entities used across the National Commerce platform.
This glossary defines the core domain entities used throughout the National Commerce system. It is seeded from the internal Client Dictionary.
From concept to table
Each term below maps to one or more tables in the Database reference. Where a term has a table, an In the database line links straight to it. To see how these records move between ShipHero, N8N, the worker, and Supabase, read Data Flows.
Brand hierarchy
Parent Brand
Parent of the Brand. A Parent Brand can have many brands beneath it.
In the database: Parent Brand.
Brand
A single brand in the system.
Deprecated
Brand no longer exists in the NC system. Accounts replaced it.
In the database: the Brands
table (one row per account).
Account
A single connection to ShipHero.
In the database: an account is a
Brands row, one ShipHero
connection with its own credentials and settings.
SKUs
The system distinguishes between several kinds of SKU. Different people track inventory against different SKU types, so it is important to keep them straight.
The Products & SKUs page shows how the three SKU tables and the bill-of-materials junction fit together.
Product SKU
The SKU you can actually buy on Amazon.
In the database: Product SKUs.
Base SKU
The SKU some people track inventory against. (Other people use the Product SKU instead.)
In the database: Base SKUs.
Inventory SKU
It is a Base SKU.
In the database: the same Base SKUs
table. inventory_sku is the column inventory is tracked against.
Case SKU
A bundle of either a Product SKU or Base SKU that can be purchased. Case SKUs are purchased for inventory replenishment.
Why case SKUs exist
It's cheaper to order packs of 12 chocolate bars than 12 single packs, because someone has to scan each package.
In the database: Case SKUs.
Inventory
Inventory (entity)
The amount of each Base SKU at a given warehouse.
In the database: Inventory, one row
per Base SKU per warehouse.
Warehouse
A place that stores inventory.
In the database: Warehouses.
Orders & shipments
Order
A request from a customer to buy thing(s).
In the database: Orders.
Shipment
An individual box that gets shipped to the customer, with its own label and label cost. A shipment links to an Order.
In the database: Shipments.
Line Item
A quantity of an individual product inside of the shipment box. A line item links to a Shipment.
In the database: Shipment Line Items.
Label
Paper that is stuck to the shipment box, defining the cost of shipping.
Label Cost
The cost of the label.
In the database: the Label_Cost column on
Shipments, rolled up to
total_label_cost on the Orders
row.
Voided Label
A label that was going to be used, but the decision was made to end it. This is usually caused when shipping is too expensive.
Postage Threshold
Something Sean created so he can track if shipments for a specific SKU are too expensive. You set it per product on the Products screen.
In the database: the Postage_Threshold column on
Product SKUs.
Exclude from metrics
A flag NC staff set on an order that is not a real sale, such as pallets shipped back to a brand. Every shipment and line item of a flagged order is left out of the stats and of daily demand. Quantity on hand is not affected. Staff switch it on the Shipments list, and can switch it back.
In the docs: Exclude from metrics.
In the database: the exclude_from_metrics column on
Orders.
Purchase orders
PO (Purchase Order)
A purchase order used to replenish inventory. Usually made up of Case SKUs.
In the database: Inventory Purchase Orders
(imported from ShipHero), with drafts built in the portal in
Inventory Replen Draft Purchase Orders.
PO Line Item
Similar to line items in an order, but for POs.
In the database: Inventory Purchase Order Line Items.
Confirmed Order
The replenishment order a client sends back after applying their cuts. Each client's sheet looks different. The Assistant reads it and turns it into draft POs, one per warehouse.
Replenishment Cycle
One brand's reorder cycle for one period, tracked from submitted through to complete. The purchase orders placed for that period attach to the cycle, so you can see what was ordered and what has arrived in one place. The portal calls a cycle a replenishment, and brands see their own read-only under Replenishments. See What brands see.
In the database: replenishment_cycles.
Replenishment Request
The weekly order National Commerce sends a brand for one cycle, snapshotted from the Replen Report. NC can adjust each line's Requested, add lines, or remove lines first. The brand opens it through a magic link with no login, approves or edits each SKU per warehouse in trays, and submits once. NC then turns the response into draft POs on the Case SKU.
In the database: a row in Inventory Replen Draft Purchase Orders
with a request_token, and its line items.
Recommended and Requested
The two numbers on each line of a replenishment request, in trays. Recommended is the Replen Report's Amount To Reorder when the request was made, and never changes. A line NC adds afterward has no Recommended. Requested is what NC asks the brand for: it starts at Recommended and NC can change it until the brand responds. The brand only sees Requested, and Approve and Edit work from it. They replace the single "Required" number the request used to have.
In the database: recommended_quantity and requested_quantity on
Inventory Replen Draft Purchase Order Line Items.
Tray
The unit a replenishment request is counted in. A tray is one base unit. A Case SKU holds about 12 trays.
Reorder Cadence
How often an account reorders, in days. Set per account by the team, and what the due and overdue nudge on the Replenishment Accounts screen measures against. Distinct from the SKU-derived cadence shown beside it, which is reference only.
Sign-in
Sign-in code
The 6-digit code the portal emails you each time you sign in. It works once and expires after 5 minutes. The portal has no passwords.
In the docs: Sign in to the portal.
Session
One device signed in to an account. A session ends when you sign out, after 7 days, or after 24 hours without use. You can see and end your sessions on the Security screen.
In the docs: Security. In the database: auth_events keeps the history of sign-ins and sign-outs.
Roles
Every portal login has one role, the same on every account it is assigned to.
NC Super Admin
National Commerce and OpsKings leads. Sees and changes everything, on every account, and is the only role that manages client connections and users. Set in the database only.
In the docs: Roles and access.
NC Internal User
Other National Commerce staff, such as account managers. Gets the brand-facing screens plus the internal ops screens on their assigned accounts, and sees client connections and users read-only.
In the docs: Roles and access.
Client User
A brand team member. Sees the brand-facing screens read-only on their assigned accounts, never sees internal screens, and never gets alert emails. The default type for a new invite.
In the docs: Roles and access.
Internal badge
The orange "Internal" mark NC staff see on every page brands can never open, in the sidebar and next to the page title.
In the docs: Roles and access.
Client preview
A read-only view of the portal exactly as one client's Client User sees it, started by NC staff with Preview as client and ended with Exit preview.
In the docs: Preview the portal as a client.
Releases
Staging
The copy of the portal, with its own database of placeholder data, where every change is reviewed before production. A change reaches production only after Sean approves it on staging.
In the docs: Staging and releases.
Assistant
Assistant
The set of tools Claude can use against National Commerce data once it is
connected to the MCP server in apps/mcp. Only National Commerce and OpsKings
staff can use it; brand users are refused. Most tools only read. The
draft-PO commit tool writes, and only when writes are switched on for the
server.
In the docs: Assistant.