Skip to main content
Item code shown on a stock item

Inventory > Stock Items > [Item] > General

Definition

A stock item’s codes are the chips in Item Code on its General tab. In the API they are the codes array on the Article resource. Each code is a string, and no two stock items in your account can share one.

Stock code vs SKU code

These are different identifiers at different levels. A bike B-1 (stock code) is one specific unit of the BIK-S (SKU code) product. Twenty bikes of the same model = twenty stock codes pointing to one SKU code.

Where do I use it?

Stock codes are used throughout TWICE Commerce for:
  • Unique identification: referencing specific units in orders, reports and operations.
  • Scanning: a label on the unit finds its record, whether you collect units into Scanned items or scan one onto an order.
  • Data integrity: the uniqueness check stops two records from claiming one code.
  • API operations: reading and changing specific stock items from your own systems.
  • Audit trails: the activity log records every change to a unit’s codes.

Key Properties

System-generated vs custom codes

Choose under Item codes when you register stock items. The choice applies to every unit you register in one go.

Auto-generated

Auto-generate gives each stock item a random 8-character code, such as LF93HXB1. Use it when you print the code on a label and nobody has to type it. Through the API, omit codes when you create the article.

Manual entry

Manual takes the codes you type, paste or scan, separated by spaces or commas. Each code becomes one unit, so the number of codes sets the quantity. Use it for asset tags already on the units (B-1), serial numbers (SN-2024-00123) or location-prefixed codes (HEL-BIK-001). To number a delivery in sequence, such as B-1 to B-40, enter the whole list under Manual. Through the API, send codes on create or update. Check them first with POST /articles/validate-code, or with POST /articles/validate-codes for a batch.

Multiple codes per item

A single Stock Item can have several values in its codes array, and a scan of any of them finds it. Add a code beside the others in Add a stock code.
  • SKI-001: your asset tag, printed on a sticker.
  • SN240501234: the manufacturer’s serial number, printed on the ski.
  • HEL-0042: the label from the system you used before, still on older units.
Removing or replacing one code leaves the others working.

Code format rules

  • Type: string. No length limit beyond the 8 characters of a generated code.
  • Characters: any printable characters. Keep to letters, digits, hyphens and underscores so codes survive label printers and barcode scanners.
  • Uniqueness: per tenant. Validated on create and update.
  • Case: a scan matches the code exactly, so b-1 does not find B-1. Pick one casing and keep to it.
  • Spaces: the admin’s code fields split what you type on spaces and commas, so a code entered there cannot contain either. A scan trims spaces at either end before it matches.
Good patterns:

QR codes and barcode scanning

Put the stock code on the unit and the listing barcode on the shelf or the packaging. Common workflows:
  • Print on receive. When new stock arrives, register it with generated or your own codes, then print labels from the admin.
  • Scan to collect. Scan a unit’s code anywhere outside an order, and the unit joins the Scanned items drawer, where you act on the whole pile at once. See Scan stock items.
  • Scan to return. Scan the units that came back and choose More → Return from orders in the drawer. See Return scanned items.
  • Scan on an order. An open order reads four kinds of code and does something different with each.

What a scan outside an order does

Every scan is checked against all four kinds at once, and each kind is unique only within itself. A code that matches more than one opens “This code matches more than one thing” and asks which you meant. Outside an order, no kind outranks another.
The dialog This code matches more than one thing, listing a stock item and a listing to choose between

One code naming both a stock item and a listing

A code matches exactly, character for character, once spaces at either end are trimmed. An order also matches its bare number, so 42 finds order #42, but only a code of digits alone reads as a number. A scan is ignored while a text field holds the cursor, and on an order’s own page, which runs its own scanner.

The scanned items pile

Scanned units collect in the Scanned items drawer, every row ticked. A stock item holding several identical units under one code counts one more unit per scan, up to what it holds. The drawer’s actions take the ticked rows, or every row when none is ticked, and More takes at most 200 units at a time. The pile stays while you move between pages. Units leave it when More or Archive acts on them, when you click Clear all scans, or when you close the browser tab. To free units from an order or a reservation that still holds them, choose More → Make available. See Make scanned items available. To hold them for a set window, choose More → Create reservation. To put them on a new order, choose More → Create order. See Reserve scanned items and Create an order from scanned items.

