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 — there is 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.

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-by-legacy-sku?legacyItemSku=PART0037

{
  "productReference": "Product_4j8k2m5n7p9q1r3s6t8v0w2x4y"
}

Step 2: Use Product References for Orders

In V2, orders use productReference instead of item_sku:

{
  "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.