> ## Documentation Index
> Fetch the complete documentation index at: https://www.twicecommerce.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Stock Code (Item Code)

> The unique system-generated identifier assigned to each stock item ensuring accurate tracking and data consistency.

<Frame caption="Inventory > Stock Items > [Item] > General">
  <img src="https://mintcdn.com/twicecommerce/lZhc_tO8u1u_bL0Q/images/stock-item-general-tab.webp?fit=max&auto=format&n=lZhc_tO8u1u_bL0Q&q=85&s=e0a29bba3d2126e9149d978d008e2a62" alt="Item code shown on a stock item" width="1920" height="1080" data-path="images/stock-item-general-tab.webp" />
</Frame>

## Definition

<Snippet file="definitions/stock-code-definition.mdx" />

A **stock code** (also called an **item code**) is a tenant-unique string that identifies a single Stock Item. A Stock Item carries a `codes` array — it can have **one or many** codes attached, which is how a single physical item supports multiple scanning workflows (an internal asset code, a printed barcode, a manufacturer serial number) at the same time.

<Info>
  **The Analogy:** A stock code is like a Social Security Number for an item — it follows the physical object through its entire lifecycle and is how every other record in TWICE refers back to it.
</Info>

<Tip>
  **Multiple codes per item.** TWICE's `codes` field is an array. You can attach the manufacturer's serial number, a printed asset tag, and an internal code to the same Stock Item and scan any of them to find it.
</Tip>

## Stock Code vs SKU Code

These are different identifiers at different levels.

|             | Stock Code (item code)       | SKU Code                |
| ----------- | ---------------------------- | ----------------------- |
| Belongs to  | One Stock Item               | One SKU                 |
| Cardinality | 1 to N per item              | 1 per SKU               |
| Identifies  | A physical unit              | A product type          |
| API field   | `codes` on `Article`         | `code` on `Sku`         |
| Uniqueness  | Per tenant                   | Per tenant              |
| Example     | `B-1`, `SN12345`, `LF93HXB1` | `BIK-S`, `SKI-ATOM-170` |

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 for:

* **Unique identification** — referencing specific items in orders, reports, and operations.
* **Barcode and QR scanning** — physical labels link directly to the digital record.
* **Bulk fulfillment workflows** — scan items in and out at pickup and return.
* **Data integrity** — the uniqueness constraint prevents duplicate records.
* **API operations** — programmatically interact with specific Stock Items.
* **Audit trails** — order history and event logs reference the codes used at the time.

## Key Properties

| Property                | Type               | Description                                                                                   |
| ----------------------- | ------------------ | --------------------------------------------------------------------------------------------- |
| `codes`                 | string\[]          | Array of codes attached to one Stock Item. Each code must be unique within the tenant.        |
| Uniqueness scope        | Per tenant         | A code can be reused across different tenants but not within yours.                           |
| Auto-generation         | Yes (when omitted) | If you create an article without supplying `codes`, TWICE generates an 8-character ID.        |
| Editable after creation | Yes                | Codes can be added or removed. Identifier changes are logged as `identifiers_changed` events. |
| Required at creation    | No                 | If no code is provided, one is generated.                                                     |

## System-generated vs custom codes

You have three ways to set codes:

### Auto-generated

Omit `codes` when creating the article. TWICE generates an 8-character random ID (e.g. `LF93HXB1`). Good for quick onboarding when you do not care about specific values.

### Manual entry

Provide `codes` on create or update. Use any string format that fits your operation — short asset tags (`B-1`), serial numbers (`SN-2024-00123`), or location-prefixed codes (`HEL-BIK-001`). Validate before save with `POST /articles/validate-code` or batch with `POST /articles/validate-codes`.

### Bulk register with pattern

In the admin **Register stock items** dialog you can auto-generate a sequence (`B-1`, `B-2`, ..., `B-N`) when creating multiple units at once. This is the most common workflow for receiving a new shipment of identical units.

## Multiple codes per item

A single Stock Item can have multiple values in its `codes` array. This is intentional and supports real-world scanning workflows:

```json theme={null}
{
  "id": "art_xyz789",
  "name": "Atomic Race Ski 170cm",
  "codes": ["SKI-001", "SN240501234", "9783161484100"]
}
```

* `SKI-001` — internal asset tag printed on a sticker.
* `SN240501234` — manufacturer serial number printed on the ski.
* `9783161484100` — barcode on the original packaging.

Scanning **any** of these resolves to the same Stock Item. All three are kept in sync, so removing or replacing one does not break the others.

## Code format rules

