Terms

Terms are the foundational elements of a taxonomy. They define hierarchical structure and help organize content systematically within a stack.

Terms support localization, allowing you to manage translated or region-specific versions across multiple locales. This ensures each term accurately reflects language and regional variations.

Note In the JavaScript Management SDK, term-related operations are accessed using .terms() (plural). This differs from the Delivery SDK, which uses .term() (singular) for term-level methods.

create

The create method lets you add a new term to your taxonomy.

import * as contentstack from '@contentstack/management'

const client = contentstack.client()

const term = {

	uid: 'termUid',

	name: 'term name',

	parent_uid: 'parent_uid',

	order: 2

}

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

terms().create(term)

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

fetch

The fetch() method retrieves details of a specific term along with organization metadata.

Name	Type	Description
locale	string	Specifies the locale used to fetch the term. 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	Follows the fallback locale hierarchy of the specified branch or main when the taxonomy term isn’t available in the selected locale.
fallback_locale	string	Specifies the fallback locale if the term isn’t available in the given locale. If both fallback_locale and include_fallback are provided, include_fallback takes precedence.
include_children_count	boolean	Includes the count of children under the term.
include_referenced_entries_count	boolean	Includes the count of entries where the term is referenced.
include_children_referenced_entries_count	boolean	Includes the count of entries where descendant terms are referenced.
deleted	boolean	Fetches only the terms that are marked as deleted.
taxonomy_uid	string	Specifies the UID of the taxonomy for which term data is required.
term_uid	string	Specifies the UID of the deleted term. 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));

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 terms. 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 terms 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.
depth	number	Includes terms from the root up to the specified depth. If set to 0, includes all terms. Default: 1
include_children_count	boolean	Includes the count of children under each term.
include_referenced_entries_count	boolean	Includes the count of entries where the term is referenced.
include_count	boolean	Includes the count of all documents or nodes that match the query.
include_order	boolean	Includes the order of the terms relative to their siblings.
asc\|desc	string	Sorts the specified field in ascending (asc) or descending (desc) order.
query	string	Defines a custom query string. Currently restricted to querying by uid.
typeahead	string	Matches the given string across all terms and returns the matching results.
deleted	boolean	Fetches only the terms that are marked as deleted.
skip	number	Specifies the number of documents or nodes to skip.
limit	number	Limits the result set to a specified number of documents or nodes.
taxonomy_uuid	string	Specifies the UUID of the taxonomy for which term data is required.

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

update

The update method is used to update the details of an exisiting term in the taxonomy.

import * as contentstack from '@contentstack/management'

const client = contentstack.client()

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

	term.name = 'taxonomy name'

	return term.update()

})

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

delete

The delete method lets you remove an existing term from a taxonomy.

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

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

ancestors

The ancestors method is used to retrieves the list of all the ancestors of an existing term

Name	Type	Description
termUid (required)	string	UID of the term
include_children_count	boolean	Include count of number of children under each term
include_referenced_entries_count	boolean	Include count of the entries where atleast 1 term of this taxonomy is referred
include_count	boolean	Include count of the terms that matched the query
skip	number	Skip the number of terms
limit	number	Limit the result to number of terms

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

descendants

The descendants method is used to retrieves the list of all the descendants of an existing term.

Name	Type	Description
termUid (required)	string	UID of the term
depth	number	Include the terms from the current term’s depth, upto the depth specified if set to a number greater than 0, include all the terms from the current term’s depth if set to 0, default depth will be set to 1, which will be to include the immediate terms from the current term’s depth
include_children_count	boolean	Include count of number of children under each term
include_referenced_entries_count	boolean	Include count of the entries where atleast 1 term of this taxonomy is referred
include_count	boolean	Include count of the terms that matched the query
include_order	boolean	Include order of the terms relative to their siblings
skip	number	Skip the number of terms
limit	number	Limit the result to number of terms

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

move

The move method lets you move an existing term or change the parent UID of the term.

Name	Type	Description
termUid (required)	string	UID of the term
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()

const term = {

	parent_uid: 'parent_uid',

	order: 2

}

client.stack({ api_key: 'api_key'}).taxonomy('taxonomyUid').terms('termUid').move({term})

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

search

The search method lets you search an existing term in the taxonomy.

Name	Type	Description
termUid (required)	string	UID of the term
include_children_count	boolean	Include count of number of children under each term
include_referenced_entries_count	boolean	Include count of the entries where atleast 1 term of this taxonomy is referred
include_count	boolean	Include count of the terms that matched the query
query	string	Used to give a custom query in a string format, currently restricted to only query on taxonomy_uid & term_uid
typeahead	string	Used to match the given string in all terms & return the matched result, should either match with term uid or term name
skip	number	Skip the number of terms
limit	number	Limit the result to number of terms

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

locales

The locales() method retrieves all locales in which a term is localized.

const termLocales = await client.stack({ api_key: 'your_api_key' })
  .taxonomy('taxonomy_uid')
  .terms('term_uid')
  .locales()

localize

The localize() method creates a localized version of a term.

Name	Type	Description
data.term	Object	Returns localized term properties such as name or description.
params.locale	string	Target locale code (e.g., 'hi-in', 'fr-fr').

const localizedTerm = await client.stack({ api_key: 'your_api_key' })
  .taxonomy('taxonomy_uid')
  .terms('term_uid')
  .localize(
    { term: { name: 'Localized Term Name' } },
    { locale: 'hi-in' }
  )