Stock — Overview

A StockReference is the central concept in the stock domain. It represents the presence of a specific product variant at a specific location — combining a VariantType (identified by SKU) with a LocationType. Every quantity tracked in the system is scoped to a StockReference.

---

GraphQL Types

StockReferenceType

The root type for a stock reference.

type StockReferenceType {
  id: ID!
  sku: String!
  reference: String
  status: StockReferenceStatusEnum!
  model: ProductModelEnum!
  physicalQuantity: Int!
  usableQuantity: Int!
  reservedQuantity: Int!
  location: LocationType
  productVariant: VariantType
  storageProfile: StorageProfileType
  organization: OrganizationType
  createdAt: DateTime!
  updatedAt: DateTime!
}

Field	Type	Description
id	ID!	Unique identifier
sku	String!	The variant SKU this stock reference tracks
reference	String	Optional custom warehouse reference code
status	StockReferenceStatusEnum!	Lifecycle status — see below
model	ProductModelEnum!	PRODUCT (single variant) or BUNDLE (composite)
physicalQuantity	Int!	Actual units physically present at the location
usableQuantity	Int!	Units available to be sold (physical minus on-hold stock)
reservedQuantity	Int!	Units committed to delivery orders but not yet shipped
location	LocationType	The location where this stock is held
productVariant	VariantType	The variant linked to this stock reference
storageProfile	StorageProfileType	Storage rules applied to this reference
organization	OrganizationType	Owner organization
createdAt	DateTime!	ISO 8601 creation timestamp
updatedAt	DateTime!	ISO 8601 last-update timestamp

---

StorageProfileType

A StorageProfile defines optional warehouse management rules applied to a stock reference, such as batch tracking or expiry date management.

type StorageProfileType {
  id: ID!
  name: String!
  batchManagement: Boolean!
  limitUsageDateManagement: Boolean!
  sellingDelay: Int
}

Field	Type	Description
id	ID!	Unique identifier
name	String!	Human-readable profile name
batchManagement	Boolean!	Whether batch/lot tracking is enabled
limitUsageDateManagement	Boolean!	Whether expiry date tracking is enforced
sellingDelay	Int	Minimum days before expiry that units may still be sold

---

Stock Quantities

Three quantity counters are maintained independently on every StockReference.

Quantity	Field	Description
Physical	physicalQuantity	The real number of units present at the location. Updated by receptions, returns, shipments, and inventory adjustments.
Usable	usableQuantity	Units that can be allocated to new delivery orders. Decremented when a delivery order is created; incremented when a delivery order line is cancelled.
Reserved	reservedQuantity	Units locked for confirmed delivery orders awaiting shipment. Incremented on delivery order creation; decremented when a delivery order line ships.

Relationship: usableQuantity typically equals physicalQuantity - reservedQuantity, but they are managed independently so discrepancies can be corrected via inventory adjustments.

---

Stock Reference Statuses

Status	Description
DRAFT	Newly created stock reference, not yet active. No fulfillment routing occurs.
VALID	Active and eligible for fulfillment. Usable stock is visible to the order routing engine.
ON_HOLD	Temporarily suspended. Stock is tracked but not available for new delivery orders.
ARCHIVED	Permanently deactivated. Cannot be restored. All quantities are frozen.

New stock references created at a WAREHOUSE location are placed in DRAFT status until stockReferenceRequestFulfillment is called. Stock references at INTERNAL locations start as VALID directly.

---

Stock Movement Types

The diagram below shows which business events trigger which quantity movements.

---

Stock Movement Natures

Every programmatic stock movement must declare a nature that describes the business reason for the change.

Nature	Description
ORDER	Movement related to order fulfillment (e.g., picking for a delivery order)
RETURN	Product return received from a customer
RECEPTION	Stock reception, typically from a transfer order or supplier delivery
WAREHOUSE_INVENTORY	Inventory count adjustment or reconciliation
LOSS	Stock loss due to damage, theft, or expiry

---

Location Types and Stock Behavior

The type of location where a StockReference exists affects how stock is managed.

Location Type	Stock Creation	Fulfillment Activation	Movements
INTERNAL	Starts as VALID immediately	Automatic	Managed directly via API mutations
WAREHOUSE	Starts as DRAFT	Requires stockReferenceRequestFulfillment call	Managed by the connected fulfillment service; API mutations trigger sync
EXTERNAL	N/A	N/A	Stock movements are not allowed

Auto-registration

Locations with registerAllVariants set to true will automatically create a StockReference for every new variant in the organization. Otherwise, you must create stock references manually.

---

Bundle Stock Management

When model is BUNDLE, the StockReference represents a composite product assembled from multiple component variants. Bundle stock behavior differs from standard products:

• physicalQuantity reflects the number of assembled or assemblable bundles, not the sum of components.
• usableQuantity is constrained by the component with the lowest available stock divided by its quantity in the bundle definition.
• Component stock references are decremented individually when a bundle delivery order is shipped.
• Bundles must be explicitly declared with model: BUNDLE at creation time and cannot be changed afterwards.

---

Storage Profiles

A StorageProfile is an optional warehouse configuration attached to a StockReference at creation time. Profiles are defined at the organization level and reused across multiple references.

Key behaviors enabled by storage profiles:

• Batch management — assigns a batch/lot number to each reception, enabling FEFO (First Expired, First Out) picking strategies.
• Limit usage date management — enforces expiry date tracking; units past their limitUsageDate are automatically excluded from usableQuantity.
• Selling delay — prevents units from being allocated if their remaining shelf life (in days) is below the configured threshold.

Storage profiles are optional. Stock references without a profile use no special warehouse management rules.

---

Operations

Queries

Operation	Scope	Description
stockReference	view_stock_references	Retrieve a stock reference by ID, SKU, or reference

Mutations

Operation	Scope	Description
stockReferenceCreate	create_stock_references	Create a stock reference linking a variant to a location
stockReferenceAdjustInventoryLevel	edit_stock_references	Set absolute inventory levels (inventory reconciliation)
stockReferenceUpdatePhysicalStock	edit_stock_references	Increment or decrement physical, usable, or reserved stock by a delta
stockReferenceArchive	edit_stock_references	Permanently archive a stock reference
stockReferenceRequestFulfillment	edit_stock_references	Activate a DRAFT stock reference at a WAREHOUSE location

---

Best Practices

1. One StockReference per (SKU, Location) pair. The combination is unique — attempting to create a duplicate will return a conflict error.
2. Prefer adjustInventoryLevel for reconciliation. Use delta mutations (updatePhysicalStock) for incremental movements; use adjustInventoryLevel only when you have a verified physical count.
3. Declare movement natures accurately. The nature field drives audit logs and reporting — always choose the most semantically correct value.
4. Call requestFulfillment before routing orders to WAREHOUSE locations. A stock reference in DRAFT status will never receive delivery orders.
5. Archive instead of deleting. Archiving preserves the full audit history. There is no delete operation.
6. Use Transfer Orders for stock replenishment. To move stock from suppliers to fulfillment locations, create a Transfer Order rather than manually adjusting inventory levels.