Products

The products endpoints expose full CRUD plus publish/unpublish, bulk operations, and export over a tenant's catalog.

Endpoints

GET/api/b2b/pim/productsauth: session

GET/api/b2b/pim/products/:entity_codeauth: session

POST/api/b2b/pim/productsauth: session

PATCH/api/b2b/pim/products/:entity_codeauth: session

DELETE/api/b2b/pim/products/:entity_codeauth: session

POST/api/b2b/pim/products/:entity_code/publishauth: session

POST/api/b2b/pim/products/:entity_code/unpublishauth: session

POST/api/b2b/pim/products/bulk-publishauth: session

POST/api/b2b/pim/products/bulk-updateauth: session

POST/api/b2b/pim/products/exportauth: session

List products

Returns a paginated list of products, filtered and sorted by query params.

Query parameters

Field	Type	Required	Description
`page`	`integer`	Optional	1-indexed page number.(default: `1`)
`limit`	`integer`	Optional	Page size, max 100.(default: `50`)
`search`	`string`	Optional	Free-text search across name, SKU, and description.
`status`	`'draft' \| 'published' \| 'archived'`	Optional	Filter by publish state.
`product_kind`	`'simple' \| 'parent' \| 'variant'`	Optional	Filter by product topology.
`sort`	`string`	Optional	Sort expression, e.g. 'name:asc' or 'updated_at:desc'.
`brand`	`string`	Optional	Filter by brand slug.
`category`	`string`	Optional	Filter by category slug (matches the category and its descendants).
`product_type`	`string`	Optional	Filter by product-type slug.
`sku`	`string`	Optional	Exact or partial SKU match — see sku_match.
`sku_match`	`'exact' \| 'prefix' \| 'contains'`	Optional	SKU match strategy.(default: `'exact'`)
`price_min`	`number`	Optional	Inclusive lower bound on list price.
`price_max`	`number`	Optional	Inclusive upper bound on list price.

Example

GET /api/b2b/pim/products?status=published&limit=2

{
"products": [
  {
    "entity_code": "SKU-0001",
    "name": { "en": "Brass ball valve 1/2\"" },
    "status": "published",
    "brand": { "code": "acme", "name": "Acme" },
    "price": { "list": 12.5, "currency": "EUR" },
    "created_at": "2026-01-14T09:22:10.000Z",
    "updated_at": "2026-03-02T15:04:01.000Z"
  },
  { "entity_code": "SKU-0002", "...": "..." }
],
"pagination": { "page": 1, "limit": 2, "total": 234, "pages": 117 }
}

Get a single product

GET/api/b2b/pim/products/:entity_codeauth: session

Returns the full product document, including all attribute groups, media references, and channel overrides.

Create a product

POST/api/b2b/pim/productsauth: session

Body

Field	Type	Required	Description
`entity_code`	`string`	Required	Stable tenant-scoped identifier. Immutable after creation.
`name`	`MultiLangString`	Required	Localized display name, e.g. { en: 'Hose', it: 'Tubo' }.
`product_kind`	`'simple' \| 'parent' \| 'variant'`	Required	Product topology.
`parent_sku`	`string`	Optional	Required when product_kind is 'variant'.
`brand`	`string`	Optional	Brand slug.
`status`	`'draft' \| 'published' \| 'archived'`	Optional	Initial publish state.(default: `'draft'`)

Update a product

PATCH/api/b2b/pim/products/:entity_codeauth: session

Partial update — only the fields you send are touched. The server merges deeply for nested objects (e.g. attributes, channel_overrides) and replaces arrays whole.

Updatable field groups

Basic: name, description, status, brand, categories, tags.
Associations: parent_sku, variants, collections.
Attributes: typed attributes.<code> values driven by the product type.
Pricing: price, tiered_prices, cost, msrp.
Media: images, videos, documents (as ordered lists of CDN refs).
Channels: per-channel overrides for marketplace and storefront.

Publish / unpublish

POST/api/b2b/pim/products/:entity_code/publishauth: session

POST/api/b2b/pim/products/:entity_code/unpublishauth: session

Publishing flips status to published and enqueues a search-index update job. Unpublishing reverses both.

Bulk operations

POST/api/b2b/pim/products/bulk-publishauth: session

POST/api/b2b/pim/products/bulk-updateauth: session

POST/api/b2b/pim/products/exportauth: session

Bulk endpoints accept either an explicit array of entity_codes or a filter matching the list-endpoint query params. Every bulk call returns a job_id you can poll via Activity.

POST /api/b2b/pim/products/bulk-publish

{
"filter": { "status": "draft", "brand": "acme" }
}

// Response
{
"success": true,
"job_id": "pim-bulk-publish-01H7X..."
}

Errors

Common error statuses

Field	Type	Required	Description
`400`	`ValidationError`	Optional	Body failed schema validation.
`401`	`Unauthenticated`	Optional	Missing or invalid credential.
`403`	`Forbidden`	Optional	Authenticated, but missing the required scope.
`404`	`NotFound`	Optional	No product with that entity_code for this tenant.
`409`	`Conflict`	Optional	entity_code already exists on create.
`422`	`BusinessRule`	Optional	Valid payload, but rejected by a business rule (e.g. publishing a product without required attributes).