Taxonomy

Taxonomy allows you to categorize content within your stack, making it easier to navigate, search, and retrieve information. You can organize your web properties hierarchically based on factors such as purpose, audience, or business function.

Taxonomies support localization, ensuring consistent classification across locales. Use advanced querying options, such as filtering, sorting, and typeahead search, for precise retrieval by locale, branch, or fallback hierarchy.

create

The create method lets you create a new taxonomy in your stack.

import * as contentstack from '@contentstack/management'

const client = contentstack.client()

const taxonomy = {

	uid: 'taxonomy_testing1',

	name: 'taxonomy testing',

	description: 'Description for Taxonomy testing'

}

client.stack({ api_key: 'api_key'}).taxonomy().create({taxonomy})

.then((taxonomy) => console.log(taxonomy))

fetch

The fetch method retrieves a specific taxonomy term along with organization and taxonomy-level metadata, based on the provided parameters.

Name	Type	Description
locale	string	Specifies the locale used to fetch the taxonomy. Defaults to master if not provided. Default: master
branch	string	Specifies the branch whose fallback locale hierarchy is followed when include_fallback is enabled.
include_fallback	boolean	Specifies a single fallback locale if the taxonomy isn’t available in the requested locale. See Locale Fallback Behavior for precedence rules.
fallback_locale	string	Specifies the locale to fallback to if the taxonomy doesn’t exist in the given locale. Gives priority to include_fallback if both are specified.
include_terms_count	boolean	Includes the total count of all terms within the taxonomy.
include_referenced_terms_count	boolean	Includes the count of terms that are referenced in at least one entry.
include_referenced_content_type_count	boolean	Includes the count of content types that reference this taxonomy.
include_referenced_entries_count	boolean	Includes the count of entries where at least one term of this taxonomy is referenced.
deleted	boolean	Fetches only the taxonomies that are marked as deleted.
taxonomy_uid (required)	string	UUID of a deleted taxonomy used to retrieve its data (required when deleted is set to true).

import * as contentstack from '@contentstack/management'
const client = contentstack.client()
client.stack({ api_key: 'api_key'}).taxonomy('taxonomyUid').terms('termUid').fetch().then((term) => console.log(term))

Locale Fallback Behavior

When using include_fallback and fallback_locale, the system applies the following behavior:

Scenario	Parameters	Behavior
Follow branch fallback hierarchy	include_fallback: true, branch: 'main'	Follows the branch’s configured fallback locale hierarchy.
Fall back to a single specific locale	fallback_locale: 'en-us'	Falls back only to the specified locale.
Both specified	include_fallback: true + fallback_locale	include_fallback takes priority. fallback_locale is ignored.

Note The SDK forwards both parameters as query parameters. The backend API applies the fallback resolution logic and precedence.

Example: Using Fallback Parameters

client
  .stack({ api_key: 'api_key' })
  .taxonomy('taxonomyUid')
  .terms('termUid')
  .fetch({
    locale: 'hi-in',
    branch: 'main',
    include_fallback: true,
    fallback_locale: 'en-us'
  })
  .then((term) => console.log(term))

In the above example, both parameters are provided, the backend API prioritizes include_fallback and ignores fallback_locale.

query

The query() method fetches all taxonomies or returns filtered results based on the provided query parameters.

Name	Type	Description
locale	string	Specifies the locale used to fetch the taxonomies. Defaults to master if not provided. Default: master
branch	string	Specifies the branch whose fallback locale hierarchy is followed when include_fallback is enabled.
include_fallback	boolean	Enables taxonomies to follow the fallback locale hierarchy (of the given branch or main) if not found in the specified locale.
fallback_locale	string	Specifies the fallback locale if the taxonomy term isn’t available in the given locale. If both fallback_locale and include_fallback are specified, the system uses include_fallback.
include_terms_count	boolean	Includes the total count of all terms within the taxonomy.
include_referenced_terms_count	boolean	Includes the count of terms that are referenced in at least one entry.
include_referenced_content_type_count	boolean	Includes the count of content types that reference this taxonomy.
include_referenced_entries_count	boolean	Includes the count of entries where at least one term of this taxonomy is referenced.
include_count	boolean	Includes the count of documents or nodes that match the query.
asc\|desc	string	Sorts the given field in ascending (asc) or descending (desc) order.
query	string	Defines a custom query in string format. Currently restricted to querying by uid.
typeahead	string	Matches the given string across all taxonomies and returns the matched results.
deleted	boolean	Fetches only the taxonomies that are marked as deleted.
skip	number	Specifies the number of documents or nodes to skip.
limit	number	Limits the result to a specific number of documents or nodes.

