Skip to main content
Stock items table in the admin

Inventory > Stock Items

Definition

A Stock Item is the unit of inventory you actually own — the digital twin of a physical thing. Stock items are held in inventory records (called an article in the API), one record per item or one record covering several identical ones; how you track them is your choice. A record carries codes, condition, attributes, media, documents, a full event timeline, and income and expenses, and belongs to a tenant. Its units sit at one or more Locations. It may also be linked to a SKU, from which it inherits product-level fields by default.
The Analogy: Think of a Stock Item as the passport for a physical product. A passport tracks a person’s journey under a unique ID, and a Stock Item tracks a product’s complete lifecycle under its own item code — where it has been, what has happened to it, and where it is now.
Special in TWICE: Stock Items are serialized by default — registration tracks each unit individually unless you turn Track individually off. One physical thing = one Stock Item. This is what makes per-item profitability, condition tracking, and maintenance history possible — and it is the foundation of the article ledger.

Where do I use it?

Stock Items are the foundation of TWICE’s inventory system. You work with Stock Items when:
  • Registering new inventory — recording units that enter your fleet, store, or warehouse
  • Tracking item lifecycle — usage, rentals, sales, maintenance, disposal
  • Managing availability — knowing what is at hand, out with a customer, or under repair
  • Analysing profitability — reading income and costs per individual item via the ledger
  • Fulfilling orders — assigning specific items to customer orders, scanning them in and out
The serialized nature of Stock Items is what enables precise tracking for rental operations, buyback programs, refurbishment workflows, and maintenance-heavy businesses.

The article ledger

Every Stock Item has its own ledger, a chronological log of monetary entries grouped as income or cost. Together they produce the item’s profitability. In the admin it is the item’s Income & Expenses tab, which holds three kinds of entry:
  • Entries you add on the tab. They cannot be edited: delete one and add it again. An entry added on a reservation or a note links to it under Reference.
  • Purchase price, which follows the purchase price saved on the Stock Item. Clearing the field removes it. A price the Stock Item inherits from its SKU adds no entry and does not count toward Total Costs.
  • Order revenue, one for each order line the unit was assigned to: its share of the line, without taxes. It changes with the order and cannot be deleted from the tab.
Profitability is Total Income minus Total Costs. It does not depreciate the purchase price: work out a residual value with an attribute formula. To compare units across the fleet, show the Item Costs, Item Income and Profitability columns in the Stock items table. See Set a purchase price and Record a cost or income. In the API the resource is articleLedgers, and the totals come back on the Stock Item: Order revenue carries its orderId, and an entry added on a reservation or a note carries its scheduledEventId.
Per-item profitability requires serialized tracking. On pooled stock items (one record covering several units), ledger totals apply to the pool as a whole, and you cannot attribute them to a specific unit. See Inventory tracking.

Quantity handling: serialized vs pooled

How a Stock Item is tracked is decided at registration with the Track individually checkbox (trackIndividually in the create request, default true) and the Quantity field. With Track individually on, registering quantity N creates one inventory record per stock item. With it off, you create a single record covering all N. trackIndividually is a create-time input only — it is not stored on the Article resource. On responses, the quantity object reports the record’s total unit count and its byLocation breakdown. When to choose each:
  • Serialized — bikes, skis, cameras, lifts, kayaks, e-scooters, any rentable or high-value asset.
  • Pooled — helmets, locks, lanyards, lift passes (when not RFID), small consumables you do not need to trace individually.
Mode is set on creation. To change it later you create a new record and migrate history; in-place conversion is not supported. Read more: Inventory tracking.

Key Properties

A Stock Item is represented by the Article type. The most important fields: Per-item state is computed at query time and exposed on the article-with-availability response:
Property inheritance from SKU. purchasePrice, description, attributes, and category can be defined on the SKU. The Stock Item reads from the SKU unless it has its own value. The *Origin fields in the API tell you which source supplied each value (article or sku). Setting a value on the item overrides the SKU default; clearing the value lets it re-inherit.Fulfillment field values inherit the same way and are kept apart from attributes: a value entered on an order wins, else the item’s, else its SKU’s. See Fulfillment fields.

Status

