Product APIs (v2)

The Product (also called Inventory) APIs let you create, retrieve, update, and manage product data. Use these APIs to define your product catalogue, define attributes, organise brands and categories, and manage SKUs across organisation units (OUs).

What you can do

You can use the Product APIs to:

• Create, read, and update product entities such as brands, categories, attributes, attribute values, and SKUs
• Search across products, brands, categories, attributes, and SKUs using prefix-based queries
• Build and retrieve hierarchies for brands and categories, including parent–child relationships
• Support for bulk create and update operations using DIY template
• Scope data by organisation unit (OU) where OU support is enabled
• Create, update, retrieve, and manage labels and label assignments to tag and organise entities such as customers, products, and stores

Search behaviour

Search across Product APIs uses starts with search on code. Each API documents its supported search parameters, precedence rules, and warnings to avoid ambiguity.

Hierarchy model

The Product APIs support hierarchical structures for:

• Categories (parent–child category trees)
• Brands (parent and child brands)

Hierarchy depth and child limits are controlled through configuration and are documented explicitly in the relevant APIs.

Organisation unit (OU) support

Product entities can be scoped at the organisation level or OU level.

Before using OU-scoped product APIs, you must:

1. Mark the concept as OU-enabled
2. Enable OU-level product and inventory configurations. To enable OU support for product entities, you need to create a JIRA ticket and enable the config CONF_OU_LEVEL_PRODUCTS_ENABLED. For more information, see Configuring Organisation Unit (OU) support for product entities.

Both steps are required. If the configuration is incomplete, the APIs return warnings or conflicts. Each API clearly documents OU behaviour, default scope, and conflict scenarios.

Bulk operations and integrations

All core product entities support bulk create and update operations.

You can:

• Submit batch requests through APIs
• Ingest large datasets using DYI templates
• Create complete hierarchies (parent and child entities) in a single request

Batch size limits, hierarchy limits, and default behaviours are documented per API.

Labels

Static labels are metadata tags that can be attached to entities such as customers, products, and stores to classify and organise them. Labels are scoped to an entity type (CUSTOMER, PRODUCT, or STORE) and must be unique by name within the same entity type and organisation.

Each label supports one of three expiry configurations:

Label operations support batch requests of up to 10 labels per request. If some labels in a batch succeed and others fail, the API returns HTTP 207 Multi-Status with successes in data and failures in errors.

Label assignments

A label assignment links a label to a specific entity — for example, a product tagged "Flash-Sale" or a customer tagged "VIP". All assignment operations use the /v2/labels/assignments endpoint.

Each entity is capped at 200 active label assignments. When you remove an assignment, the entity is untagged immediately — downstream features such as promotions or campaigns that filter by that label will no longer include the entity.

Auto-creation of labels on assignment. If you supply both labelName and labelExternalId when creating an assignment and no label with that combination exists, the API creates a new label with no expiry before creating the assignment. Both fields must be provided together for auto-creation to trigger.

QuickStart: set up products using the Product APIs

Use this sequence when onboarding a new catalogue or integrating for the first time. Follow the order to avoid dependency and validation errors.

Step 1: Create brands

Create parent and child brands first. SKUs and categories reference brand codes and require them to exist.

Step 2: Create categories

Create product categories and category hierarchies.

Step 3: Create product attributes

Define custom attributes such as material, size, or fit.

Step 4: Create attribute values

Create allowed values for attributes that require controlled inputs.

Step 5: Create SKUs

Create SKUs only after brands, categories, and attributes exist.

Step 6: Retrieve and verify data

Use GET and search APIs to validate the setup.