--- title: "Taxonomy" description: "Taxonomy" url: "https://www.contentstack.com/docs/developers/sdks/content-management-sdk/javascript/reference/taxonomy" product: "Contentstack" doc_type: "guide" audience: - developers - admins version: "current" last_updated: "2026-09-06" --- # Taxonomy ## 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. ``` 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: ScenarioParametersBehaviorFollow branch fallback hierarchyinclude_fallback: true, branch: 'main'Follows the branch’s configured fallback locale hierarchy.Fall back to a single specific localefallback_locale: 'en-us'Falls back only to the specified locale.Both specifiedinclude_fallback: true + fallback_localeinclude_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. ``` Specifies the locale used to fetch the taxonomy. Defaults to master if not provided. Specifies the branch whose fallback locale hierarchy is followed when include\_fallback is enabled. Specifies a single fallback locale if the taxonomy isn’t available in the requested locale. See Locale Fallback Behavior for precedence rules. 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. Includes the total count of all terms within the taxonomy. Includes the count of terms that are referenced in at least one entry. Includes the count of content types that reference this taxonomy. Includes the count of entries where at least one term of this taxonomy is referenced. Fetches only the taxonomies that are marked as deleted. UUID of a deleted taxonomy used to retrieve its data (required when deleted is set to true). ## query The query() method fetches all taxonomies or returns filtered results based on the provided query parameters. ``` 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). ``` Specifies the locale used to fetch the taxonomies. Defaults to master if not provided. Specifies the branch whose fallback locale hierarchy is followed when include\_fallback is enabled. Enables taxonomies to follow the fallback locale hierarchy (of the given branch or main) if not found in the specified locale. 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. Includes the total count of all terms within the taxonomy. Includes the count of terms that are referenced in at least one entry. Includes the count of content types that reference this taxonomy. Includes the count of entries where at least one term of this taxonomy is referenced. Includes the count of documents or nodes that match the query. Sorts the given field in ascending (asc) or descending (desc) order. Defines a custom query in string format. Currently restricted to querying by uid. Matches the given string across all taxonomies and returns the matched results. Fetches only the taxonomies that are marked as deleted. Specifies the number of documents or nodes to skip. Limits the result to a specific number of documents or nodes. ## update The update method lets you update an existing taxonomy in your stack. ``` 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)) ``` UID of the taxonomy ## delete The delete method lets you remove an existing taxonomy from the stack. ``` import * as contentstack from '@contentstack/management' const client = contentstack.client() client.stack({ api_key: 'api_key'}).taxonomy('taxonomyUid').delete().then((taxonomy) => console.log(taxonomy)) ``` UID of the taxonomy Setting this to true will force delete the taxonomy and all its child terms. By default it is set to false. ## 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. ``` const localizedTaxonomy = await client.stack({ api_key: 'your_api_key' }) .taxonomy('taxonomy_uid') .localize( { taxonomy: { name: 'Localized Taxonomy Name' } }, { locale: 'hi-in' } ) ``` Returns the updated localized taxonomy details. Target locale code (e.g., 'hi-in', 'fr-fr'). ## publish The publish method initiates a job to publish a taxonomy and/or specific taxonomy terms to the specified environments and locales. ``` Note: Taxonomy publishing is supported only with api_version: "3.2". If api_version is omitted, taxonomy publishing is not available. Publish Payload Behavioruid 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.Exampleimport * 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)) ``` Pass "3.2" to enable enhanced logic for the publish taxonomy operation. Specifies publish details (locales, environments, and items such as entries/assets). ## Taxonomy | JavaScript Management SDK | Contentstack Taxonomy lets you categorize and hierarchically organize content for easy search and retrieval, in the JavaScript Management SDK.