Back to Arky

Taxonomies

Organize content with hierarchical categories and filterable attributes

Taxonomies provide hierarchical categorization for products, services, providers, and other filterable store records. Each taxonomy defines a schema of filterable fields that can then be attached as TaxonomyEntry values. CMS collections and entries use schemas and blocks for content, while taxonomies stay responsible for classification and filtering.

Create Taxonomy

POST /v1/stores/{storeId}/taxonomies
SDK: sdk.cms.taxonomy.create() 
const taxonomy = await sdk.cms.taxonomy.create({
  key: 'product-attributes',
  schema: [
    { type: 'text', id: 'fld_color', key: 'color', value: ['red', 'blue', 'green'] },
    { type: 'text', id: 'fld_size', key: 'size', value: ['S', 'M', 'L'] },
    { type: 'number', id: 'fld_weight', key: 'weight', min: 0, max: 100 },
  ],
});

// Create a child taxonomy
const child = await sdk.cms.taxonomy.create({
  key: 'electronics',
  parent_id: taxonomy.id,
  schema: [
    { type: 'boolean', id: 'fld_wireless', key: 'wireless' },
  ],
});

Parameters

Name Type Description
key required string Unique taxonomy identifier
parent_id optional string | null Parent taxonomy ID for nesting
schema optional TaxonomySchema[] Filterable field definitions

Schema Field Types

TypeExtra options
textvalue: string[] (allowed values), min
numbermin, max
boolean—
geo_location—

Response

{
  "id": "tax_abc123",
  "key": "product-attributes",
  "store_id": "store_123",
  "parent_id": null,
  "schema": [
    { "type": "text", "id": "fld_color", "key": "color", "value": ["red", "blue", "green"] }
  ],
  "status": "active",
  "created_at": 1704067200,
  "updated_at": 1704067200
}

Get Taxonomy

GET /v1/stores/{storeId}/taxonomies/{id}
SDK: sdk.cms.taxonomy.get()

Retrieve a taxonomy by ID or key.

// By ID
const taxonomy = await sdk.cms.taxonomy.get({ id: 'tax_abc123' });

// By key
const taxonomy = await sdk.cms.taxonomy.get({ key: 'product-attributes' });

List Taxonomies

GET /v1/stores/{storeId}/taxonomies
SDK: sdk.cms.taxonomy.find() 
const { items, cursor } = await sdk.cms.taxonomy.find({
  status: 'active',
  limit: 50,
});

Parameters

Name Type Description
parent_id optional string Filter by parent taxonomy
query optional string Search in taxonomy keys
key optional string Filter by exact key
ids optional string[] Filter by specific taxonomy IDs
status optional string Filter by status
limit optional number Items per page
cursor optional string Pagination cursor
sort_field optional string Sort field
sort_direction optional asc | desc Sort direction
created_at_from optional number Filter by creation date (start)
created_at_to optional number Filter by creation date (end)

Get Taxonomy Children

GET /v1/stores/{storeId}/taxonomies/{id}/children
SDK: sdk.cms.taxonomy.getChildren()

Get direct children of a taxonomy.

const children = await sdk.cms.taxonomy.getChildren({ id: 'tax_abc123' });

Parameters

Name Type Description
id required string Parent taxonomy ID

Update Taxonomy

PUT /v1/stores/{storeId}/taxonomies/{id}
SDK: sdk.cms.taxonomy.update() 
await sdk.cms.taxonomy.update({
  id: 'tax_abc123',
  schema: [
    { type: 'text', id: 'fld_color', key: 'color', value: ['red', 'blue', 'green', 'black'] },
    { type: 'text', id: 'fld_size', key: 'size', value: ['XS', 'S', 'M', 'L', 'XL'] },
    { type: 'text', id: 'fld_material', key: 'material', value: ['cotton', 'wool'] },
  ],
});

Parameters

Name Type Description
id required string Taxonomy ID
key optional string Updated key
parent_id optional string | null Move to new parent
schema optional TaxonomySchema[] Updated filter schema
status optional ACTIVE | ARCHIVED Updated status

Delete Taxonomy

DELETE /v1/stores/{storeId}/taxonomies/{id}
SDK: sdk.cms.taxonomy.delete()

Deletes the taxonomy and all its children. Removes taxonomy references from products, services, providers, and other records that use it.

await sdk.cms.taxonomy.delete({ id: 'tax_abc123' });
Warning

Deleting a taxonomy cascades to all child taxonomies and removes references from products, services, providers, and other records that use it.

Attaching a Taxonomy to Content

Once a taxonomy is defined, attach it to a product, service, or provider via a TaxonomyEntry:

await sdk.eshop.product.update({
  id: 'prod_xyz789',
  taxonomies: [
    {
      taxonomy_id: 'tax_abc123',
      fields: [
        { type: 'text', id: 'fld_color', key: 'color', value: ['red'] },
        { type: 'text', id: 'fld_size', key: 'size', value: ['M'] },
      ],
    },
  ],
});