Terms

The Terms REST API endpoint is part of the WooCommerce Product Search extension.

Provide all taxonomy terms or those that match a specified set of search and filter constraints.

HTTP Request

GET /wp-json/wps/v1/terms

Parameters

The endpoint allows to specify the parameters described below.

Parameter	Type	Description
`taxonomy`	string	The product taxonomy (or taxonomies separated by comma) whose terms to retrieve for the current context.
`except`	string	Except the product taxonomy (or taxonomies separated by comma) from restricting the current context.
`orderby`	string	Sort terms by indicated option. Options: `''` (the empty string), `id`, `term_id`, `menu_order` or `order` (they are synonymous), `name`, `slug` and `count`. Default is `order`.
`order`	string	Sort order. Options: `asc` and `desc`. Default is `asc`.
`hide_empty`	boolean	Omit terms which have no products that match the current context. Default is `true`.
`sum_counts`	boolean	Provide sum of child counts for parent terms. Default is `true`.
`include`	string \| array	Restrict the result set to particular terms given by their ids.
`exclude`	string \| array	Exclude particular terms given by their ids from the result set.
In addition to the particular parameters of this endpoint, as listed above, it also supports most of the parameters of the `/wp-json/wps/v1/products` endpoint.		The `terms` endpoint provides terms based on its particular parameters and the defaults of the `products` endpoint. The parameters of the `products` endpoint can be used to request data that matches a specified set of search and filter constraints. Pagination and sorting parameters for products are not considered. For example, the `orderby` parameter applies to the terms that this endpoint provides as results, it does not apply to the matching products as that would be irrelevant to the results. See the description of parameters on the REST API – Products documentation page.

The response to a request to the terms endpoint will contain detailed term data for all terms that match the requested parameters. By default, this will include data for all relevant product taxonomies, the result set can be constrained to terms of one or more taxonomies using the request parameters accordingly.

Here is an example response to a request /wp-json/wps/v1/terms based on the defaults. The example has two additional taxonomies used for variations, Color and Size. A single term data set is shown for each taxonomy product_cat, product_tag, pa_size and pa_color and additional entries that would be included have been omitted for clarity. This data provided for terms is also included with the shop endpoint in the corresponding section of its JSON response. See the section REST API – Shop for details in its example.

[
  {
    "id": 19,
    "parent": null,
    "taxonomy": "pa_color",
    "name": "Multicolor",
    "slug": "multicolor",
    "permalink": "https://example.com/?taxonomy=pa_color&term=multicolor",
    "description": "",
    "count": 1,
    "images": [],
    "menu_order": 0,
    "match": true,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wps/v1/terms?taxonomy=pa_color&include=19&hide_empty=false"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wps/v1/terms?taxonomy=pa_color"
        }
      ]
    }
  },
  ... (further terms of the pa_color taxonomy omitted)
  {
    "id": 43,
    "parent": null,
    "taxonomy": "pa_size",
    "name": "XXS",
    "slug": "xxs",
    "permalink": "https://example.com/?taxonomy=pa_size&term=xxs",
    "description": "",
    "count": 2,
    "images": [],
    "menu_order": 0,
    "match": true,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wps/v1/terms?taxonomy=pa_size&include=43&hide_empty=false"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wps/v1/terms?taxonomy=pa_size"
        }
      ]
    }
  },
  ... (further terms of the pa_size taxonomy omitted)
  {
    "id": 89,
    "parent": null,
    "taxonomy": "product_tag",
    "name": "test",
    "slug": "test",
    "permalink": "https://example.com/product-tag/test/",
    "description": "",
    "count": 2,
    "images": [],
    "menu_order": 0,
    "match": true,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wps/v1/terms?taxonomy=product_tag&include=89&hide_empty=false"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wps/v1/terms?taxonomy=product_tag"
        }
      ]
    }
  },
  ... (further terms of the product_tag taxonomy omitted)
  {
    "id": 72,
    "parent": null,
    "taxonomy": "product_cat",
    "name": "Men",
    "slug": "men",
    "permalink": "https://example.com/product-category/men/",
    "description": "",
    "count": 22,
    "images": [],
    "menu_order": 3,
    "match": true,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wps/v1/terms?taxonomy=product_cat&include=72&hide_empty=false"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wps/v1/terms?taxonomy=product_cat"
        }
      ]
    }
  },
  {
    "id": 74,
    "parent": 72,
    "taxonomy": "product_cat",
    "name": "Pants",
    "slug": "pants-men",
    "permalink": "https://example.com/product-category/men/pants-men/",
    "description": "",
    "count": 5,
    "images": [],
    "menu_order": 4,
    "match": true,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wps/v1/terms?taxonomy=product_cat&include=74&hide_empty=false"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wps/v1/terms?taxonomy=product_cat"
        }
      ],
      "up": [
        {
          "href": "https://example.com/wp-json/wps/v1/terms?taxonomy=product_cat&include=72&hide_empty=false"
        }
      ]
    }
  },
  ... (further terms of the product_cat taxonomy omitted)
]

This and related sections will be further enhanced with information and examples shortly. If you are a developer and have questions on the use of the REST API for your components or App, you can reach out and Contact Support for the extension.