API docs by Redocly

4klyft API (1.0.0)

Download OpenAPI specification:

4klyft API Support: support@4klyft.com License: Proprietary

Logistics operations API for the 4klyft platform.

Overview

This API provides comprehensive endpoints for managing:

  • Routes & Execution: Create, manage, and execute delivery routes
  • Shipments & Loads: Track shipments from pickup to delivery
  • Fleet Management: Manage carriers, vehicles, and drivers
  • Proof of Delivery: Capture signatures, photos, and delivery confirmations
  • Settings: Configure system-wide and tenant-specific settings
  • Webhooks: Subscribe to real-time event notifications
  • Analytics: Access delivery performance metrics and reports

Authentication

All API endpoints (except /api/docs and /api/v1/iam/auth/*) require JWT Bearer token authentication. Include the token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Rate Limiting

API requests are rate-limited to ensure fair usage. Standard limits are:

  • 1000 requests per minute for read operations
  • 100 requests per minute for write operations

Error Handling

The API uses RFC 7807 Problem Details for error responses.

Catalog - Assets

The usage index for one Asset: how many owners link it, and which. Warn-only — Phase 2 exposes usage but does NOT block retire.

List catalog media assets

List catalog media assets

Authorizations:
Bearer
query Parameters
kind
string
Enum: "image" "video" "document"

Filter by media kind

status
string
Enum: "active" "retired"

Filter by status

search
string

Search by title

page
integer >= 1
Default: 1

Page number for pagination

itemsPerPage
integer [ 1 .. 200 ]
Default: 50

Number of items per page

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": []
}

Register a catalog media asset

Registers a reusable asset for a file already stored in a drive (drive:// reference).

Authorizations:
Bearer
Request Body schema:
required

The new CatalogAsset resource

kind
required
string
Enum: "image" "video" "document"
storageUri
required
string^(drive://[^/]+/.+)$
title
required
string [ 1 .. 255 ] characters
defaultAltText
string or null <= 1000 characters
mimeType
string or null <= 128 characters
folderId
string or null <uuid>
https://schema.org/identifier

Responses

Request samples

Content type
{
  • "kind": "image",
  • "storageUri": "string",
  • "title": "string",
  • "defaultAltText": "string",
  • "mimeType": "string",
  • "folderId": "5b6379a4-2a6c-4085-b184-45838a3b8e7e"
}

Response samples

Content type
{}

Report which owners link a catalog asset

Report which owners link a catalog asset

Authorizations:
Bearer
path Parameters
assetId
required
string

CatalogAssetUsage identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "assetId": "string",
  • "usageCount": 0,
  • "references": [
    ]
}

Get a catalog media asset

Get a catalog media asset

Authorizations:
Bearer
path Parameters
id
required
string

CatalogAsset identifier

Responses

Response samples

Content type
{}

Retitle a catalog media asset

Retitle a catalog media asset

Authorizations:
Bearer
path Parameters
id
required
string

CatalogAsset identifier

Request Body schema: application/merge-patch+json
required

The updated CatalogAsset resource

title
string [ 1 .. 255 ] characters

Responses

Request samples

Content type
application/merge-patch+json
{
  • "title": "string"
}

Response samples

Content type
{}

Set or clear a catalog asset default alt text

A null defaultAltText clears it.

Authorizations:
Bearer
path Parameters
id
required
string

CatalogAsset identifier

Request Body schema:
required

The new CatalogAsset resource

defaultAltText
string or null <= 1000 characters

Responses

Request samples

Content type
{
  • "defaultAltText": "string"
}

Response samples

Content type
{}

File a catalog media asset into a folder

A null folderId unfiles the asset (moves it to the library root).

Authorizations:
Bearer
path Parameters
id
required
string

CatalogAsset identifier

Request Body schema:
required

The new CatalogAsset resource

folderId
string or null <uuid>
https://schema.org/identifier

Responses

Request samples

Content type
{
  • "folderId": "5b6379a4-2a6c-4085-b184-45838a3b8e7e"
}

Response samples

Content type
{}

Restore a retired catalog media asset

Restore a retired catalog media asset

Authorizations:
Bearer
path Parameters
id
required
string

CatalogAsset identifier

Responses

Response samples

Content type
{}

Retire a catalog media asset

Retire a catalog media asset

Authorizations:
Bearer
path Parameters
id
required
string

CatalogAsset identifier

Responses

Response samples

Content type
{}

Catalog - Assortments

Represents a catalog assortment — a channel-scoped subset of the catalog (design assortment-scoping-and-channel-links.md). Curated members and a dynamic ruleMatch + ruleClauses predicate may BOTH be present; the live product membership is their union, resolved on demand by the AssortmentResolver (not materialised on this resource). Kept deliberately separate from the merchandising Collection.

List catalog assortments

List catalog assortments

Authorizations:
Bearer
query Parameters
status
string
Enum: "active" "archived"

Filter by status

search
string

Search by name or code

page
integer >= 1
Default: 1

Page number for pagination

itemsPerPage
integer [ 1 .. 100 ]
Default: 50

Number of items per page

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Create a catalog assortment

Create a catalog assortment

Authorizations:
Bearer
Request Body schema:
required

The new Assortment resource

name
required
string [ 1 .. 255 ] characters
code
string or null <= 64 characters
description
string or null

Responses

Request samples

Content type
{
  • "name": "string",
  • "code": "string",
  • "description": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Pharmaceuticals",
  • "code": "pharmaceuticals",
  • "description": "string",
  • "status": "active",
  • "membershipType": "curated",
  • "curatedCount": 0,
  • "ruleDefined": false,
  • "ruleMatch": "all",
  • "members": [
    ],
  • "ruleClauses": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Get a catalog assortment

Get a catalog assortment

Authorizations:
Bearer
path Parameters
id
required
string

Assortment identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Pharmaceuticals",
  • "code": "pharmaceuticals",
  • "description": "string",
  • "status": "active",
  • "membershipType": "curated",
  • "curatedCount": 0,
  • "ruleDefined": false,
  • "ruleMatch": "all",
  • "members": [
    ],
  • "ruleClauses": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Rename a catalog assortment

Rename a catalog assortment

Authorizations:
Bearer
path Parameters
id
required
string

Assortment identifier

Request Body schema: application/merge-patch+json
required

The updated Assortment resource

name
string [ 1 .. 255 ] characters

Responses

Request samples

Content type
application/merge-patch+json
{
  • "name": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Pharmaceuticals",
  • "code": "pharmaceuticals",
  • "description": "string",
  • "status": "active",
  • "membershipType": "curated",
  • "curatedCount": 0,
  • "ruleDefined": false,
  • "ruleMatch": "all",
  • "members": [
    ],
  • "ruleClauses": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Archive a catalog assortment

Archive a catalog assortment

Authorizations:
Bearer
path Parameters
id
required
string

Assortment identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Pharmaceuticals",
  • "code": "pharmaceuticals",
  • "description": "string",
  • "status": "active",
  • "membershipType": "curated",
  • "curatedCount": 0,
  • "ruleDefined": false,
  • "ruleMatch": "all",
  • "members": [
    ],
  • "ruleClauses": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Update a catalog assortment description

Update a catalog assortment description

Authorizations:
Bearer
path Parameters
id
required
string

Assortment identifier

Request Body schema:
required

The new Assortment resource

description
string or null

Responses

Request samples

Content type
{
  • "description": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Pharmaceuticals",
  • "code": "pharmaceuticals",
  • "description": "string",
  • "status": "active",
  • "membershipType": "curated",
  • "curatedCount": 0,
  • "ruleDefined": false,
  • "ruleMatch": "all",
  • "members": [
    ],
  • "ruleClauses": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Curate a product into an assortment

Curate a product into an assortment

Authorizations:
Bearer
path Parameters
id
required
string

Assortment identifier

Request Body schema:
required

The new Assortment resource

productId
required
string

Responses

Request samples

Content type
{
  • "productId": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Pharmaceuticals",
  • "code": "pharmaceuticals",
  • "description": "string",
  • "status": "active",
  • "membershipType": "curated",
  • "curatedCount": 0,
  • "ruleDefined": false,
  • "ruleMatch": "all",
  • "members": [
    ],
  • "ruleClauses": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Curate a batch of products into an assortment

Add many products at once by their opaque ResourceUris. Idempotent — already-curated products are skipped.

Authorizations:
Bearer
path Parameters
id
required
string

Assortment identifier

Request Body schema:
required

The new Assortment resource

productIds
required
Array of strings

Responses

Request samples

Content type
{
  • "productIds": [
    ]
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Pharmaceuticals",
  • "code": "pharmaceuticals",
  • "description": "string",
  • "status": "active",
  • "membershipType": "curated",
  • "curatedCount": 0,
  • "ruleDefined": false,
  • "ruleMatch": "all",
  • "members": [
    ],
  • "ruleClauses": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Remove a curated product from an assortment

Remove a curated product from an assortment

Authorizations:
Bearer
path Parameters
id
required
string

Assortment identifier

Request Body schema:
required

The new Assortment resource

productId
required
string

Responses

Request samples

Content type
{
  • "productId": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Pharmaceuticals",
  • "code": "pharmaceuticals",
  • "description": "string",
  • "status": "active",
  • "membershipType": "curated",
  • "curatedCount": 0,
  • "ruleDefined": false,
  • "ruleMatch": "all",
  • "members": [
    ],
  • "ruleClauses": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Reactivate a catalog assortment

Reactivate a catalog assortment

Authorizations:
Bearer
path Parameters
id
required
string

Assortment identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Pharmaceuticals",
  • "code": "pharmaceuticals",
  • "description": "string",
  • "status": "active",
  • "membershipType": "curated",
  • "curatedCount": 0,
  • "ruleDefined": false,
  • "ruleMatch": "all",
  • "members": [
    ],
  • "ruleClauses": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Set the dynamic rule expression of an assortment

Store the typed predicate. Composes with curated members — membership is the union of both.

Authorizations:
Bearer
path Parameters
id
required
string

Assortment identifier

Request Body schema:
required

The new Assortment resource

match
required
string
Enum: "all" "any"
required
Array of objects

Responses

Request samples

Content type
{
  • "match": "all",
  • "clauses": [
    ]
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Pharmaceuticals",
  • "code": "pharmaceuticals",
  • "description": "string",
  • "status": "active",
  • "membershipType": "curated",
  • "curatedCount": 0,
  • "ruleDefined": false,
  • "ruleMatch": "all",
  • "members": [
    ],
  • "ruleClauses": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Clear the dynamic rule of an assortment

Clear the dynamic rule of an assortment

Authorizations:
Bearer
path Parameters
id
required
string

Assortment identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Pharmaceuticals",
  • "code": "pharmaceuticals",
  • "description": "string",
  • "status": "active",
  • "membershipType": "curated",
  • "curatedCount": 0,
  • "ruleDefined": false,
  • "ruleMatch": "all",
  • "members": [
    ],
  • "ruleClauses": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Catalog - Attribute Definitions

Represents a catalog attribute definition — a typed entry in the tenant-global attribute registry (catalog.md §4.3). A select/multiselect definition binds a first-class OptionSet (optionSetRef) as the source of its allowed values; maxSelections caps a multiselect.

List all catalog attribute definitions

Retrieve a paginated list of attribute definitions with optional filters.

Authorizations:
Bearer
query Parameters
group
string

Filter by attribute group

type
string
Enum: "text" "number" "bool" "select" "multiselect" "measurement" "rich_text" "date" "file"

Filter by attribute type

status
string
Enum: "active" "archived"

Filter by status

search
string

Search by name or code

page
integer >= 1
Default: 1

Page number for pagination

itemsPerPage
integer [ 1 .. 100 ]
Default: 20

Number of items per page

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Create a catalog attribute definition

Create a catalog attribute definition

Authorizations:
Bearer
Request Body schema:
required

The new AttributeDefinition resource

name
required
string [ 1 .. 255 ] characters
code
string or null <= 64 characters
type
required
string
Enum: "text" "number" "bool" "select" "multiselect" "measurement" "rich_text" "date" "file"
unit
string or null <= 32 characters
group
string or null <= 100 characters
isFilterable
boolean
Default: false
maxLength
integer or null > 0
scope
string
Default: "per_product"
Enum: "per_product" "per_variant"
comparable
boolean
Default: false
perLocale
boolean
Default: false
lockedToCatalog
boolean
Default: false
helpText
string or null <= 255 characters

Responses

Request samples

Content type
{
  • "name": "string",
  • "code": "string",
  • "type": "text",
  • "unit": "string",
  • "group": "string",
  • "isFilterable": false,
  • "maxLength": 0,
  • "scope": "per_product",
  • "comparable": false,
  • "perLocale": false,
  • "lockedToCatalog": false,
  • "helpText": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Colour",
  • "code": "colour",
  • "type": "text",
  • "unit": "cm",
  • "group": "Physical properties",
  • "isFilterable": true,
  • "optionSetRef": "string",
  • "maxSelections": 3,
  • "maxLength": 255,
  • "scope": "per_product",
  • "comparable": false,
  • "perLocale": false,
  • "lockedToCatalog": false,
  • "helpText": "Enter the primary colour name",
  • "status": "active",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Get a catalog attribute definition

Get a catalog attribute definition

Authorizations:
Bearer
path Parameters
id
required
string

AttributeDefinition identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Colour",
  • "code": "colour",
  • "type": "text",
  • "unit": "cm",
  • "group": "Physical properties",
  • "isFilterable": true,
  • "optionSetRef": "string",
  • "maxSelections": 3,
  • "maxLength": 255,
  • "scope": "per_product",
  • "comparable": false,
  • "perLocale": false,
  • "lockedToCatalog": false,
  • "helpText": "Enter the primary colour name",
  • "status": "active",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Update a catalog attribute definition

Update the mutable profile (name, unit, group, isFilterable, and enrichment flags). code/type are immutable.

Authorizations:
Bearer
path Parameters
id
required
string

AttributeDefinition identifier

Request Body schema: application/merge-patch+json
required

The updated AttributeDefinition resource

name
string [ 1 .. 255 ] characters
unit
string or null <= 32 characters
group
string or null <= 100 characters
isFilterable
boolean
Default: false
maxLength
integer or null > 0
scope
string
Default: "per_product"
Enum: "per_product" "per_variant"
comparable
boolean
Default: false
perLocale
boolean
Default: false
lockedToCatalog
boolean
Default: false
helpText
string or null <= 255 characters

Responses

Request samples

Content type
application/merge-patch+json
{
  • "name": "string",
  • "unit": "string",
  • "group": "string",
  • "isFilterable": false,
  • "maxLength": 0,
  • "scope": "per_product",
  • "comparable": false,
  • "perLocale": false,
  • "lockedToCatalog": false,
  • "helpText": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Colour",
  • "code": "colour",
  • "type": "text",
  • "unit": "cm",
  • "group": "Physical properties",
  • "isFilterable": true,
  • "optionSetRef": "string",
  • "maxSelections": 3,
  • "maxLength": 255,
  • "scope": "per_product",
  • "comparable": false,
  • "perLocale": false,
  • "lockedToCatalog": false,
  • "helpText": "Enter the primary colour name",
  • "status": "active",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Archive a catalog attribute definition

Archive a catalog attribute definition

Authorizations:
Bearer
path Parameters
id
required
string

AttributeDefinition identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Colour",
  • "code": "colour",
  • "type": "text",
  • "unit": "cm",
  • "group": "Physical properties",
  • "isFilterable": true,
  • "optionSetRef": "string",
  • "maxSelections": 3,
  • "maxLength": 255,
  • "scope": "per_product",
  • "comparable": false,
  • "perLocale": false,
  • "lockedToCatalog": false,
  • "helpText": "Enter the primary colour name",
  • "status": "active",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Bind a first-class OptionSet as the source of allowed values

Only valid for select/multiselect attribute definitions. maxSelections is a multiselect-only cap.

Authorizations:
Bearer
path Parameters
id
required
string

AttributeDefinition identifier

Request Body schema:
required

The new AttributeDefinition resource

optionSetId
required
string
maxSelections
integer or null > 0

Responses

Request samples

Content type
{
  • "optionSetId": "string",
  • "maxSelections": 0
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Colour",
  • "code": "colour",
  • "type": "text",
  • "unit": "cm",
  • "group": "Physical properties",
  • "isFilterable": true,
  • "optionSetRef": "string",
  • "maxSelections": 3,
  • "maxLength": 255,
  • "scope": "per_product",
  • "comparable": false,
  • "perLocale": false,
  • "lockedToCatalog": false,
  • "helpText": "Enter the primary colour name",
  • "status": "active",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Reactivate a catalog attribute definition

Reactivate a catalog attribute definition

Authorizations:
Bearer
path Parameters
id
required
string

AttributeDefinition identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Colour",
  • "code": "colour",
  • "type": "text",
  • "unit": "cm",
  • "group": "Physical properties",
  • "isFilterable": true,
  • "optionSetRef": "string",
  • "maxSelections": 3,
  • "maxLength": 255,
  • "scope": "per_product",
  • "comparable": false,
  • "perLocale": false,
  • "lockedToCatalog": false,
  • "helpText": "Enter the primary colour name",
  • "status": "active",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Catalog - Attribute Sets

Represents a catalog attribute set — a family / product-type in the tenant-global Catalog that declares which attributes apply to a Product and which of them are required (catalog.md §4.8).

List all catalog attribute sets

Retrieve a paginated list of attribute sets (families / product-types) with optional filters.

Authorizations:
Bearer
query Parameters
status
string
Enum: "active" "archived"

Filter by status

search
string

Search by name or code

page
integer >= 1
Default: 1

Page number for pagination

itemsPerPage
integer [ 1 .. 100 ]
Default: 20

Number of items per page

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Create a catalog attribute set

Create a catalog attribute set

Authorizations:
Bearer
Request Body schema:
required

The new AttributeSet resource

name
required
string [ 1 .. 255 ] characters
code
string or null <= 64 characters
description
string or null <= 2000 characters

Responses

Request samples

Content type
{
  • "name": "string",
  • "code": "string",
  • "description": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Apparel",
  • "code": "apparel",
  • "description": "Fields for apparel product types",
  • "status": "active",
  • "sections": [
    ],
  • "members": [
    ],
  • "memberCount": 0,
  • "sectionCount": 0,
  • "createdAt": "string",
  • "updatedAt": "string"
}

Get a catalog attribute set

Get a catalog attribute set

Authorizations:
Bearer
path Parameters
id
required
string

AttributeSet identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Apparel",
  • "code": "apparel",
  • "description": "Fields for apparel product types",
  • "status": "active",
  • "sections": [
    ],
  • "members": [
    ],
  • "memberCount": 0,
  • "sectionCount": 0,
  • "createdAt": "string",
  • "updatedAt": "string"
}

Rename a catalog attribute set

Update the display name. code is immutable.

Authorizations:
Bearer
path Parameters
id
required
string

AttributeSet identifier

Request Body schema: application/merge-patch+json
required

The updated AttributeSet resource

name
string [ 1 .. 255 ] characters

Responses

Request samples

Content type
application/merge-patch+json
{
  • "name": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Apparel",
  • "code": "apparel",
  • "description": "Fields for apparel product types",
  • "status": "active",
  • "sections": [
    ],
  • "members": [
    ],
  • "memberCount": 0,
  • "sectionCount": 0,
  • "createdAt": "string",
  • "updatedAt": "string"
}

Archive a catalog attribute set

Archive a catalog attribute set

Authorizations:
Bearer
path Parameters
id
required
string

AttributeSet identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Apparel",
  • "code": "apparel",
  • "description": "Fields for apparel product types",
  • "status": "active",
  • "sections": [
    ],
  • "members": [
    ],
  • "memberCount": 0,
  • "sectionCount": 0,
  • "createdAt": "string",
  • "updatedAt": "string"
}

Add an attribute to the set

Adds an AttributeDefinition as a member. The definition must exist.

Authorizations:
Bearer
path Parameters
id
required
string

AttributeSet identifier

Request Body schema:
required

The new AttributeSet resource

attributeDefinitionId
required
string
sectionId
required
string
required
boolean
Default: false

Responses

Request samples

Content type
{
  • "attributeDefinitionId": "string",
  • "sectionId": "string",
  • "required": false
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Apparel",
  • "code": "apparel",
  • "description": "Fields for apparel product types",
  • "status": "active",
  • "sections": [
    ],
  • "members": [
    ],
  • "memberCount": 0,
  • "sectionCount": 0,
  • "createdAt": "string",
  • "updatedAt": "string"
}

Reorder the set's members

Reorder the set's members

Authorizations:
Bearer
path Parameters
id
required
string

AttributeSet identifier

Request Body schema:
required

The new AttributeSet resource

sectionId
required
string
orderedAttributeDefinitionIds
required
Array of strings

Responses

Request samples

Content type
{
  • "sectionId": "string",
  • "orderedAttributeDefinitionIds": [
    ]
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Apparel",
  • "code": "apparel",
  • "description": "Fields for apparel product types",
  • "status": "active",
  • "sections": [
    ],
  • "members": [
    ],
  • "memberCount": 0,
  • "sectionCount": 0,
  • "createdAt": "string",
  • "updatedAt": "string"
}

Remove an attribute from the set

Remove an attribute from the set

Authorizations:
Bearer
path Parameters
attributeDefinitionId
required
string

The member attribute definition id to remove

id
required
string

AttributeSet identifier

Responses

Toggle a member attribute's required flag

Toggle a member attribute's required flag

Authorizations:
Bearer
path Parameters
attributeDefinitionId
required
string

The member attribute definition id

id
required
string

AttributeSet identifier

Request Body schema: application/merge-patch+json
required

The updated AttributeSet resource

required
boolean
Default: false

Responses

Request samples

Content type
application/merge-patch+json
{
  • "required": false
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Apparel",
  • "code": "apparel",
  • "description": "Fields for apparel product types",
  • "status": "active",
  • "sections": [
    ],
  • "members": [
    ],
  • "memberCount": 0,
  • "sectionCount": 0,
  • "createdAt": "string",
  • "updatedAt": "string"
}

Set a member's per-membership label override

Overrides the display label for THIS membership, superseding the definition's name. A blank label is rejected.

Authorizations:
Bearer
path Parameters
attributeDefinitionId
required
string

The member attribute definition id

id
required
string

AttributeSet identifier

Request Body schema:
required

The new AttributeSet resource

label
string
Default: ""

The display label to use for this membership

Responses

Request samples

Content type
{
  • "label": "Shade"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Apparel",
  • "code": "apparel",
  • "description": "Fields for apparel product types",
  • "status": "active",
  • "sections": [
    ],
  • "members": [
    ],
  • "memberCount": 0,
  • "sectionCount": 0,
  • "createdAt": "string",
  • "updatedAt": "string"
}

Clear a member's label override

Reverts the member to inheriting the definition's name as its display label.

Authorizations:
Bearer
path Parameters
attributeDefinitionId
required
string

The member attribute definition id

id
required
string

AttributeSet identifier

Responses

Set a member's per-membership OptionSet override

Binds an OptionSet (and optional multiselect cap) for THIS membership, superseding the definition default. Only valid on select/multiselect attributes.

Authorizations:
Bearer
path Parameters
attributeDefinitionId
required
string

The member attribute definition id

id
required
string

AttributeSet identifier

Request Body schema:
required

The new AttributeSet resource

optionSetRef
string
Default: ""

The OptionSet id to bind for this membership

maxSelections
integer or null

Optional multiselect selection cap (>= 1); null caps nothing

Responses

Request samples

Content type
{
  • "optionSetRef": "01912345-6789-7abc-def0-123456789abc",
  • "maxSelections": 0
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Apparel",
  • "code": "apparel",
  • "description": "Fields for apparel product types",
  • "status": "active",
  • "sections": [
    ],
  • "members": [
    ],
  • "memberCount": 0,
  • "sectionCount": 0,
  • "createdAt": "string",
  • "updatedAt": "string"
}

Clear a member's OptionSet override

Reverts the member to inheriting the definition's default binding.

Authorizations:
Bearer
path Parameters
attributeDefinitionId
required
string

The member attribute definition id

id
required
string

AttributeSet identifier

Responses

Move a member to another section

Move a member to another section

Authorizations:
Bearer
path Parameters
attributeDefinitionId
required
string

The member attribute definition id

id
required
string

AttributeSet identifier

Request Body schema:
required

The new AttributeSet resource

sectionId
required
string

Responses

Request samples

Content type
{
  • "sectionId": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Apparel",
  • "code": "apparel",
  • "description": "Fields for apparel product types",
  • "status": "active",
  • "sections": [
    ],
  • "members": [
    ],
  • "memberCount": 0,
  • "sectionCount": 0,
  • "createdAt": "string",
  • "updatedAt": "string"
}

Update the attribute set description

A null description clears the hint.

Authorizations:
Bearer
path Parameters
id
required
string

AttributeSet identifier

Request Body schema:
required

The new AttributeSet resource

description
string or null <= 2000 characters

Responses

Request samples

Content type
{
  • "description": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Apparel",
  • "code": "apparel",
  • "description": "Fields for apparel product types",
  • "status": "active",
  • "sections": [
    ],
  • "members": [
    ],
  • "memberCount": 0,
  • "sectionCount": 0,
  • "createdAt": "string",
  • "updatedAt": "string"
}

Restore an archived catalog attribute set

Restore an archived catalog attribute set

Authorizations:
Bearer
path Parameters
id
required
string

AttributeSet identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Apparel",
  • "code": "apparel",
  • "description": "Fields for apparel product types",
  • "status": "active",
  • "sections": [
    ],
  • "members": [
    ],
  • "memberCount": 0,
  • "sectionCount": 0,
  • "createdAt": "string",
  • "updatedAt": "string"
}

Add a section (named grouping) to the set

Add a section (named grouping) to the set

Authorizations:
Bearer
path Parameters
id
required
string

AttributeSet identifier

Request Body schema:
required

The new AttributeSet resource

name
required
string [ 1 .. 255 ] characters

Responses

Request samples

Content type
{
  • "name": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Apparel",
  • "code": "apparel",
  • "description": "Fields for apparel product types",
  • "status": "active",
  • "sections": [
    ],
  • "members": [
    ],
  • "memberCount": 0,
  • "sectionCount": 0,
  • "createdAt": "string",
  • "updatedAt": "string"
}

Reorder the set's sections

Reorder the set's sections

Authorizations:
Bearer
path Parameters
id
required
string

AttributeSet identifier

Request Body schema:
required

The new AttributeSet resource

orderedSectionIds
required
Array of strings

Responses

Request samples

Content type
{
  • "orderedSectionIds": [
    ]
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Apparel",
  • "code": "apparel",
  • "description": "Fields for apparel product types",
  • "status": "active",
  • "sections": [
    ],
  • "members": [
    ],
  • "memberCount": 0,
  • "sectionCount": 0,
  • "createdAt": "string",
  • "updatedAt": "string"
}

Remove an (empty) section from the set

Remove an (empty) section from the set

Authorizations:
Bearer
path Parameters
sectionId
required
string

The section id to remove

id
required
string

AttributeSet identifier

Responses

Rename a section

Rename a section

Authorizations:
Bearer
path Parameters
sectionId
required
string

The section id

id
required
string

AttributeSet identifier

Request Body schema: application/merge-patch+json
required

The updated AttributeSet resource

name
string [ 1 .. 255 ] characters

Responses

Request samples

Content type
application/merge-patch+json
{
  • "name": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Apparel",
  • "code": "apparel",
  • "description": "Fields for apparel product types",
  • "status": "active",
  • "sections": [
    ],
  • "members": [
    ],
  • "memberCount": 0,
  • "sectionCount": 0,
  • "createdAt": "string",
  • "updatedAt": "string"
}

Catalog - Attribute Values

Represents a catalog attribute value — the assignment of an AttributeDefinition's value to a subject (a Catalog Product or Variant, referenced by opaque ResourceUri) (catalog.md §4.3).

List a subject's catalog attribute values

Retrieve all attribute values set on a Product or Variant, for the product editor.

Authorizations:
Bearer
query Parameters
subjectRef
required
string
Example: subjectRef=glacia:///catalog/products/01912345-6789-7abc-def0-123456789abc

The subject's opaque ResourceUri (a Product or Variant)

page
integer
Default: 1

The collection page number

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Set a catalog attribute value

Create or update the value of an AttributeDefinition on a subject (idempotent upsert keyed on subjectRef + attributeDefinitionId).

Authorizations:
Bearer
Request Body schema: application/json
required

Attribute value data

subjectRef
required
string
attributeDefinitionId
required
string <uuid>
value
required
string

Responses

Request samples

Content type
application/json
{
  • "subjectRef": "glacia:///catalog/products/01912345-6789-7abc-def0-123456789abc",
  • "attributeDefinitionId": "5a99bae6-70b6-4cce-a212-45b1dfb36b9c",
  • "value": "red"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "subjectRef": "glacia:///catalog/products/01912345-6789-7abc-def0-123456789abc",
  • "attributeDefinitionId": "string",
  • "value": "red",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Get a catalog attribute value

Get a catalog attribute value

Authorizations:
Bearer
path Parameters
id
required
string

AttributeValue identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "subjectRef": "glacia:///catalog/products/01912345-6789-7abc-def0-123456789abc",
  • "attributeDefinitionId": "string",
  • "value": "red",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Clear a catalog attribute value

Clear a catalog attribute value

Authorizations:
Bearer
path Parameters
id
required
string

AttributeValue identifier

Responses

Catalog - Brands

Represents a catalog brand — the tenant-global Brand identity Products may optionally reference.

List all catalog brands

Retrieve a paginated list of catalog brands with optional filters.

Authorizations:
Bearer
query Parameters
status
string
Enum: "active" "discontinued"
Example: status=active

Filter by brand status

search
string
Example: search=Acme

Search by name or code

page
integer >= 1
Default: 1
Example: page=1

Page number for pagination

itemsPerPage
integer [ 1 .. 100 ]
Default: 20
Example: itemsPerPage=20

Number of items per page

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Create a catalog brand

Create a new tenant-global catalog brand identity.

Authorizations:
Bearer
Request Body schema: application/json
required

Catalog brand creation data

name
required
string non-empty
code
string or null
description
string or null
logoRef
string or null

Responses

Request samples

Content type
application/json
{
  • "name": "Acme",
  • "code": "ACME",
  • "description": "string",
  • "logoRef": "glacia:///storage/files/01912345-6789-7abc-def0-123456789abc"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Acme",
  • "code": "ACME",
  • "description": "string",
  • "website": "https://acme.example",
  • "seo": {
    },
  • "status": "active",
  • "logoRef": "glacia:///storage/files/01912345-6789-7abc-def0-123456789abc",
  • "logoUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Get a catalog brand

Retrieve a single catalog brand by its UUID.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Brand UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Acme",
  • "code": "ACME",
  • "description": "string",
  • "website": "https://acme.example",
  • "seo": {
    },
  • "status": "active",
  • "logoRef": "glacia:///storage/files/01912345-6789-7abc-def0-123456789abc",
  • "logoUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Update a catalog brand

Update a brand's mutable profile (name, code, description, logoRef).

Authorizations:
Bearer
path Parameters
id
required
string

Brand identifier

Request Body schema: application/merge-patch+json
required

The updated Brand resource

name
string [ 1 .. 255 ] characters
code
string or null <= 64 characters
description
string or null
logoRef
string or null <= 512 characters

Responses

Request samples

Content type
application/merge-patch+json
{
  • "name": "string",
  • "code": "string",
  • "description": "string",
  • "logoRef": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Acme",
  • "code": "ACME",
  • "description": "string",
  • "website": "https://acme.example",
  • "seo": {
    },
  • "status": "active",
  • "logoRef": "glacia:///storage/files/01912345-6789-7abc-def0-123456789abc",
  • "logoUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Discontinue a catalog brand

Transition a brand to the discontinued status.

Authorizations:
Bearer
path Parameters
id
required
string

Brand identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Acme",
  • "code": "ACME",
  • "description": "string",
  • "website": "https://acme.example",
  • "seo": {
    },
  • "status": "active",
  • "logoRef": "glacia:///storage/files/01912345-6789-7abc-def0-123456789abc",
  • "logoUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Reactivate a catalog brand

Transition a discontinued brand back to the active status.

Authorizations:
Bearer
path Parameters
id
required
string

Brand identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Acme",
  • "code": "ACME",
  • "description": "string",
  • "website": "https://acme.example",
  • "seo": {
    },
  • "status": "active",
  • "logoRef": "glacia:///storage/files/01912345-6789-7abc-def0-123456789abc",
  • "logoUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Update a catalog brand's SEO content

Set the brand's meta title, meta description and URL slug. The slug must be unique per tenant among brands.

Authorizations:
Bearer
path Parameters
id
required
string

Brand identifier

Request Body schema:
required

The new Brand resource

metaTitle
string or null
metaDescription
string or null
slug
string or null

Responses

Request samples

Content type
{
  • "metaTitle": "string",
  • "metaDescription": "string",
  • "slug": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Acme",
  • "code": "ACME",
  • "description": "string",
  • "website": "https://acme.example",
  • "seo": {
    },
  • "status": "active",
  • "logoRef": "glacia:///storage/files/01912345-6789-7abc-def0-123456789abc",
  • "logoUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Update a catalog brand's website URL

Update a catalog brand's website URL

Authorizations:
Bearer
path Parameters
id
required
string

Brand identifier

Request Body schema:
required

The new Brand resource

website
string or null

Responses

Request samples

Content type
{
  • "website": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Acme",
  • "code": "ACME",
  • "description": "string",
  • "website": "https://acme.example",
  • "seo": {
    },
  • "status": "active",
  • "logoRef": "glacia:///storage/files/01912345-6789-7abc-def0-123456789abc",
  • "logoUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Catalog - Overview

A product on the Overview "needs attention" list: it is missing one or more publish-readiness dimensions (missing), which the UI renders as reason chips. A column-level heuristic — see the query service for why this is not the authoritative publication-gate verdict. Served by {@see NeedsAttentionCollectionProvider}.

List products missing key publish-readiness fields

Paginated list of products missing a Brand reference, description, primary image, or still in draft enrichment. Each row carries the exact set of missing dimensions.

Authorizations:
Bearer
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number for pagination

itemsPerPage
integer [ 1 .. 100 ]
Default: 20
Example: itemsPerPage=20

Number of items per page

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": []
}

Catalog Overview counts / facets

Tenant-scoped aggregate counts (products with per-status breakdown, variants, brands, categories, collections, tags, attributes, assets) backing the catalog Overview dashboard.

Authorizations:
Bearer

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "catalog-overview",
  • "products": {
    },
  • "variants": {
    },
  • "brands": {
    },
  • "categories": {
    },
  • "collections": {
    },
  • "tags": {
    },
  • "attributes": {
    },
  • "assets": {
    }
}

Catalog - Categories

Represents a catalog category — a node in the tenant-global taxonomy tree (catalog.md §4.1). Products are assigned to categories via the ProductCategoryAssignment resource.

List catalog categories

Retrieve categories as a flat paginated list, or the full tree ordered by path with ?tree=1.

Authorizations:
Bearer
query Parameters
tree
boolean

Return the whole tree ordered by path (depth-first)

parentId
string

Filter to the direct children of a category (empty string = roots)

status
string
Enum: "active" "archived"

Filter by status

search
string

Search by name or code

page
integer >= 1
Default: 1

Page number for pagination

itemsPerPage
integer [ 1 .. 200 ]
Default: 50

Number of items per page

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": []
}

Create a catalog category

Create a catalog category

Authorizations:
Bearer
Request Body schema:
required

The new Category resource

name
required
string [ 1 .. 255 ] characters
code
string or null <= 64 characters
parentId
string or null
position
integer >= 0
Default: 0

Responses

Request samples

Content type
{
  • "name": "string",
  • "code": "string",
  • "parentId": "string",
  • "position": 0
}

Response samples

Content type
{}

List the categories a product is assigned to

List the categories a product is assigned to

Authorizations:
Bearer
query Parameters
productId
required
string

The product's opaque ResourceUri

page
integer
Default: 1

The collection page number

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": []
}

Get a catalog category

Get a catalog category

Authorizations:
Bearer
path Parameters
id
required
string

Category identifier

Responses

Response samples

Content type
{}

Rename a catalog category

Rename a catalog category

Authorizations:
Bearer
path Parameters
id
required
string

Category identifier

Request Body schema: application/merge-patch+json
required

The updated Category resource

name
string [ 1 .. 255 ] characters

Responses

Request samples

Content type
application/merge-patch+json
{
  • "name": "string"
}

Response samples

Content type
{}

Archive a catalog category

Archive a catalog category

Authorizations:
Bearer
path Parameters
id
required
string

Category identifier

Responses

Response samples

Content type
{}

Update a catalog category's description

Update a catalog category's description

Authorizations:
Bearer
path Parameters
id
required
string

Category identifier

Request Body schema:
required

The new Category resource

description
string or null

Responses

Request samples

Content type
{
  • "description": "string"
}

Response samples

Content type
{}

Reparent a catalog category

Move the category under a new parent (newParentId null promotes it to a root). Rejected with 400 if the move would create a cycle.

Authorizations:
Bearer
path Parameters
id
required
string

Category identifier

Request Body schema:
required

The new Category resource

newParentId
string or null

Responses

Request samples

Content type
{
  • "newParentId": "string"
}

Response samples

Content type
{}

Assign a batch of products to a category

Assign many products at once by their bare ids. Idempotent — products already assigned are skipped.

Authorizations:
Bearer
path Parameters
id
required
string

Category identifier

Request Body schema:
required

The new Category resource

productIds
required
Array of strings

Responses

Request samples

Content type
{
  • "productIds": [
    ]
}

Response samples

Content type
{}

Reactivate a catalog category

Reactivate a catalog category

Authorizations:
Bearer
path Parameters
id
required
string

Category identifier

Responses

Response samples

Content type
{}

Reorder a catalog category among its siblings

Reorder a catalog category among its siblings

Authorizations:
Bearer
path Parameters
id
required
string

Category identifier

Request Body schema:
required

The new Category resource

position
integer >= 0
Default: 0

Responses

Request samples

Content type
{
  • "position": 0
}

Response samples

Content type
{}

Update a catalog category's SEO content

Set the category's meta title, meta description and URL slug. The slug must be unique per tenant among categories.

Authorizations:
Bearer
path Parameters
id
required
string

Category identifier

Request Body schema:
required

The new Category resource

metaTitle
string or null
metaDescription
string or null
slug
string or null

Responses

Request samples

Content type
{
  • "metaTitle": "string",
  • "metaDescription": "string",
  • "slug": "string"
}

Response samples

Content type
{}

Catalog - Channel Content Overrides

Represents a per-channel content override layered over base Variant content at read time (catalog.md §4.7). Keyed on the (variantRef, channelRef, field) triple; setting the same triple again UPDATES the value (idempotent upsert), NOT a 409. The base Product/Variant stays the canonical truth.

Set (upsert) a per-channel content override

Upserts the override keyed on (variantRef, channelRef, field). Setting the same triple again updates the value — no 409.

Authorizations:
Bearer
Request Body schema:
required

The new ChannelContentOverride resource

variantRef
required
string [ 1 .. 512 ] characters
channelRef
required
string [ 1 .. 512 ] characters
field
required
string
Enum: "title" "description" "short_description" "meta_title" "meta_description"
value
required
string

Responses

Request samples

Content type
{
  • "variantRef": "string",
  • "channelRef": "string",
  • "field": "title",
  • "value": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "variantRef": "01912345-6789-7abc-def0-123456789abc",
  • "channelRef": "glacia:///sales/channels/01912345-6789-7abc-def0-123456789abc",
  • "field": "title",
  • "value": "Amazon-optimised product title",
  • "createdAt": "string",
  • "updatedAt": "string"
}

List the content overrides layered over a variant

List the content overrides layered over a variant

Authorizations:
Bearer
query Parameters
variantRef
required
string

The variant's VariantId

channelRef
string

Optional channel ResourceUri filter

page
integer
Default: 1

The collection page number

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Get a channel content override

Get a channel content override

Authorizations:
Bearer
path Parameters
id
required
string

ChannelContentOverride identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "variantRef": "01912345-6789-7abc-def0-123456789abc",
  • "channelRef": "glacia:///sales/channels/01912345-6789-7abc-def0-123456789abc",
  • "field": "title",
  • "value": "Amazon-optimised product title",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Clear a channel content override

Clear a channel content override

Authorizations:
Bearer
path Parameters
id
required
string

ChannelContentOverride identifier

Responses

Catalog - Collections

Represents a catalog collection — a merchandising grouping of products (catalog.md §4.2). Curated collections expose an ordered members list; dynamic collections expose a ruleMatch + ruleClauses predicate. Kept deliberately separate from the Category taxonomy.

List catalog collections

List catalog collections

Authorizations:
Bearer
query Parameters
kind
string
Enum: "curated" "dynamic"

Filter by kind

status
string
Enum: "active" "archived"

Filter by status

search
string

Search by name or code

page
integer >= 1
Default: 1

Page number for pagination

itemsPerPage
integer [ 1 .. 100 ]
Default: 50

Number of items per page

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Create a catalog collection

Create a catalog collection

Authorizations:
Bearer
Request Body schema:
required

The new Collection resource

name
required
string [ 1 .. 255 ] characters
code
string or null <= 64 characters
kind
required
string
Enum: "curated" "dynamic"
description
string or null
position
integer >= 0
Default: 0

Responses

Request samples

Content type
{
  • "name": "string",
  • "code": "string",
  • "kind": "curated",
  • "description": "string",
  • "position": 0
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Summer Sale",
  • "code": "summer-sale",
  • "kind": "curated",
  • "description": "string",
  • "seo": {
    },
  • "position": 0,
  • "status": "active",
  • "ruleDefined": false,
  • "ruleMatch": "all",
  • "members": [
    ],
  • "ruleClauses": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string",
  • "primaryImageUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "iconUrl": "https://app.example.com/api/v1/storage/files/access/eyJ..."
}

List the curated collections a product is a member of

List the curated collections a product is a member of

Authorizations:
Bearer
query Parameters
productId
required
string

The product's opaque ResourceUri

page
integer
Default: 1

The collection page number

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Get a catalog collection

Get a catalog collection

Authorizations:
Bearer
path Parameters
id
required
string

Collection identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Summer Sale",
  • "code": "summer-sale",
  • "kind": "curated",
  • "description": "string",
  • "seo": {
    },
  • "position": 0,
  • "status": "active",
  • "ruleDefined": false,
  • "ruleMatch": "all",
  • "members": [
    ],
  • "ruleClauses": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string",
  • "primaryImageUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "iconUrl": "https://app.example.com/api/v1/storage/files/access/eyJ..."
}

Rename a catalog collection

Rename a catalog collection

Authorizations:
Bearer
path Parameters
id
required
string

Collection identifier

Request Body schema: application/merge-patch+json
required

The updated Collection resource

name
string [ 1 .. 255 ] characters

Responses

Request samples

Content type
application/merge-patch+json
{
  • "name": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Summer Sale",
  • "code": "summer-sale",
  • "kind": "curated",
  • "description": "string",
  • "seo": {
    },
  • "position": 0,
  • "status": "active",
  • "ruleDefined": false,
  • "ruleMatch": "all",
  • "members": [
    ],
  • "ruleClauses": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string",
  • "primaryImageUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "iconUrl": "https://app.example.com/api/v1/storage/files/access/eyJ..."
}

Archive a catalog collection

Archive a catalog collection

Authorizations:
Bearer
path Parameters
id
required
string

Collection identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Summer Sale",
  • "code": "summer-sale",
  • "kind": "curated",
  • "description": "string",
  • "seo": {
    },
  • "position": 0,
  • "status": "active",
  • "ruleDefined": false,
  • "ruleMatch": "all",
  • "members": [
    ],
  • "ruleClauses": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string",
  • "primaryImageUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "iconUrl": "https://app.example.com/api/v1/storage/files/access/eyJ..."
}

Update a catalog collection description

Update a catalog collection description

Authorizations:
Bearer
path Parameters
id
required
string

Collection identifier

Request Body schema:
required

The new Collection resource

description
string or null

Responses

Request samples

Content type
{
  • "description": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Summer Sale",
  • "code": "summer-sale",
  • "kind": "curated",
  • "description": "string",
  • "seo": {
    },
  • "position": 0,
  • "status": "active",
  • "ruleDefined": false,
  • "ruleMatch": "all",
  • "members": [
    ],
  • "ruleClauses": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string",
  • "primaryImageUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "iconUrl": "https://app.example.com/api/v1/storage/files/access/eyJ..."
}

Add a product to a curated collection

Add a product to a curated collection

Authorizations:
Bearer
path Parameters
id
required
string

Collection identifier

Request Body schema:
required

The new Collection resource

productId
required
string

Responses

Request samples

Content type
{
  • "productId": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Summer Sale",
  • "code": "summer-sale",
  • "kind": "curated",
  • "description": "string",
  • "seo": {
    },
  • "position": 0,
  • "status": "active",
  • "ruleDefined": false,
  • "ruleMatch": "all",
  • "members": [
    ],
  • "ruleClauses": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string",
  • "primaryImageUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "iconUrl": "https://app.example.com/api/v1/storage/files/access/eyJ..."
}

Add a batch of products to a curated collection

Add many products at once by their opaque ResourceUris. Idempotent — already-member products are skipped.

Authorizations:
Bearer
path Parameters
id
required
string

Collection identifier

Request Body schema:
required

The new Collection resource

productIds
required
Array of strings

Responses

Request samples

Content type
{
  • "productIds": [
    ]
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Summer Sale",
  • "code": "summer-sale",
  • "kind": "curated",
  • "description": "string",
  • "seo": {
    },
  • "position": 0,
  • "status": "active",
  • "ruleDefined": false,
  • "ruleMatch": "all",
  • "members": [
    ],
  • "ruleClauses": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string",
  • "primaryImageUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "iconUrl": "https://app.example.com/api/v1/storage/files/access/eyJ..."
}

Remove a product from a curated collection

Remove a product from a curated collection

Authorizations:
Bearer
path Parameters
id
required
string

Collection identifier

Request Body schema:
required

The new Collection resource

productId
required
string

Responses

Request samples

Content type
{
  • "productId": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Summer Sale",
  • "code": "summer-sale",
  • "kind": "curated",
  • "description": "string",
  • "seo": {
    },
  • "position": 0,
  • "status": "active",
  • "ruleDefined": false,
  • "ruleMatch": "all",
  • "members": [
    ],
  • "ruleClauses": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string",
  • "primaryImageUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "iconUrl": "https://app.example.com/api/v1/storage/files/access/eyJ..."
}

Reorder a curated collection's members

Reorder a curated collection's members

Authorizations:
Bearer
path Parameters
id
required
string

Collection identifier

Request Body schema:
required

The new Collection resource

orderedProductIds
required
Array of strings

Responses

Request samples

Content type
{
  • "orderedProductIds": [
    ]
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Summer Sale",
  • "code": "summer-sale",
  • "kind": "curated",
  • "description": "string",
  • "seo": {
    },
  • "position": 0,
  • "status": "active",
  • "ruleDefined": false,
  • "ruleMatch": "all",
  • "members": [
    ],
  • "ruleClauses": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string",
  • "primaryImageUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "iconUrl": "https://app.example.com/api/v1/storage/files/access/eyJ..."
}

Reactivate a catalog collection

Reactivate a catalog collection

Authorizations:
Bearer
path Parameters
id
required
string

Collection identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Summer Sale",
  • "code": "summer-sale",
  • "kind": "curated",
  • "description": "string",
  • "seo": {
    },
  • "position": 0,
  • "status": "active",
  • "ruleDefined": false,
  • "ruleMatch": "all",
  • "members": [
    ],
  • "ruleClauses": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string",
  • "primaryImageUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "iconUrl": "https://app.example.com/api/v1/storage/files/access/eyJ..."
}

Reorder a catalog collection among its peers

Reorder a catalog collection among its peers

Authorizations:
Bearer
path Parameters
id
required
string

Collection identifier

Request Body schema:
required

The new Collection resource

position
integer >= 0
Default: 0

Responses

Request samples

Content type
{
  • "position": 0
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Summer Sale",
  • "code": "summer-sale",
  • "kind": "curated",
  • "description": "string",
  • "seo": {
    },
  • "position": 0,
  • "status": "active",
  • "ruleDefined": false,
  • "ruleMatch": "all",
  • "members": [
    ],
  • "ruleClauses": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string",
  • "primaryImageUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "iconUrl": "https://app.example.com/api/v1/storage/files/access/eyJ..."
}

Set the rule expression of a dynamic collection

Store the typed predicate for a dynamic collection. Rejected with 400 on a curated collection.

Authorizations:
Bearer
path Parameters
id
required
string

Collection identifier

Request Body schema:
required

The new Collection resource

match
required
string
Enum: "all" "any"
required
Array of objects

Responses

Request samples

Content type
{
  • "match": "all",
  • "clauses": [
    ]
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Summer Sale",
  • "code": "summer-sale",
  • "kind": "curated",
  • "description": "string",
  • "seo": {
    },
  • "position": 0,
  • "status": "active",
  • "ruleDefined": false,
  • "ruleMatch": "all",
  • "members": [
    ],
  • "ruleClauses": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string",
  • "primaryImageUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "iconUrl": "https://app.example.com/api/v1/storage/files/access/eyJ..."
}

Update a catalog collection's SEO content

Set the collection's meta title, meta description and URL slug. The slug must be unique per tenant among collections.

Authorizations:
Bearer
path Parameters
id
required
string

Collection identifier

Request Body schema:
required

The new Collection resource

metaTitle
string or null
metaDescription
string or null
slug
string or null

Responses

Request samples

Content type
{
  • "metaTitle": "string",
  • "metaDescription": "string",
  • "slug": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Summer Sale",
  • "code": "summer-sale",
  • "kind": "curated",
  • "description": "string",
  • "seo": {
    },
  • "position": 0,
  • "status": "active",
  • "ruleDefined": false,
  • "ruleMatch": "all",
  • "members": [
    ],
  • "ruleClauses": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string",
  • "primaryImageUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "iconUrl": "https://app.example.com/api/v1/storage/files/access/eyJ..."
}

Catalog - Products

Represents a catalog product — the tenant-global, GTIN-keyed product identity.

List all catalog products

Retrieve a paginated list of catalog products with optional filters.

Authorizations:
Bearer
query Parameters
status
Array of strings
Items Enum: "active" "discontinued"
Example: status=active

Filter by product status (repeat status[] for multi-select; OR within, AND across dimensions)

brandId
Array of strings
Example: brandId=01912345-6789-7abc-def0-123456789abc

Filter by Brand aggregate id(s); repeat brandId[] for multi-select

attributeSetId
Array of strings
Example: attributeSetId=01912345-6789-7abc-def0-123456789abc

Filter by AttributeSet (family) id(s); repeat attributeSetId[] for multi-select

enrichmentStatus
Array of strings
Items Enum: "draft" "enriching" "review" "published"
Example: enrichmentStatus=draft

Filter by PIM enrichment status(es); repeat enrichmentStatus[] for multi-select

categoryId
Array of strings
Example: categoryId=01912345-6789-7abc-def0-123456789abc

Filter to products assigned to the given Category id(s); repeat categoryId[] for multi-select

collectionId
Array of strings
Example: collectionId=01912345-6789-7abc-def0-123456789abc

Filter to products that are members of the given Collection id(s); repeat collectionId[] for multi-select

assortmentId
Array of strings
Example: assortmentId=01912345-6789-7abc-def0-123456789abc

Filter to products that are CURATED members of the given Assortment id(s); repeat assortmentId[] for multi-select. Dynamic-rule membership is not included.

channelId
Array of strings
Example: channelId=01912345-6789-7abc-def0-123456789abc

Filter to products with an ENABLED listing on the given sales channel id(s) or ref(s); repeat channelId[] for multi-select

search
string
Example: search=Widget

Search by name or brand

page
integer >= 1
Default: 1
Example: page=1

Page number for pagination

itemsPerPage
integer [ 1 .. 100 ]
Default: 20
Example: itemsPerPage=20

Number of items per page

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Create a catalog product

Create a new tenant-global catalog product identity.

Authorizations:
Bearer
Request Body schema: application/json
required

Catalog product creation data

name
required
string non-empty
brand
string or null

Responses

Request samples

Content type
application/json
{
  • "name": "Acme Widget",
  • "brand": "Acme"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Acme Widget",
  • "brand": "Acme",
  • "code": "ACME-WIDGET-01",
  • "brandId": "01912345-6789-7abc-def0-123456789abc",
  • "attributeSetId": "01912345-6789-7abc-def0-123456789abc",
  • "description": "string",
  • "seo": {
    },
  • "status": "active",
  • "enrichmentStatus": "draft",
  • "sourceLocale": "en-US",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00",
  • "primaryImageUrl": "https://app.example.com/api/v1/storage/files/access/eyJ..."
}

Get a catalog product

Retrieve a single catalog product by its UUID.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Product UUID

query Parameters
locale
string
Example: locale=fr-FR

Optional BCP-47 display locale. Resolves name/description/SEO for that locale (falling back to the org source locale). Absent → org source locale.

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Acme Widget",
  • "brand": "Acme",
  • "code": "ACME-WIDGET-01",
  • "brandId": "01912345-6789-7abc-def0-123456789abc",
  • "attributeSetId": "01912345-6789-7abc-def0-123456789abc",
  • "description": "string",
  • "seo": {
    },
  • "status": "active",
  • "enrichmentStatus": "draft",
  • "sourceLocale": "en-US",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00",
  • "primaryImageUrl": "https://app.example.com/api/v1/storage/files/access/eyJ..."
}

Update a catalog product

Update a product's mutable profile (name, brand).

Authorizations:
Bearer
path Parameters
id
required
string

Product identifier

Request Body schema: application/merge-patch+json
required

The updated Product resource

name
string [ 1 .. 255 ] characters
brand
string or null <= 255 characters

Responses

Request samples

Content type
application/merge-patch+json
{
  • "name": "string",
  • "brand": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Acme Widget",
  • "brand": "Acme",
  • "code": "ACME-WIDGET-01",
  • "brandId": "01912345-6789-7abc-def0-123456789abc",
  • "attributeSetId": "01912345-6789-7abc-def0-123456789abc",
  • "description": "string",
  • "seo": {
    },
  • "status": "active",
  • "enrichmentStatus": "draft",
  • "sourceLocale": "en-US",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00",
  • "primaryImageUrl": "https://app.example.com/api/v1/storage/files/access/eyJ..."
}

Assign the product to an attribute set (family)

Assign the product to an active AttributeSet. Variants inherit the product's family.

Authorizations:
Bearer
path Parameters
id
required
string

Product identifier

Request Body schema: application/json
required

Attribute set assignment data

attributeSetId
required
string

Responses

Request samples

Content type
application/json
{
  • "attributeSetId": "01912345-6789-7abc-def0-123456789abc"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Acme Widget",
  • "brand": "Acme",
  • "code": "ACME-WIDGET-01",
  • "brandId": "01912345-6789-7abc-def0-123456789abc",
  • "attributeSetId": "01912345-6789-7abc-def0-123456789abc",
  • "description": "string",
  • "seo": {
    },
  • "status": "active",
  • "enrichmentStatus": "draft",
  • "sourceLocale": "en-US",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00",
  • "primaryImageUrl": "https://app.example.com/api/v1/storage/files/access/eyJ..."
}

Clear the product's attribute set (family) assignment

Clear the product's attribute set (family) assignment

Authorizations:
Bearer
path Parameters
id
required
string

Product identifier

Responses

Report a product's PIM completeness

Derived completeness score, counts and the list of unmet requirements for a product.

Authorizations:
Bearer
path Parameters
id
required
string

CatalogCompleteness identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "subjectType": "product",
  • "score": 0,
  • "requiredCount": 0,
  • "filledCount": 0,
  • "hasFamily": false,
  • "enrichmentStatus": "draft",
  • "isPublishable": false,
  • "missing": [
    ]
}

Update a catalog product's description

Update a catalog product's description

Authorizations:
Bearer
path Parameters
id
required
string

Product identifier

Request Body schema:
required

The new Product resource

description
string or null

Responses

Request samples

Content type
{
  • "description": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Acme Widget",
  • "brand": "Acme",
  • "code": "ACME-WIDGET-01",
  • "brandId": "01912345-6789-7abc-def0-123456789abc",
  • "attributeSetId": "01912345-6789-7abc-def0-123456789abc",
  • "description": "string",
  • "seo": {
    },
  • "status": "active",
  • "enrichmentStatus": "draft",
  • "sourceLocale": "en-US",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00",
  • "primaryImageUrl": "https://app.example.com/api/v1/storage/files/access/eyJ..."
}

Discontinue a catalog product

Transition a product to the discontinued status.

Authorizations:
Bearer
path Parameters
id
required
string

Product identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Acme Widget",
  • "brand": "Acme",
  • "code": "ACME-WIDGET-01",
  • "brandId": "01912345-6789-7abc-def0-123456789abc",
  • "attributeSetId": "01912345-6789-7abc-def0-123456789abc",
  • "description": "string",
  • "seo": {
    },
  • "status": "active",
  • "enrichmentStatus": "draft",
  • "sourceLocale": "en-US",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00",
  • "primaryImageUrl": "https://app.example.com/api/v1/storage/files/access/eyJ..."
}

Transition the product's PIM enrichment status

Move the product through its enrichment lifecycle (draft → enriching → review → published; back-transitions allowed for rework).

Authorizations:
Bearer
path Parameters
id
required
string

Product identifier

Request Body schema: application/json
required

Enrichment status transition data

status
required
string
Enum: "draft" "enriching" "review" "published"

Responses

Request samples

Content type
application/json
{
  • "status": "enriching"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Acme Widget",
  • "brand": "Acme",
  • "code": "ACME-WIDGET-01",
  • "brandId": "01912345-6789-7abc-def0-123456789abc",
  • "attributeSetId": "01912345-6789-7abc-def0-123456789abc",
  • "description": "string",
  • "seo": {
    },
  • "status": "active",
  • "enrichmentStatus": "draft",
  • "sourceLocale": "en-US",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00",
  • "primaryImageUrl": "https://app.example.com/api/v1/storage/files/access/eyJ..."
}

Generate the product's variant matrix

Generate the missing Variants — the full Cartesian product of the product's variant axes' (OptionSet) values. Idempotent: combinations whose Variant already exists are skipped.

Authorizations:
Bearer
path Parameters
id
required
string

Product identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Acme Widget",
  • "brand": "Acme",
  • "code": "ACME-WIDGET-01",
  • "brandId": "01912345-6789-7abc-def0-123456789abc",
  • "attributeSetId": "01912345-6789-7abc-def0-123456789abc",
  • "description": "string",
  • "seo": {
    },
  • "status": "active",
  • "enrichmentStatus": "draft",
  • "sourceLocale": "en-US",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00",
  • "primaryImageUrl": "https://app.example.com/api/v1/storage/files/access/eyJ..."
}

Reactivate a catalog product

Transition a discontinued product back to the active status.

Authorizations:
Bearer
path Parameters
id
required
string

Product identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Acme Widget",
  • "brand": "Acme",
  • "code": "ACME-WIDGET-01",
  • "brandId": "01912345-6789-7abc-def0-123456789abc",
  • "attributeSetId": "01912345-6789-7abc-def0-123456789abc",
  • "description": "string",
  • "seo": {
    },
  • "status": "active",
  • "enrichmentStatus": "draft",
  • "sourceLocale": "en-US",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00",
  • "primaryImageUrl": "https://app.example.com/api/v1/storage/files/access/eyJ..."
}

Update a catalog product's SEO content

Set the product's meta title, meta description and URL slug. The slug must be unique per tenant among products.

Authorizations:
Bearer
path Parameters
id
required
string

Product identifier

Request Body schema:
required

The new Product resource

metaTitle
string or null
metaDescription
string or null
slug
string or null

Responses

Request samples

Content type
{
  • "metaTitle": "string",
  • "metaDescription": "string",
  • "slug": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Acme Widget",
  • "brand": "Acme",
  • "code": "ACME-WIDGET-01",
  • "brandId": "01912345-6789-7abc-def0-123456789abc",
  • "attributeSetId": "01912345-6789-7abc-def0-123456789abc",
  • "description": "string",
  • "seo": {
    },
  • "status": "active",
  • "enrichmentStatus": "draft",
  • "sourceLocale": "en-US",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00",
  • "primaryImageUrl": "https://app.example.com/api/v1/storage/files/access/eyJ..."
}

Assign or clear a catalog product's Brand reference

Set the product's Brand reference to the given Brand id, or clear it when brandId is null.

Authorizations:
Bearer
path Parameters
id
required
string

Product identifier

Request Body schema: application/json
optional

Brand assignment data

brandId
string or null

Responses

Request samples

Content type
application/json
{
  • "brandId": "01912345-6789-7abc-def0-123456789abc"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Acme Widget",
  • "brand": "Acme",
  • "code": "ACME-WIDGET-01",
  • "brandId": "01912345-6789-7abc-def0-123456789abc",
  • "attributeSetId": "01912345-6789-7abc-def0-123456789abc",
  • "description": "string",
  • "seo": {
    },
  • "status": "active",
  • "enrichmentStatus": "draft",
  • "sourceLocale": "en-US",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00",
  • "primaryImageUrl": "https://app.example.com/api/v1/storage/files/access/eyJ..."
}

Get a product's resolved attribute schema

Returns the product's attribute schema (sections → fields) resolved from its AttributeSet, with the effective member-override binding and current values.

Authorizations:
Bearer
path Parameters
productId
required
string

The product id

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "productId": "string",
  • "attributeSetId": "01912345-6789-7abc-def0-123456789abc",
  • "attributeSetName": "Apparel",
  • "sections": [
    ]
}

Catalog - Variants

Represents a catalog variant — the sellable unit under a product.

List all catalog variants

Retrieve a paginated list of catalog variants, optionally filtered by owning product.

Authorizations:
Bearer
query Parameters
productId
string <uuid>
Example: productId=01912345-6789-7abc-def0-123456789abc

Filter by owning product UUID

status
string
Enum: "active" "discontinued"
Example: status=active

Filter by variant status

search
string
Example: search=Red

Search by variant name

page
integer >= 1
Default: 1
Example: page=1

Page number for pagination

itemsPerPage
integer [ 1 .. 100 ]
Default: 20
Example: itemsPerPage=20

Number of items per page

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Create a catalog variant

Create a new sellable variant under an existing catalog product.

Authorizations:
Bearer
Request Body schema: application/json
required

Catalog variant creation data

productId
required
string <uuid>
name
required
string non-empty
uom
string non-empty
Default: "H87"

Responses

Request samples

Content type
application/json
{
  • "productId": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Red / Large",
  • "uom": "H87"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "productId": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Red / Large",
  • "uom": "H87",
  • "status": "active",
  • "enrichmentStatus": "draft",
  • "axes": {
    },
  • "sku": "SKU-RED-XL",
  • "gtin": "00012345678905",
  • "mpn": "MPN-9",
  • "supplierReference": "SUP-42",
  • "hsCode": "6109.10",
  • "price": {
    },
  • "compareAtPrice": {
    },
  • "unitCost": {
    },
  • "taxCategoryRef": "glacia:///finance/tax-categories/01ABC",
  • "priceRounding": "none",
  • "margin": 40.02,
  • "channelListings": [
    ],
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Get a catalog variant

Retrieve a single catalog variant by its UUID.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Variant UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "productId": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Red / Large",
  • "uom": "H87",
  • "status": "active",
  • "enrichmentStatus": "draft",
  • "axes": {
    },
  • "sku": "SKU-RED-XL",
  • "gtin": "00012345678905",
  • "mpn": "MPN-9",
  • "supplierReference": "SUP-42",
  • "hsCode": "6109.10",
  • "price": {
    },
  • "compareAtPrice": {
    },
  • "unitCost": {
    },
  • "taxCategoryRef": "glacia:///finance/tax-categories/01ABC",
  • "priceRounding": "none",
  • "margin": 40.02,
  • "channelListings": [
    ],
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Update a catalog variant

Update a variant's mutable profile (name, unit of measure).

Authorizations:
Bearer
path Parameters
id
required
string

Variant identifier

Request Body schema: application/merge-patch+json
required

The updated Variant resource

name
string [ 1 .. 255 ] characters
uom
string [ 1 .. 50 ] characters
Default: "H87"
sku
string or null <= 100 characters
gtin
string or null <= 20 characters
mpn
string or null <= 100 characters
supplierReference
string or null <= 100 characters
hsCode
string or null <= 20 characters
VariantMoneyInput (object) or null
VariantMoneyInput (object) or null
VariantMoneyInput (object) or null
taxCategoryRef
string or null <= 255 characters
priceRounding
string
Default: "none"
Enum: "none" "nearest_9" "nearest_95" "nearest_99"

Responses

Request samples

Content type
application/merge-patch+json
{
  • "name": "string",
  • "uom": "H87",
  • "sku": "string",
  • "gtin": "string",
  • "mpn": "string",
  • "supplierReference": "string",
  • "hsCode": "string",
  • "price": {
    },
  • "compareAtPrice": {
    },
  • "unitCost": {
    },
  • "taxCategoryRef": "string",
  • "priceRounding": "none"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "productId": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Red / Large",
  • "uom": "H87",
  • "status": "active",
  • "enrichmentStatus": "draft",
  • "axes": {
    },
  • "sku": "SKU-RED-XL",
  • "gtin": "00012345678905",
  • "mpn": "MPN-9",
  • "supplierReference": "SUP-42",
  • "hsCode": "6109.10",
  • "price": {
    },
  • "compareAtPrice": {
    },
  • "unitCost": {
    },
  • "taxCategoryRef": "glacia:///finance/tax-categories/01ABC",
  • "priceRounding": "none",
  • "margin": 40.02,
  • "channelListings": [
    ],
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Set a variant's per-channel listing

Set (upsert) the per-channel price override and published flag for a sales channel. A null priceOverride follows the catalog price.

Authorizations:
Bearer
path Parameters
id
required
string

Variant identifier

Request Body schema:
required

The new Variant resource

channelRef
required
string <= 255 characters
VariantMoneyInput (object) or null
published
boolean
Default: false

Responses

Request samples

Content type
{
  • "channelRef": "string",
  • "priceOverride": {
    },
  • "published": false
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "productId": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Red / Large",
  • "uom": "H87",
  • "status": "active",
  • "enrichmentStatus": "draft",
  • "axes": {
    },
  • "sku": "SKU-RED-XL",
  • "gtin": "00012345678905",
  • "mpn": "MPN-9",
  • "supplierReference": "SUP-42",
  • "hsCode": "6109.10",
  • "price": {
    },
  • "compareAtPrice": {
    },
  • "unitCost": {
    },
  • "taxCategoryRef": "glacia:///finance/tax-categories/01ABC",
  • "priceRounding": "none",
  • "margin": 40.02,
  • "channelListings": [
    ],
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Clear a variant's per-channel listing

Remove the listing for a sales channel. No-op-safe when the channel was never listed.

Authorizations:
Bearer
path Parameters
id
required
string

Variant identifier

Request Body schema:
required

The new Variant resource

channelRef
required
string <= 255 characters

Responses

Request samples

Content type
{
  • "channelRef": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "productId": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Red / Large",
  • "uom": "H87",
  • "status": "active",
  • "enrichmentStatus": "draft",
  • "axes": {
    },
  • "sku": "SKU-RED-XL",
  • "gtin": "00012345678905",
  • "mpn": "MPN-9",
  • "supplierReference": "SUP-42",
  • "hsCode": "6109.10",
  • "price": {
    },
  • "compareAtPrice": {
    },
  • "unitCost": {
    },
  • "taxCategoryRef": "glacia:///finance/tax-categories/01ABC",
  • "priceRounding": "none",
  • "margin": 40.02,
  • "channelListings": [
    ],
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Publish (make live) a variant on a sales channel

Set the per-channel listing published flag to true so the variant lands live on that channel. Preserves any price override; creates the listing when none exists. Idempotent.

Authorizations:
Bearer
path Parameters
id
required
string

Variant identifier

Request Body schema:
required

The new Variant resource

channelRef
required
string <= 255 characters
Default: ""

Responses

Request samples

Content type
{
  • "channelRef": ""
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "productId": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Red / Large",
  • "uom": "H87",
  • "status": "active",
  • "enrichmentStatus": "draft",
  • "axes": {
    },
  • "sku": "SKU-RED-XL",
  • "gtin": "00012345678905",
  • "mpn": "MPN-9",
  • "supplierReference": "SUP-42",
  • "hsCode": "6109.10",
  • "price": {
    },
  • "compareAtPrice": {
    },
  • "unitCost": {
    },
  • "taxCategoryRef": "glacia:///finance/tax-categories/01ABC",
  • "priceRounding": "none",
  • "margin": 40.02,
  • "channelListings": [
    ],
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Unpublish (hide) a variant on a sales channel

Set the per-channel listing published flag to false so the variant is hidden on that channel. Preserves any price override. No-op-safe when the variant was never listed. Idempotent.

Authorizations:
Bearer
path Parameters
id
required
string

Variant identifier

Request Body schema:
required

The new Variant resource

channelRef
required
string <= 255 characters
Default: ""

Responses

Request samples

Content type
{
  • "channelRef": ""
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "productId": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Red / Large",
  • "uom": "H87",
  • "status": "active",
  • "enrichmentStatus": "draft",
  • "axes": {
    },
  • "sku": "SKU-RED-XL",
  • "gtin": "00012345678905",
  • "mpn": "MPN-9",
  • "supplierReference": "SUP-42",
  • "hsCode": "6109.10",
  • "price": {
    },
  • "compareAtPrice": {
    },
  • "unitCost": {
    },
  • "taxCategoryRef": "glacia:///finance/tax-categories/01ABC",
  • "priceRounding": "none",
  • "margin": 40.02,
  • "channelListings": [
    ],
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Report a variant's PIM completeness

Derived completeness score, counts and the list of unmet requirements for a variant (scored against the owning product's family).

Authorizations:
Bearer
path Parameters
id
required
string

CatalogCompleteness identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "subjectType": "product",
  • "score": 0,
  • "requiredCount": 0,
  • "filledCount": 0,
  • "hasFamily": false,
  • "enrichmentStatus": "draft",
  • "isPublishable": false,
  • "missing": [
    ]
}

Discontinue a catalog variant

Transition a variant to the discontinued status.

Authorizations:
Bearer
path Parameters
id
required
string

Variant identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "productId": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Red / Large",
  • "uom": "H87",
  • "status": "active",
  • "enrichmentStatus": "draft",
  • "axes": {
    },
  • "sku": "SKU-RED-XL",
  • "gtin": "00012345678905",
  • "mpn": "MPN-9",
  • "supplierReference": "SUP-42",
  • "hsCode": "6109.10",
  • "price": {
    },
  • "compareAtPrice": {
    },
  • "unitCost": {
    },
  • "taxCategoryRef": "glacia:///finance/tax-categories/01ABC",
  • "priceRounding": "none",
  • "margin": 40.02,
  • "channelListings": [
    ],
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Transition the variant's PIM enrichment status

Move the variant through its enrichment lifecycle (draft → enriching → review → published; back-transitions allowed for rework).

Authorizations:
Bearer
path Parameters
id
required
string

Variant identifier

Request Body schema: application/json
required

Enrichment status transition data

status
required
string
Enum: "draft" "enriching" "review" "published"

Responses

Request samples

Content type
application/json
{
  • "status": "enriching"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "productId": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Red / Large",
  • "uom": "H87",
  • "status": "active",
  • "enrichmentStatus": "draft",
  • "axes": {
    },
  • "sku": "SKU-RED-XL",
  • "gtin": "00012345678905",
  • "mpn": "MPN-9",
  • "supplierReference": "SUP-42",
  • "hsCode": "6109.10",
  • "price": {
    },
  • "compareAtPrice": {
    },
  • "unitCost": {
    },
  • "taxCategoryRef": "glacia:///finance/tax-categories/01ABC",
  • "priceRounding": "none",
  • "margin": 40.02,
  • "channelListings": [
    ],
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Reactivate a catalog variant

Transition a discontinued variant back to the active status.

Authorizations:
Bearer
path Parameters
id
required
string

Variant identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "productId": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Red / Large",
  • "uom": "H87",
  • "status": "active",
  • "enrichmentStatus": "draft",
  • "axes": {
    },
  • "sku": "SKU-RED-XL",
  • "gtin": "00012345678905",
  • "mpn": "MPN-9",
  • "supplierReference": "SUP-42",
  • "hsCode": "6109.10",
  • "price": {
    },
  • "compareAtPrice": {
    },
  • "unitCost": {
    },
  • "taxCategoryRef": "glacia:///finance/tax-categories/01ABC",
  • "priceRounding": "none",
  • "margin": 40.02,
  • "channelListings": [
    ],
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Catalog - Folders

Represents a node in the tenant's DAM media-library folder tree (catalog.md §4.5). The collection endpoint returns the WHOLE flat list (not paginated); the UI assembles the hierarchy client-side from each folder's parentId. Archiving is a status change exposed as an explicit POST action, not a hard DELETE, so the folder stays queryable.

List catalog media folders (whole tree, not paginated)

List catalog media folders (whole tree, not paginated)

Authorizations:
Bearer
query Parameters
status
string
Enum: "active" "archived"

Filter by status

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "member": [
    ]
}

Create a catalog media folder

Creates a folder in the media-library tree. A null parentId creates a root folder.

Authorizations:
Bearer
Request Body schema:
required

The new CatalogFolder resource

name
required
string [ 1 .. 255 ] characters
parentId
string or null

Responses

Request samples

Content type
{
  • "name": "string",
  • "parentId": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Product Shots",
  • "parentId": "string",
  • "status": "active",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Get a catalog media folder

Get a catalog media folder

Authorizations:
Bearer
path Parameters
id
required
string

CatalogFolder identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Product Shots",
  • "parentId": "string",
  • "status": "active",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Rename a catalog media folder

Rename a catalog media folder

Authorizations:
Bearer
path Parameters
id
required
string

CatalogFolder identifier

Request Body schema: application/merge-patch+json
required

The updated CatalogFolder resource

name
string [ 1 .. 255 ] characters

Responses

Request samples

Content type
application/merge-patch+json
{
  • "name": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Product Shots",
  • "parentId": "string",
  • "status": "active",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Archive a catalog media folder

Archive a catalog media folder

Authorizations:
Bearer
path Parameters
id
required
string

CatalogFolder identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Product Shots",
  • "parentId": "string",
  • "status": "active",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Reparent a catalog media folder

A null newParentId promotes the folder to a root.

Authorizations:
Bearer
path Parameters
id
required
string

CatalogFolder identifier

Request Body schema:
required

The new CatalogFolder resource

newParentId
string or null

Responses

Request samples

Content type
{
  • "newParentId": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Product Shots",
  • "parentId": "string",
  • "status": "active",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Catalog - Product media

One media link on an owner (product, variant, brand, category or collection), linking a reusable Asset with a role + ordering + nullable locale/channel scope (catalog.md §4.5, DAM Phase 2).

ONE resource serves every owner because the representation and the board semantics are identical — only the URI prefix differs. Each operation carries its owner type in extraProperties, so a single provider/processor per action serves products, variants, brands, categories and collections. The mutating operations return the FULL board (a list) rather than the single changed link, because linking, unlinking and reordering all renormalise position and can move primary.

A product's linked media, in render order

A product's linked media, in render order

Authorizations:
Bearer
path Parameters
ownerId
required
string

CatalogMediaLink identifier

query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": []
}

Reorder a product's media

Reorder a product's media

Authorizations:
Bearer
path Parameters
ownerId
required
string

CatalogMediaLink identifier

Request Body schema:
required

The new CatalogMediaLink resource

orderedAssetIds
required
Array of strings

Responses

Request samples

Content type
{
  • "orderedAssetIds": [
    ]
}

Response samples

Content type
{}

Make a product media link the primary

Make a product media link the primary

Authorizations:
Bearer
path Parameters
ownerId
required
string

CatalogMediaLink identifier

Request Body schema:
required

The new CatalogMediaLink resource

assetId
required
string

Responses

Request samples

Content type
{
  • "assetId": "string"
}

Response samples

Content type
{}

Change a product media link's role

Change a product media link's role

Authorizations:
Bearer
path Parameters
ownerId
required
string

CatalogMediaLink identifier

Request Body schema:
required

The new CatalogMediaLink resource

assetId
required
string
role
required
string
Enum: "primary" "gallery" "swatch" "icon"

Responses

Request samples

Content type
{
  • "assetId": "string",
  • "role": "primary"
}

Response samples

Content type
{}

Set a product media link's locale/channel scope

Set a product media link's locale/channel scope

Authorizations:
Bearer
path Parameters
ownerId
required
string

CatalogMediaLink identifier

Request Body schema:
required

The new CatalogMediaLink resource

assetId
required
string
locale
string or null <= 35 characters
channelId
string or null <= 255 characters

Responses

Request samples

Content type
{
  • "assetId": "string",
  • "locale": "string",
  • "channelId": "string"
}

Response samples

Content type
{}

Catalog - Variant media

One media link on an owner (product, variant, brand, category or collection), linking a reusable Asset with a role + ordering + nullable locale/channel scope (catalog.md §4.5, DAM Phase 2).

ONE resource serves every owner because the representation and the board semantics are identical — only the URI prefix differs. Each operation carries its owner type in extraProperties, so a single provider/processor per action serves products, variants, brands, categories and collections. The mutating operations return the FULL board (a list) rather than the single changed link, because linking, unlinking and reordering all renormalise position and can move primary.

A variant's linked media, in render order

A variant's linked media, in render order

Authorizations:
Bearer
path Parameters
ownerId
required
string

CatalogMediaLink identifier

query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": []
}

Reorder a variant's media

Reorder a variant's media

Authorizations:
Bearer
path Parameters
ownerId
required
string

CatalogMediaLink identifier

Request Body schema:
required

The new CatalogMediaLink resource

orderedAssetIds
required
Array of strings

Responses

Request samples

Content type
{
  • "orderedAssetIds": [
    ]
}

Response samples

Content type
{}

Make a variant media link the primary

Make a variant media link the primary

Authorizations:
Bearer
path Parameters
ownerId
required
string

CatalogMediaLink identifier

Request Body schema:
required

The new CatalogMediaLink resource

assetId
required
string

Responses

Request samples

Content type
{
  • "assetId": "string"
}

Response samples

Content type
{}

Change a variant media link's role

Change a variant media link's role

Authorizations:
Bearer
path Parameters
ownerId
required
string

CatalogMediaLink identifier

Request Body schema:
required

The new CatalogMediaLink resource

assetId
required
string
role
required
string
Enum: "primary" "gallery" "swatch" "icon"

Responses

Request samples

Content type
{
  • "assetId": "string",
  • "role": "primary"
}

Response samples

Content type
{}

Set a variant media link's locale/channel scope

Set a variant media link's locale/channel scope

Authorizations:
Bearer
path Parameters
ownerId
required
string

CatalogMediaLink identifier

Request Body schema:
required

The new CatalogMediaLink resource

assetId
required
string
locale
string or null <= 35 characters
channelId
string or null <= 255 characters

Responses

Request samples

Content type
{
  • "assetId": "string",
  • "locale": "string",
  • "channelId": "string"
}

Response samples

Content type
{}

Catalog - Brand media

One media link on an owner (product, variant, brand, category or collection), linking a reusable Asset with a role + ordering + nullable locale/channel scope (catalog.md §4.5, DAM Phase 2).

ONE resource serves every owner because the representation and the board semantics are identical — only the URI prefix differs. Each operation carries its owner type in extraProperties, so a single provider/processor per action serves products, variants, brands, categories and collections. The mutating operations return the FULL board (a list) rather than the single changed link, because linking, unlinking and reordering all renormalise position and can move primary.

A brand's linked media, in render order

A brand's linked media, in render order

Authorizations:
Bearer
path Parameters
ownerId
required
string

CatalogMediaLink identifier

query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": []
}

Reorder a brand's media

Reorder a brand's media

Authorizations:
Bearer
path Parameters
ownerId
required
string

CatalogMediaLink identifier

Request Body schema:
required

The new CatalogMediaLink resource

orderedAssetIds
required
Array of strings

Responses

Request samples

Content type
{
  • "orderedAssetIds": [
    ]
}

Response samples

Content type
{}

Make a brand media link the primary

Make a brand media link the primary

Authorizations:
Bearer
path Parameters
ownerId
required
string

CatalogMediaLink identifier

Request Body schema:
required

The new CatalogMediaLink resource

assetId
required
string

Responses

Request samples

Content type
{
  • "assetId": "string"
}

Response samples

Content type
{}

Change a brand media link's role

Change a brand media link's role

Authorizations:
Bearer
path Parameters
ownerId
required
string

CatalogMediaLink identifier

Request Body schema:
required

The new CatalogMediaLink resource

assetId
required
string
role
required
string
Enum: "primary" "gallery" "swatch" "icon"

Responses

Request samples

Content type
{
  • "assetId": "string",
  • "role": "primary"
}

Response samples

Content type
{}

Set a brand media link's locale/channel scope

Set a brand media link's locale/channel scope

Authorizations:
Bearer
path Parameters
ownerId
required
string

CatalogMediaLink identifier

Request Body schema:
required

The new CatalogMediaLink resource

assetId
required
string
locale
string or null <= 35 characters
channelId
string or null <= 255 characters

Responses

Request samples

Content type
{
  • "assetId": "string",
  • "locale": "string",
  • "channelId": "string"
}

Response samples

Content type
{}

Catalog - Category media

One media link on an owner (product, variant, brand, category or collection), linking a reusable Asset with a role + ordering + nullable locale/channel scope (catalog.md §4.5, DAM Phase 2).

ONE resource serves every owner because the representation and the board semantics are identical — only the URI prefix differs. Each operation carries its owner type in extraProperties, so a single provider/processor per action serves products, variants, brands, categories and collections. The mutating operations return the FULL board (a list) rather than the single changed link, because linking, unlinking and reordering all renormalise position and can move primary.

A category's linked media, in render order

A category's linked media, in render order

Authorizations:
Bearer
path Parameters
ownerId
required
string

CatalogMediaLink identifier

query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": []
}

Reorder a category's media

Reorder a category's media

Authorizations:
Bearer
path Parameters
ownerId
required
string

CatalogMediaLink identifier

Request Body schema:
required

The new CatalogMediaLink resource

orderedAssetIds
required
Array of strings

Responses

Request samples

Content type
{
  • "orderedAssetIds": [
    ]
}

Response samples

Content type
{}

Make a category media link the primary

Make a category media link the primary

Authorizations:
Bearer
path Parameters
ownerId
required
string

CatalogMediaLink identifier

Request Body schema:
required

The new CatalogMediaLink resource

assetId
required
string

Responses

Request samples

Content type
{
  • "assetId": "string"
}

Response samples

Content type
{}

Change a category media link's role

Change a category media link's role

Authorizations:
Bearer
path Parameters
ownerId
required
string

CatalogMediaLink identifier

Request Body schema:
required

The new CatalogMediaLink resource

assetId
required
string
role
required
string
Enum: "primary" "gallery" "swatch" "icon"

Responses

Request samples

Content type
{
  • "assetId": "string",
  • "role": "primary"
}

Response samples

Content type
{}

Set a category media link's locale/channel scope

Set a category media link's locale/channel scope

Authorizations:
Bearer
path Parameters
ownerId
required
string

CatalogMediaLink identifier

Request Body schema:
required

The new CatalogMediaLink resource

assetId
required
string
locale
string or null <= 35 characters
channelId
string or null <= 255 characters

Responses

Request samples

Content type
{
  • "assetId": "string",
  • "locale": "string",
  • "channelId": "string"
}

Response samples

Content type
{}

Catalog - Collection media

One media link on an owner (product, variant, brand, category or collection), linking a reusable Asset with a role + ordering + nullable locale/channel scope (catalog.md §4.5, DAM Phase 2).

ONE resource serves every owner because the representation and the board semantics are identical — only the URI prefix differs. Each operation carries its owner type in extraProperties, so a single provider/processor per action serves products, variants, brands, categories and collections. The mutating operations return the FULL board (a list) rather than the single changed link, because linking, unlinking and reordering all renormalise position and can move primary.

A collection's linked media, in render order

A collection's linked media, in render order

Authorizations:
Bearer
path Parameters
ownerId
required
string

CatalogMediaLink identifier

query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": []
}

Reorder a collection's media

Reorder a collection's media

Authorizations:
Bearer
path Parameters
ownerId
required
string

CatalogMediaLink identifier

Request Body schema:
required

The new CatalogMediaLink resource

orderedAssetIds
required
Array of strings

Responses

Request samples

Content type
{
  • "orderedAssetIds": [
    ]
}

Response samples

Content type
{}

Make a collection media link the primary

Make a collection media link the primary

Authorizations:
Bearer
path Parameters
ownerId
required
string

CatalogMediaLink identifier

Request Body schema:
required

The new CatalogMediaLink resource

assetId
required
string

Responses

Request samples

Content type
{
  • "assetId": "string"
}

Response samples

Content type
{}

Change a collection media link's role

Change a collection media link's role

Authorizations:
Bearer
path Parameters
ownerId
required
string

CatalogMediaLink identifier

Request Body schema:
required

The new CatalogMediaLink resource

assetId
required
string
role
required
string
Enum: "primary" "gallery" "swatch" "icon"

Responses

Request samples

Content type
{
  • "assetId": "string",
  • "role": "primary"
}

Response samples

Content type
{}

Set a collection media link's locale/channel scope

Set a collection media link's locale/channel scope

Authorizations:
Bearer
path Parameters
ownerId
required
string

CatalogMediaLink identifier

Request Body schema:
required

The new CatalogMediaLink resource

assetId
required
string
locale
string or null <= 35 characters
channelId
string or null <= 255 characters

Responses

Request samples

Content type
{
  • "assetId": "string",
  • "locale": "string",
  • "channelId": "string"
}

Response samples

Content type
{}

Catalog - Option Sets

Represents a reusable, governed catalog option set — a value list (e.g. "Sizes", "Colours") that select/multiselect attributes bind to. Owns an ordered collection of values, each with a stable channel code and (for swatch sets) a colour.

List catalog option sets

List catalog option sets

Authorizations:
Bearer
query Parameters
status
string
Enum: "active" "archived"

Filter by status

valueType
string
Enum: "text" "swatch"

Filter by value type

search
string

Search by name or code

page
integer >= 1
Default: 1

Page number for pagination

itemsPerPage
integer [ 1 .. 200 ]
Default: 50

Number of items per page

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Create a catalog option set

Create a catalog option set

Authorizations:
Bearer
Request Body schema:
required

The new OptionSet resource

name
required
string [ 1 .. 255 ] characters
description
string or null <= 2000 characters
code
string or null <= 64 characters
valueType
string or null
Enum: "text" "swatch"
displayOrder
string or null
Enum: "manual" "alphabetical"

Responses

Request samples

Content type
{
  • "name": "string",
  • "description": "string",
  • "code": "string",
  • "valueType": "text",
  • "displayOrder": "manual"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Sizes",
  • "description": "Standard apparel sizes",
  • "code": "sizes",
  • "valueType": "text",
  • "displayOrder": "manual",
  • "status": "active",
  • "values": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Get a catalog option set

Get a catalog option set

Authorizations:
Bearer
path Parameters
id
required
string

OptionSet identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Sizes",
  • "description": "Standard apparel sizes",
  • "code": "sizes",
  • "valueType": "text",
  • "displayOrder": "manual",
  • "status": "active",
  • "values": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Rename a catalog option set

Rename the set. code is immutable after creation.

Authorizations:
Bearer
path Parameters
id
required
string

OptionSet identifier

Request Body schema: application/merge-patch+json
required

The updated OptionSet resource

name
string [ 1 .. 255 ] characters

Responses

Request samples

Content type
application/merge-patch+json
{
  • "name": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Sizes",
  • "description": "Standard apparel sizes",
  • "code": "sizes",
  • "valueType": "text",
  • "displayOrder": "manual",
  • "status": "active",
  • "values": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Archive a catalog option set

Archive a catalog option set

Authorizations:
Bearer
path Parameters
id
required
string

OptionSet identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Sizes",
  • "description": "Standard apparel sizes",
  • "code": "sizes",
  • "valueType": "text",
  • "displayOrder": "manual",
  • "status": "active",
  • "values": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Change the option set description

A null description clears the hint.

Authorizations:
Bearer
path Parameters
id
required
string

OptionSet identifier

Request Body schema:
required

The new OptionSet resource

description
string or null <= 2000 characters

Responses

Request samples

Content type
{
  • "description": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Sizes",
  • "description": "Standard apparel sizes",
  • "code": "sizes",
  • "valueType": "text",
  • "displayOrder": "manual",
  • "status": "active",
  • "values": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Set the option set display order (manual or alphabetical)

Set the option set display order (manual or alphabetical)

Authorizations:
Bearer
path Parameters
id
required
string

OptionSet identifier

Request Body schema:
required

The new OptionSet resource

displayOrder
required
string
Enum: "manual" "alphabetical"

Responses

Request samples

Content type
{
  • "displayOrder": "manual"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Sizes",
  • "description": "Standard apparel sizes",
  • "code": "sizes",
  • "valueType": "text",
  • "displayOrder": "manual",
  • "status": "active",
  • "values": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Reactivate a catalog option set

Reactivate a catalog option set

Authorizations:
Bearer
path Parameters
id
required
string

OptionSet identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Sizes",
  • "description": "Standard apparel sizes",
  • "code": "sizes",
  • "valueType": "text",
  • "displayOrder": "manual",
  • "status": "active",
  • "values": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Set the option set value type (text or swatch)

Set the option set value type (text or swatch)

Authorizations:
Bearer
path Parameters
id
required
string

OptionSet identifier

Request Body schema:
required

The new OptionSet resource

valueType
required
string
Enum: "text" "swatch"

Responses

Request samples

Content type
{
  • "valueType": "text"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Sizes",
  • "description": "Standard apparel sizes",
  • "code": "sizes",
  • "valueType": "text",
  • "displayOrder": "manual",
  • "status": "active",
  • "values": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Add an allowed value

Add an allowed value

Authorizations:
Bearer
path Parameters
id
required
string

OptionSet identifier

Request Body schema:
required

The new OptionSet resource

label
required
string [ 1 .. 255 ] characters
code
required
string [ 1 .. 64 ] characters
swatchColor
string or null^(#[0-9A-Fa-f]{6})$
optionSetValueId
string or null

Caller-minted id for this value. Optional: when omitted the processor mints one.

Responses

Request samples

Content type
{
  • "label": "string",
  • "code": "string",
  • "swatchColor": "string",
  • "optionSetValueId": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Sizes",
  • "description": "Standard apparel sizes",
  • "code": "sizes",
  • "valueType": "text",
  • "displayOrder": "manual",
  • "status": "active",
  • "values": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Reorder allowed values

Reorder allowed values

Authorizations:
Bearer
path Parameters
id
required
string

OptionSet identifier

Request Body schema:
required

The new OptionSet resource

orderedValueIds
required
Array of strings

Responses

Request samples

Content type
{
  • "orderedValueIds": [
    ]
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Sizes",
  • "description": "Standard apparel sizes",
  • "code": "sizes",
  • "valueType": "text",
  • "displayOrder": "manual",
  • "status": "active",
  • "values": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Remove an allowed value

Remove an allowed value

Authorizations:
Bearer
path Parameters
valueId
required
string

The option set value id to remove

id
required
string

OptionSet identifier

Responses

Update an allowed value

Update an allowed value

Authorizations:
Bearer
path Parameters
valueId
required
string

The option set value id to update

id
required
string

OptionSet identifier

Request Body schema: application/merge-patch+json
required

The updated OptionSet resource

label
string or null [ 1 .. 255 ] characters
code
string or null [ 1 .. 64 ] characters
swatchColor
string or null^(#[0-9A-Fa-f]{6})$

Responses

Request samples

Content type
application/merge-patch+json
{
  • "label": "string",
  • "code": "string",
  • "swatchColor": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Sizes",
  • "description": "Standard apparel sizes",
  • "code": "sizes",
  • "valueType": "text",
  • "displayOrder": "manual",
  • "status": "active",
  • "values": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Catalog - Product Associations

Represents a directed, typed association between two catalog records (referenced by opaque ResourceUri) — related / cross-sell / up-sell / bundle (catalog.md §4.9). quantity is a bundle component count; bundle EXPLOSION into SkuBindings is a fulfilment-side read and is out of scope here.

Link two products with a typed association

Creates a directed association keyed on (fromRef, toRef, type). Linking the same triple twice returns 409 (DUPLICATE).

Authorizations:
Bearer
Request Body schema:
required

The new ProductAssociation resource

fromRef
required
string [ 1 .. 512 ] characters
toRef
required
string [ 1 .. 512 ] characters
type
required
string
Enum: "related" "cross_sell" "up_sell" "bundle"
quantity
integer or null > 0

Responses

Request samples

Content type
{
  • "fromRef": "string",
  • "toRef": "string",
  • "type": "related",
  • "quantity": 0
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "fromRef": "glacia:///catalog/products/01912345-6789-7abc-def0-123456789abc",
  • "toRef": "glacia:///catalog/variants/01912345-6789-7abc-def0-123456789abc",
  • "type": "cross_sell",
  • "quantity": 2,
  • "createdAt": "string",
  • "updatedAt": "string"
}

List the associations a product points to

List the associations a product points to

Authorizations:
Bearer
query Parameters
productRef
required
string

The source product's opaque ResourceUri

type
string

Optional AssociationType filter (related, cross_sell, up_sell, bundle)

page
integer
Default: 1

The collection page number

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Get a product association

Get a product association

Authorizations:
Bearer
path Parameters
id
required
string

ProductAssociation identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "fromRef": "glacia:///catalog/products/01912345-6789-7abc-def0-123456789abc",
  • "toRef": "glacia:///catalog/variants/01912345-6789-7abc-def0-123456789abc",
  • "type": "cross_sell",
  • "quantity": 2,
  • "createdAt": "string",
  • "updatedAt": "string"
}

Remove a product association

Remove a product association

Authorizations:
Bearer
path Parameters
id
required
string

ProductAssociation identifier

Responses

Catalog - Product Categories

Represents a Product↔Category assignment — a single membership of a Product (referenced by opaque ResourceUri) in a taxonomy node (catalog.md §4.1).

List product-category assignments

Filter by categoryId (products in a category) and/or productId (a product's categories).

Authorizations:
Bearer
query Parameters
categoryId
string

Filter to a category

productId
string

Filter to a product's opaque ResourceUri

page
integer >= 1
Default: 1

Page number for pagination

itemsPerPage
integer [ 1 .. 100 ]
Default: 20

Number of items per page

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Assign a product to a category

Idempotent upsert keyed on productId + categoryId.

Authorizations:
Bearer
Request Body schema:
required

The new ProductCategoryAssignment resource

productId
required
string [ 1 .. 512 ] characters
categoryId
required
string [ 1 .. 255 ] characters

Responses

Request samples

Content type
{
  • "productId": "string",
  • "categoryId": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "productId": "01912345-6789-7abc-def0-123456789abc",
  • "categoryId": "string",
  • "categoryName": "Apparel",
  • "categoryCode": "apparel",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Get a product-category assignment

Get a product-category assignment

Authorizations:
Bearer
path Parameters
id
required
string

ProductCategoryAssignment identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "productId": "01912345-6789-7abc-def0-123456789abc",
  • "categoryId": "string",
  • "categoryName": "Apparel",
  • "categoryCode": "apparel",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Remove a product from a category

Remove a product from a category

Authorizations:
Bearer
path Parameters
id
required
string

ProductCategoryAssignment identifier

Responses

Catalog - Product

A Product View channel-sync card: the product's sync enablement on one sales channel, plus whether it is eligible to sync (syncable) and — when it is not — the human-readable reasons.

syncable/reasons are channel-agnostic in v1 (sourced from the product's publication readiness). The UI renders a card per channel with an enable/disable switch that is disabled-with-reason when syncable is false; enabling a non-syncable product is also rejected server-side.

List a product's per-channel sync cards

One card per sales channel for the product: current sync enablement, whether the product is syncable, and — if not — why.

Authorizations:
Bearer
query Parameters
productId
required
string

The product id

page
integer
Default: 1

The collection page number

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Enable or disable a product on a sales channel

Toggles the product's sync enablement on the channel and returns the refreshed card. Enabling a non-syncable product is rejected with 409 INCOMPLETE_FOR_PUBLICATION.

Authorizations:
Bearer
Request Body schema:
required

The new ProductChannelSyncCard resource

productId
required
string
channelId
required
string
enabled
boolean
Default: false

Responses

Request samples

Content type
{
  • "productId": "string",
  • "channelId": "string",
  • "enabled": false
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "channelId": "01912345-6789-7abc-def0-123456789abc",
  • "channelName": "Nimbus Store",
  • "enabled": true,
  • "syncable": false,
  • "reasons": [
    ]
}

Catalog - Product Tags

Represents a Product↔Tag assignment — a single application of a Tag to a Product (referenced by opaque ResourceUri) (catalog.md §4.3). The read of "which tags does a product carry" lives on the Tag resource (GET /catalog/tags/for-product).

Apply a tag to a product

Idempotent upsert keyed on productId + tagId.

Authorizations:
Bearer
Request Body schema:
required

The new ProductTagAssignment resource

productId
required
string [ 1 .. 512 ] characters
tagId
required
string [ 1 .. 255 ] characters

Responses

Request samples

Content type
{
  • "productId": "string",
  • "tagId": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "productId": "01912345-6789-7abc-def0-123456789abc",
  • "tagId": "string",
  • "tagName": "Clearance",
  • "tagCode": "clearance",
  • "tagColor": "#FF8800",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Get a product-tag assignment

Get a product-tag assignment

Authorizations:
Bearer
path Parameters
id
required
string

ProductTagAssignment identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "productId": "01912345-6789-7abc-def0-123456789abc",
  • "tagId": "string",
  • "tagName": "Clearance",
  • "tagCode": "clearance",
  • "tagColor": "#FF8800",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Remove a tag from a product

Remove a tag from a product

Authorizations:
Bearer
path Parameters
id
required
string

ProductTagAssignment identifier

Responses

Catalog - Variant Axes

A Product's variant-defining axes (Phase 3-A) — the ordered OptionSets whose Cartesian value combination generates the Product's Variants. Keyed by the owning Product; every operation nests under /catalog/products/{productId}.

Get a product's variant axes

The ordered OptionSets selected as variant axes, each resolved to its values (the variant matrix is their Cartesian product).

Authorizations:
Bearer
path Parameters
productId
required
string

The owning Product id

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "productId": "string",
  • "axes": [
    ]
}

Attach an OptionSet as a variant axis

Select an existing OptionSet as a variant-defining axis. An OptionSet can be attached at most once; order of attachment sets the matrix column order.

Authorizations:
Bearer
path Parameters
productId
required
string

ProductVariantAxes identifier

Request Body schema:
required

The new ProductVariantAxes resource

optionSetId
required
string [ 1 .. 64 ] characters

Responses

Request samples

Content type
{
  • "optionSetId": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "productId": "string",
  • "axes": [
    ]
}

Reorder a product's variant axes

Reorder the axes; the payload must be a full permutation of the current axes.

Authorizations:
Bearer
path Parameters
productId
required
string

ProductVariantAxes identifier

Request Body schema:
required

The new ProductVariantAxes resource

orderedOptionSetIds
required
Array of strings

Responses

Request samples

Content type
{
  • "orderedOptionSetIds": [
    ]
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "productId": "string",
  • "axes": [
    ]
}

Detach a variant axis

Remove an OptionSet from the variant axes. Rejected while any existing Variant still uses the axis.

Authorizations:
Bearer
path Parameters
optionSetId
required
string

The OptionSet id to detach

productId
required
string

ProductVariantAxes identifier

Responses

Catalog - SKU Bindings

Represents a catalog SKU binding — the explicit link between a Variant and a per-principal InventoryItem (referenced by opaque ResourceUri).

List all catalog SKU bindings

Retrieve a paginated list of SKU bindings, optionally filtered by variant (items-for-variant) or item (variant-for-item).

Authorizations:
Bearer
query Parameters
variantRef
string <uuid>
Example: variantRef=01912345-6789-7abc-def0-123456789abc

Filter by bound Variant id (items-for-variant)

itemId
string <uuid>
Example: itemId=01912345-6789-7abc-def0-123456789abc

Filter by bound InventoryItem id (variant-for-item)

principalRef
string
Example: principalRef=glacia:///inventory/principals/01912345-6789-7abc-def0-123456789abc

Filter by owning Principal ResourceUri

page
integer >= 1
Default: 1
Example: page=1

Page number for pagination

itemsPerPage
integer [ 1 .. 100 ]
Default: 20
Example: itemsPerPage=20

Number of items per page

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Create a catalog SKU binding

Bind a per-principal InventoryItem (opaque ResourceUri) to an existing Catalog Variant.

Authorizations:
Bearer
Request Body schema: application/json
required

SKU binding creation data

itemId
required
string <uuid>
variantRef
required
string <uuid>
principalRef
required
string

Responses

Request samples

Content type
application/json
{
  • "itemId": "01912345-6789-7abc-def0-123456789abc",
  • "variantRef": "01912345-6789-7abc-def0-123456789abc",
  • "principalRef": "glacia:///inventory/principals/01912345-6789-7abc-def0-123456789abc"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "itemId": "01912345-6789-7abc-def0-123456789abc",
  • "variantRef": "01912345-6789-7abc-def0-123456789abc",
  • "principalRef": "glacia:///inventory/principals/01912345-6789-7abc-def0-123456789abc",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Get a catalog SKU binding

Retrieve a single SKU binding by its UUID.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

SKU binding UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "itemId": "01912345-6789-7abc-def0-123456789abc",
  • "variantRef": "01912345-6789-7abc-def0-123456789abc",
  • "principalRef": "glacia:///inventory/principals/01912345-6789-7abc-def0-123456789abc",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Remove a catalog SKU binding

Retire a SKU binding (e.g. rebinding the Item to a different Variant).

Authorizations:
Bearer
path Parameters
id
required
string

SkuBinding identifier

Responses

Catalog - Tags

Represents a catalog tag — a free-form, tenant-scoped label applied to Products (catalog.md §4.3). Products carry tags via the ProductTagAssignment resource. Tags can be MERGED into one another.

List catalog tags

List catalog tags

Authorizations:
Bearer
query Parameters
status
string
Enum: "active" "archived"

Filter by status

search
string

Search by name or code

page
integer >= 1
Default: 1

Page number for pagination

itemsPerPage
integer [ 1 .. 200 ]
Default: 50

Number of items per page

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Create a catalog tag

Create a catalog tag

Authorizations:
Bearer
Request Body schema:
required

The new Tag resource

name
required
string [ 1 .. 255 ] characters
code
string or null <= 64 characters
color
string or null^(#[0-9A-Fa-f]{6})$

Responses

Request samples

Content type
{
  • "name": "string",
  • "code": "string",
  • "color": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Clearance",
  • "code": "clearance",
  • "color": "#FF8800",
  • "status": "active",
  • "createdAt": "string",
  • "updatedAt": "string"
}

List the tags a product carries

List the tags a product carries

Authorizations:
Bearer
query Parameters
productId
required
string

The product's opaque ResourceUri

page
integer
Default: 1

The collection page number

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Get a catalog tag

Get a catalog tag

Authorizations:
Bearer
path Parameters
id
required
string

Tag identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Clearance",
  • "code": "clearance",
  • "color": "#FF8800",
  • "status": "active",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Rename a catalog tag

Rename a catalog tag

Authorizations:
Bearer
path Parameters
id
required
string

Tag identifier

Request Body schema: application/merge-patch+json
required

The updated Tag resource

name
string [ 1 .. 255 ] characters

Responses

Request samples

Content type
application/merge-patch+json
{
  • "name": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Clearance",
  • "code": "clearance",
  • "color": "#FF8800",
  • "status": "active",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Archive a catalog tag

Archive a catalog tag

Authorizations:
Bearer
path Parameters
id
required
string

Tag identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Clearance",
  • "code": "clearance",
  • "color": "#FF8800",
  • "status": "active",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Merge source tags into this tag

Re-points every product assignment from the source tags to this target then archives the sources.

Authorizations:
Bearer
path Parameters
id
required
string

Tag identifier

Request Body schema:
required

The new Tag resource

sourceTagIds
required
Array of strings non-empty

Responses

Request samples

Content type
{
  • "sourceTagIds": [
    ]
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Clearance",
  • "code": "clearance",
  • "color": "#FF8800",
  • "status": "active",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Reactivate a catalog tag

Reactivate a catalog tag

Authorizations:
Bearer
path Parameters
id
required
string

Tag identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Clearance",
  • "code": "clearance",
  • "color": "#FF8800",
  • "status": "active",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Recolour a catalog tag

Set or clear the chip colour (null color clears it).

Authorizations:
Bearer
path Parameters
id
required
string

Tag identifier

Request Body schema:
required

The new Tag resource

color
string or null^(#[0-9A-Fa-f]{6})$

Responses

Request samples

Content type
{
  • "color": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "Clearance",
  • "code": "clearance",
  • "color": "#FF8800",
  • "status": "active",
  • "createdAt": "string",
  • "updatedAt": "string"
}