What a scan on an order does

A closed order, or one your role cannot change, takes order numbers only. A code that matches more than one kind asks which you meant, and a SKU code counts only when nothing else matches. With a panel open, close it first. The stock item panel is the exception: there a scan picks the unit’s row under Change stock item.

Uniqueness scope

The uniqueness constraint is per tenant (your TWICE Commerce account). Two different tenants can both have a B-1 Stock Item. Within a tenant:
  • Each code in any article’s codes array must be unique across all Stock Items.
  • Validation happens server-side on create and update via the articleCodes table.
  • Use POST /articles/validate-code (single) or POST /articles/validate-codes (batch) before submitting to fail fast with a clear error.

Relationships

Lifecycle

1

Creation

Codes are assigned on Stock Item creation.
If you submit codes: ["..."] they are used as-is. If you omit codes, TWICE Commerce generates an 8-character random code. In the admin, the same choice is Auto-generate or Manual under Item codes.
Yes. POST /articles/validate-code with { code } returns { isUnique }. POST /articles/validate-codes with { codes: [...] } returns the list of invalid codes and their reason (existing).
2

Usage

Codes are the everyday handle on a Stock Item.
On the Stock Item detail, in the table column, in orders that include the item, on labels you print, in scanning workflows, and in every API response that includes the Article.
Yes. The Stock Items table search and the global admin search resolve codes to their Stock Item. The API supports filters.code for exact and partial matching.
3

Modification

Codes can be added, removed, or replaced.
In the admin, add it in Item Code on the unit’s General tab and save. Add a stock code walks through it. Through the API, send PUT /articles/:id with the new full array. The change is logged as an identifiers_changed event with the previous and new arrays.
Yes. Replace the code with the new value. The old code is detached and immediately becomes available for use on another item.
Order line items and ledger entries reference the Stock Item by its id, not by its code. Changing or removing a code does not break historical links.

FAQs

Yes. Add, remove or replace codes at any time. The change is recorded in the activity log as identifiers_changed. Historical orders and ledger entries link by item id, not by code, so they remain valid.
They are the same thing. “Stock code” emphasises the inventory tracking angle; “item code” emphasises that it identifies a specific physical item. In the API, the field is codes on the Article resource.
No. Codes are unique across all Stock Items in a tenant. If you try to create or update with a duplicate code, the operation fails with an existing validation reason.
Yes. The codes field is an array. You can attach an internal code, a manufacturer serial number and the code from an older label to the same Stock Item, and scanning any of them resolves to that item.
Whatever fits your operation. Most operators use alphanumerics with hyphens or underscores so codes survive label printers and barcode scanners. The system generates 8-character random codes when you omit a value.
Per tenant. A code is unique across your whole account, not just within one service location. Two locations in the same TWICE tenant cannot both have B-1.
The scan was ignored. A scan is ignored while a text field, such as a search box, holds the cursor, and on an order’s own page, which runs its own scanner. Click an empty part of the page and scan again, and check that the scanner ends each code with Enter.
The scanner read the code, and no stock item, listing, SKU or order carries exactly that string. Search Inventory → Stock items for the code as text. If it is there, compare the two: a scanner set to add a prefix or a suffix sends a string that no longer matches. A scan searches only what your role can view.
The string is on more than one kind of record, most often a manufacturer’s barcode used as both a stock code and a listing barcode. Pick the one you meant and the scan carries on. Give units codes of their own and leave the manufacturer’s barcode to the listing, and the question stops.

Developer Reference

Stock codes are managed via the articles endpoints. Use validate-code to check uniqueness before creating.

API: Articles

Open the endpoint in the API reference.

Stock Items

The records that codes identify

SKUs

SKU code vs item code

Inventory Tracking

Codes behave differently for serialized vs pooled inventory