* **Type:** string. No length limit enforced beyond the auto-generated default of 8.
* **Characters:** any printable characters. Most operators stick to alphanumerics, hyphens, and underscores so codes survive label printers and barcode scanners.
* **Uniqueness:** per tenant. Validated on create and update.
* **Case sensitivity:** codes are stored case-sensitively but most scanning workflows treat them as case-insensitive — pick one casing convention and stick to it.
* **Whitespace:** trim leading and trailing whitespace before saving. Embedded spaces work but make scanning fragile.

Good patterns:

| Pattern           | Example           | Use case                  |
| ----------------- | ----------------- | ------------------------- |
| Pure sequence     | `B-1`, `B-2`, ... | Quick onboarding          |
| SKU-prefixed      | `BIK-S-001`       | Easy to read at a glance  |
| Location-prefixed | `HEL-BIK-001`     | Multi-location operations |
| Year-prefixed     | `2025-BIK-001`    | Track purchase cohort     |
| Serial number     | `SN12345`         | Manufacturer-issued       |

## QR codes and barcode scanning

Stock codes are designed to be encoded onto physical labels. Common workflows:

* **Print on receive.** When new inventory arrives, register Stock Items with auto-generated or manual codes, then print labels straight from the admin.
* **Scan on pickup.** Operators scan an item's code when assigning it to a rental order — TWICE validates the code, finds the item, and attaches it to the order line.
* **Scan on return.** The same scan flow runs in reverse to mark items as returned and flip state from **Out** to **In**.
* **Scan for lookup.** Quick search via the admin: scan a code and jump straight to the item detail.

Because `codes` is an array, an item that has both an internal asset tag and a manufacturer barcode can be scanned on either label. Operators do not need to know which one they are looking at.

## 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

```mermaid theme={null}
flowchart LR
    SKU["SKU<br/>code: BIK-S"]
    Article1["Stock Item<br/>codes: B-1, SN001"]
    Article2["Stock Item<br/>codes: B-2, SN002"]
    Article3["Stock Item<br/>codes: B-3"]
    Label1["Label B-1"]
    Label2["Barcode SN001"]
    SKU --> Article1
    SKU --> Article2
    SKU --> Article3
    Label1 -.->|scans to| Article1
    Label2 -.->|scans to| Article1
```

## Lifecycle

<Steps>
  <Step title="Creation">
    Codes are assigned on Stock Item creation.

    <AccordionGroup>
      <Accordion title="How are codes generated?">
        If you submit `codes: ["..."]` they are used as-is. If you omit `codes`, TWICE generates an 8-character random code. The **Register stock items** bulk dialog can also generate a sequence.
      </Accordion>

      <Accordion title="Can I validate before creating?">
        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`).
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Usage">
    Codes are the everyday handle on a Stock Item.

    <AccordionGroup>
      <Accordion title="Where do codes appear?">
        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.
      </Accordion>

      <Accordion title="Can I search by code?">
        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.
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Modification">
    Codes can be added, removed, or replaced.

    <AccordionGroup>
      <Accordion title="How do I add a code?">
        Edit the item and append to the `codes` array, or `PUT /articles/:id` with the new full array. The change is logged as an `identifiers_changed` event with the previous and new arrays.
      </Accordion>

      <Accordion title="Can I change a code?">
        Yes — replace the array with the new value. The old code is detached and immediately becomes available for use on another item.
      </Accordion>

      <Accordion title="What happens to historical references?">
        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.
      </Accordion>
    </AccordionGroup>
  </Step>
</Steps>

## FAQs

<AccordionGroup>
  <Accordion title="Can I change a stock code after creation?">
    Yes. Codes are not immutable — you can add, remove, or replace them 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.
  </Accordion>

  <Accordion title="What's the difference between stock code and item code?">
    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.
  </Accordion>

  <Accordion title="Can two items have the same code?">
    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.
  </Accordion>

  <Accordion title="Can one item have multiple codes?">
    Yes. The `codes` field is an array. You can attach an internal code, a manufacturer serial number, and a packaging barcode to the same Stock Item — scanning any of them resolves to that item.
  </Accordion>

  <Accordion title="What format should I use?">
    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.
  </Accordion>

  <Accordion title="Is the uniqueness global or per location?">
    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`.
  </Accordion>
</AccordionGroup>

## Developer Reference

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

<Card title="API: Articles" icon="code" href="https://server.twicecommerce.com/api/internal">
  Open the endpoint in the API reference.
</Card>

## Related Concepts

<CardGroup cols={2}>
  <Card title="Stock Items" icon="box" href="/docs/concepts/inventory/stock-items">
    The records that codes identify
  </Card>

  <Card title="SKUs" icon="layer-group" href="/docs/concepts/inventory/skus">
    SKU code vs item code
  </Card>

  <Card title="Inventory Tracking" icon="boxes-stacked" href="/docs/concepts/inventory/inventory-tracking">
    Codes behave differently for serialized vs pooled inventory
  </Card>
</CardGroup>