Status describes where the item sits in its operational lifecycle. Three values exist:
  • Active — operational, available to be assigned to orders. (status: 'active' in the API.)
  • Inactive — excluded from operations (e.g. under repair, retired, lost, or sold). Preserved in the system. (status: 'inactive'.)
  • Draft — registration in progress. Not yet operational. (status: 'draft'.)
Only Active items count toward ATS and can be assigned to new orders. Inactive items keep their full history (ledger, events, attachments). Read more: Stock item status.

State (In / Out)

State describes the item’s physical location relative to your operation. It is automatic — you cannot set it manually.
  • In — at hand in your inventory. May still be committed to an upcoming order.
  • Out — currently with a customer (rental in progress) or otherwise away.
State transitions happen on fulfillment events:
  • Pickup / handout → Out
  • Return → In
Read more: Stock item state.

Location tracking

A Stock Item has no location field. Its units sit at Locations, and articleLocations on the stock item response counts them per Location over time:
An entry whose range covers the current moment places that many units at the Location now. quantity.byLocation gives the same count as a total per Location. Units change Location in two ways:
  • A quantity change at each Location. Add the units where they arrived and remove them where they left, with Edit Item quantity on the item’s General tab, or with POST /articles/:id/increase-quantity and POST /articles/:id/decrease-quantity, each taking a serviceLocationId. See Move a stock item to another location.
  • Archiving a Location with “Move stock items to another location”, which moves every Stock Item there to the Location you pick. See Locations settings.
Before a reduction, GET /articles/:id/plan-quantity-change lists the bookings it would leave without a unit. Read more: Locations.

Orders hold units at their pickup location

An order holds a unit of a pooled Stock Item at its pickup location only. TWICE Commerce counts availability for each Location on its own, so a Location with no free unit for the order’s dates refuses the order, even when another Location has units free. The refusal carries the reason stock_item_unavailable. The rule covers checkout, orders created in the admin or with POST /internal/orders, switching the unit on an order line, and changing an order’s dates. Units never move between Locations to fill an order. To take orders at a Location that shows 0 available, add units there with Edit Item quantity, as described under Location tracking above.

Media and documents

Two ordered file collections per item:
  • Media (media) — images and videos shown on the item detail. The first media item is used as the thumbnail in lists. Reorderable.
  • Documents (documents) — arbitrary files (PDFs, spreadsheets, photos). Each document carries an orderIndex and an optional comment.
Documents can also be attached to specific scheduled events (e.g. inspection notes against a maintenance reservation) — see Stock item events.

Activity log and events

A Stock Item’s history sits on two tabs of its page:
  • Events lists what holds the item: the orders it is on, and the reservations and notes added to it (scheduledEvents, types reservation and note). Reservations and notes can block availability and carry documents. See Stock item events.
  • Activity log lists the requests that touched the item, from the admin or the API, with who made each and when. See Activity logs.
Read both with Read a stock item’s history.

Relationships

Stock Items can link to a SKU via skuId. The SKU acts as the product-level template: purchasePrice, description, attributes, and category cascade down unless overridden. A Stock Item without a SKU is fully self-contained.
Has many entries that combine into itemIncome, itemCosts, and profitability.
Has many and an . See Events.
Linked to the Orders that reserve the item. State and unavailability are driven by orders that include the item.
Its units sit at one or more Locations, counted per Location over time in articleLocations.

Lifecycle

1

Creation

Stock Items enter your system when you register new inventory.
From Inventory → Stock items, click Register Items and choose Manual Entry. In the Register new stock item dialog, provide a name, choose whether to Track individually, set a quantity, pick an Entry Location, and optionally link to a SKU. See Register stock items.To start from photos, choose Upload Images instead. TWICE Commerce reads the first photo and fills in the same dialog with a suggested name, setting a category and attributes the dialog does not show. A suggestion can come back empty: fill in the dialog as for Manual Entry. See Register from photos.
Minimum: name and serviceLocationId. Recommended: skuId (for inheritance), taxonomyCategoryId, purchasePrice, and one or more codes (auto-generated if omitted).
2

Initial state and bulk creation