import * as contentstack from '@contentstack/management'
const client = contentstack.client()
client
  .stack({ api_key: 'api_key' })
  .taxonomy()
  .query()
  .find()
  .then((result) => {
    console.log(result.items)   // Array of Taxonomy objects
    console.log(result.count)   // Total count (when include_count: true is used)
  })
  .catch((error) => console.error(error))

The find() method returns a collection with:

items: An array of matched taxonomies.
count: The total number of matched taxonomies when include_count: true is provided (otherwise, the API may not populate it).

update

The update method lets you update an existing taxonomy in your stack.

Name	Type	Description
taxonomyUid (required)	string	UID of the taxonomy

import * as contentstack from '@contentstack/management'

const client = contentstack.client()

client.stack({ api_key: 'api_key'}).taxonomy('taxonomyUid').fetch() .then((taxonomy) => {

	taxonomy.name = 'taxonomy name'

	return taxonomy.update()

})

.then((taxonomy) => console.log(taxonomy))

delete

The delete method lets you remove an existing taxonomy from the stack.

Name	Type	Description
taxonomyUid (required)	string	UID of the taxonomy
force	boolean	Setting this to true will force delete the taxonomy and all its child terms. By default it is set to false.

import * as contentstack from '@contentstack/management'

const client = contentstack.client()

client.stack({ api_key: 'api_key'}).taxonomy('taxonomyUid').delete().then((taxonomy) => console.log(taxonomy))

locales

The locales() method retrieves a list of all locales where a specific taxonomy is localized.

const taxonomyLocales = await client.stack({ api_key: 'your_api_key' })

.taxonomy('taxonomy_uid')

.locales()

localize

The localize() method creates a localized version of a taxonomy in the specified locale.

Name	Type	Description
data	Object	Returns the updated localized taxonomy details.
params.locale	string	Target locale code (e.g., 'hi-in', 'fr-fr').

const localizedTaxonomy = await client.stack({ api_key: 'your_api_key' })
  .taxonomy('taxonomy_uid')
  .localize(
    { taxonomy: { name: 'Localized Taxonomy Name' } },
    { locale: 'hi-in' }
  )

publish

The publish method initiates a job to publish a taxonomy and/or specific taxonomy terms to the specified environments and locales.

Name	Type	Description
api_version	string	Pass "3.2" to enable enhanced logic for the publish taxonomy operation.
details	object	Specifies publish details (locales, environments, and items such as entries/assets).

Note Taxonomy publishing is supported only with api_version: "3.2". If api_version is omitted, taxonomy publishing is not available.

Publish Payload Behavior

uid refers to the UID of the taxonomy.
term_uid refers to the UID of a specific term within that taxonomy.
If only uid is provided, the entire taxonomy is published.
If both uid and term_uid are provided, only the specified term is published.
You can include a mix of taxonomy-only (uid) and taxonomy-term (uid + term_uid) objects within the same items array.

Example

import * as contentstack from '@contentstack/management'
const client = contentstack.client()
const publishData = {
  locales: ['en-us'],
  environments: ['development'],
  items: [
    { uid: 'taxonomy_testing', term_uid: 'vehicles' },
    { uid: 'taxonomy_testing', term_uid: 'cars' }
  ]
}

client.stack({ api_key: 'api_key' })
  .taxonomy('taxonomy_testing')
  .publish(publishData, '3.2')
  .then((response) => console.log(response))
  .catch((err) => console.error(err))