# Items, Products, and SKUs

Canonical URL: https://api-docs.test-printeers.com/guides/items-products-and-skus

Understand how physical stock items relate to orderable products, how SKUs work, and how to migrate from SKU-based to reference-based integrations.

## V1 "Items" Are V2 "Products" and "Items"

In V1, the term **item** covers both the orderable catalog entry and the physical stock unit in the warehouse, with no distinction. In V2, these concepts are split: the orderable catalog entry is called a **product**, and the physical stock unit is called an **item**. So a V1 "item" maps to both a V2 "product" and a V2 "item".

When V1 refers to an "item" with an "item SKU" (e.g. in `POST /order`, `GET /stock`, or `POST /quote`), it is talking about the same orderable catalog entry that V2 calls a "product". V2 items (physical warehouse stock) are only relevant if you store your own stock at Printeers (e.g. custom packaging or pre-purchased components). For public products where Printeers handles purchasing, items are not visible. You only interact with **products**.

If you do store your own stock, the V2 `GET /items` endpoint returns your warehouse items. Each item has its own `reference` (`Item_...`) and `sku` (e.g. `PART0037`), along with `logicalQuantity`, `physicalQuantity`, and a list of `products` linked to it. Note that the item SKU (`PART0037`) is the warehouse identifier. It is not the same as the suffixed legacy item SKUs (`PART0037P001`) that identify individual products.

```
V1 "item" (SKU: PART0037)  ═══  V2 "product" (Product_4j8k...)
                                       │
                                       └── linked to warehouse item PART0037
```

Multiple products can share the same warehouse item. For example, a matte-printed and a glossy-printed version of the same Luggage Tag are different products (different print techniques, different productgroups) but both use the same physical blank from the warehouse.

```
Warehouse item: PART0037 (Luggage Tag)
├── Product: Luggage Tag (matte print)   legacyItemSKU: PART0037
└── Product: Luggage Tag (glossy print)  legacyItemSKU: PART0037P001
```

## Product References vs SKUs

The V2 API identifies products by **reference**: a unique, opaque identifier like `Product_4j8k2m5n7p9q1r3s6t8v0w2x4y`. References are stable and globally unique.

The V1 API identifies products by **SKU** (e.g. `PART0037`). These SKUs are carried forward in V2 as the `legacyItemSKU` field on products, allowing you to match V1 SKUs to V2 product references during migration.

For products created before 2026-03-22, the legacy item SKU is identical to the warehouse item's SKU (e.g. `PART0037`). Since 2026-03-22, new products receive a suffixed legacy item SKU (e.g. `PART0037P001`) to keep them unique across products that share the same warehouse item.

| Concept | V1 Item | V2 Product | V2 Item |
|---------|----|----|----|
| Orderable catalog entry | ✓ | ✓ | × |
| Physical warehouse stock | ✓ | × | ✓ |
| SKU (`PART0037`, `PART0037P001`) | `sku` | `legacyItemSKU` | × |
| V2 Item-only SKU (`PART0037`) | × | × | `sku` |
| Product Reference | `v2_product_reference` | `productReference` | × |
| Item Reference | × | × | `itemReference` |

## Backward Compatibility for V1

The V1 API continues to work as before. All V1 endpoints accept and return SKUs. Existing integrations do not need any changes.

Remember that V1 calls products "items". The `item_sku` field in V1 is the same value as `legacyItemSKU` in V2:

- **`GET /stock`**: Returns products (called "items" in V1) with their `sku` field.
- **`POST /quote`**: Accepts `item_sku` to look up product pricing.
- **`POST /order`**: Accepts `item_sku` in orderlines to identify the product.
- **`GET /order/{id}`**: Returns `item_sku` on each orderline.

Existing products keep their original SKU values. If you create orders using SKUs you already have, they continue to work without modification.

## Migrating from V1 to V2

When migrating to V2, replace SKU-based product lookups with product references.

### Step 1: Look Up Product References

Use the V2 lookup endpoint to translate a legacy SKU to a product reference:

```
GET /v2/utilities/lookup-product-reference-by-legacy-sku?legacyItemSku=PART0037
```

```json
{
  "productReference": "Product_4j8k2m5n7p9q1r3s6t8v0w2x4y"
}
```

### Step 2: Use Product References for Orders

In V2, orders use `productReference` instead of `item_sku`:

```json
{
  "order": {
    "storeReference": "Store_9jmn3dewwvy13rv12k7aannqzy",
    "shippingKind": "dropship",
    "dropshipAddress": { "..." : "..." },
    "orderlines": [
      {
        "productReference": "Product_4j8k2m5n7p9q1r3s6t8v0w2x4y",
        "imageReference": "Image_pdcptbw3k48sv03wy338bb8jzm",
        "quantity": 1
      }
    ]
  }
}
```

### Step 3: Update Your Product Catalog

Instead of storing SKUs, store product references from the V2 `GET /products` endpoint. Each product in the response includes both `reference` (the product reference) and `legacyItemSKU` (the V1 SKU), so you can match them to your existing SKU-based records during migration.

## Deprecation Timeline

The legacy SKU lookup endpoint and the `legacySku` field on orderlines are provided to ease the V1-to-V2 transition. They will be removed in V3. We recommend migrating to product references as soon as practical.