A new item counts from its entry date.
New items default to status: 'active' (Active) and the In state. They count toward availability from their Entry date, which the registration dialog sets to the current time unless you change it. If items need inspection before going live, set status to inactive (Inactive) on creation.
Yes. Use bulk register in the admin (auto-generates codes for N items), the CSV import flow, or POST /articles/create-many for API import. See Bulk creation for which call to make and how many records to create.
3

Usage

Active Stock Items participate in orders, listings, and reports.
Inventory → Stock Items table, the item detail page (General / Attributes / Income & Expenses / Fulfilment / Documents / Events / Activity log tabs), fulfillment screens, availability calendars, and SKU detail pages.
Edit its fields, change its quantity at a Location, change status, add media or documents, add scheduled events (reservations / notes), record income and expense entries, add tags, and link / unlink the SKU.
Only items with status: active and In state (and not committed to an overlapping booking) contribute to a listing’s ATS. See Stock item state.
4

Modification

Update fields throughout the lifecycle.
Open the item detail and edit inline, or select multiple rows in the table and use bulk edit: see Bulk-edit stock items. The API endpoint is PUT /articles/:id.
Almost everything: name, SKU link, codes, status, attributes, condition, purchase price, description, media, documents, tags. Where its units sit changes through quantity, below. The id itself is immutable. Codes can be added or removed but must remain unique within the tenant.
Use Edit Item quantity on the General tab, which changes the quantity at one Location at a time. In the API, use POST /articles/:id/increase-quantity or POST /articles/:id/decrease-quantity. Before decreasing, call GET /articles/:id/plan-quantity-change to see what would be impacted (blockingUnavailabilities, moves, removedSlotIds).
5

Retirement or deletion

Prefer status changes over deletion to preserve history.
Set status to Inactive. All history (ledger, events, attachments) is preserved and the item drops out of availability immediately.
Archive it, which keeps the record readable. See Archive stock items.
Only when it has never been on an order. DELETE /articles/:id refuses with Stock items with order history cannot be deleted — archive them instead for an item that sits on an order or holds an order-linked reservation. Order status is ignored, so closing the order does not lift the refusal.
Nothing. A deletable item has no order history to lose.

FAQs

Availability counts per Location, and an order holds a unit only at its pickup location. Add units at the Location with Edit Item quantity on the General tab. See Orders hold units at their pickup location, under Location tracking.
Use pooled stock for identical, low-value, interchangeable items where individual tracking adds no value (helmets, locks, lanyards). Use serialized (qty = 1, Track individually) for anything you want to follow per unit: high-value gear, anything that depreciates differently, anything rented out.
codes belongs to the Stock Item — it identifies the physical thing. code on the SKU identifies the product type. One SKU can have many Stock Items, each with its own item code(s).
purchasePrice, description, attributes, and taxonomyCategoryId, among others: see Inherited fields for the full list. The API returns *Origin fields telling you whether the value came from the article or the SKU. Setting a value on the article overrides; clearing it re-inherits.
Item Name, SKU Name, SKU Code, Category, attributes and media reach every selected Stock Item. So does every value written from the Multiple matching values dialog, Status included. Item Code is edited on each Stock Item.The rest writes to the first selected item only: Purchase Price, Condition, Description, Tags, Status where the items already agree, and every tab but General and Attributes. Purchase Price and Condition show the first item’s value even where the items differ. Quantity and buffer time cannot be edited for several items.Edit with one row ticked opens that Stock Item on its own page. Select all items selects rows for archiving only and greys out Edit. The selection lives in the browser tab you opened it from, for an hour, and after that the page opens empty, as New article. See Bulk-edit stock items.
Status is your call (Active / Inactive / Draft). State is set by fulfillment (In / Out). They are independent — an Active / Out item is healthy inventory that is currently with a customer.
Set its status to Inactive — there is no separate Lost or Sold status. The change does not retroactively modify orders that include the item; handle those manually (refund, reassign). Record the reason as a note or ledger entry.

Developer Reference

Stock Items are exposed as articles in the API.

API: Articles

Open the endpoint in the API reference.

SKUs

Product-level template for Stock Items

Stock Item Status

Active / Inactive / Draft

Stock Item State

In / Out — physical location vs your operation

Stock Codes

Identifiers, barcodes, scanning workflows

Inventory Tracking

Serialized vs pooled

Stock Item Events

Reservations, notes, activity log