Skip to content

Product API V2 (New) ​

The Product V2 API is the next generation of our product management architecture. It is designed to be flexible, scalable, and category-agnostic.

Unlike the classic V1 API, which had hardcoded fields for "RAM," "Storage," and "Size," V2 uses a Generic Attribute System. This means you can define any property you need (like "Material," "Voltage," or "Inseam") without being limited by a fixed schema.

Important — Inventory & Warehouse Required

Product V2 uses the Inventory system for all stock management. Stock levels are no longer stored directly on the product or SKU — they live in dedicated inventory records tied to a warehouse.

  • When you create a V2 product, inventory records are automatically created in your default warehouse. You do not need to call the inventory API manually.
  • If no warehouse exists yet, the system creates a default one ("Main Warehouse") for you automatically.
  • BUNDLE products are excluded — bundles have no inventory of their own; stock is tracked at the component product level.

See the Warehouse and Inventory documentation to understand how to query stock levels, adjust quantities, and set up reorder alerts.

Key Concepts ​

1. Product Types ​

Every V2 product follows one of these four structures:

  • SIMPLE: A standard product with one price and one stock level (e.g., a specific book).
  • VARIABLE: A product with multiple options grouped together (e.g., a Shirt available in different Colors and Sizes).
  • DIGITAL: A non-physical product like a software license or an e-book.
  • BUNDLE: A package deal composed of multiple existing products.

2. Attributes ​

Attributes are the building blocks of your product details. They are simple key-value pairs.

  • V1 (Old): Used ramSize: "8GB".
  • V2 (New): Uses attributes: { "RAM": "8GB" }.

3. Variant Groups & SKUs ​

For VARIABLE products, we use a two-tier hierarchy:

  • Variant Group: Groups options by a physical characteristic (e.g., "Color: Midnight Blue").
  • SKU (Stock Keeping Unit): The actual purchasable item with its own price and stock (e.g., the "Large" size of the "Midnight Blue" shirt).

Why use V2? ​

  • No Limits: Add any custom data you want.
  • Better Organization: Group variations logically rather than flattening them.
  • Future Proof: Designed to support complex retail workflows (Bundles, Digital goods).

Next Steps ​

Build with joy