taxons

The taxons query allows you to return the categorization hierarchy, or Taxonomy as it’s referred to in Marketplacer.

2 minute read

Key Information

Use-Case

The categorization hierarchy defines both where products sit, and what attributes those products have, (via Prototypes). There are a number of use cases for using the taxonomy query, but perhaps the most common one would be so that Sellers can create products correctly in Marketplacer when using the API (products will be considered invalid if they have not been created with a valid category / taxon).

Further Points of Note

Taxons are hierarchical, in that they can recursively have children.
To ensure you query all descendants for a given taxon, you need to ensure you query the children at each layer, an example querying a 5 level taxonomy is shown below
From a usability perspective, categorization hierarchies (taxonomies) with a depth greater than 5 are sum-optimal and should be avoided

Availability

Operator API: Yes
Seller API: Yes

Example

query getCategoriesToADepthOf5{
  taxons(first: 100, after: null) {
    totalCount
    pageInfo {
      endCursor
      hasNextPage
    }
    nodes {
      id
      displayName
      treeName
      prototype {
        name
        id
      }
      children {
        nodes {
          id
          displayName
          treeName
          prototype {
            name
            id
          }
          children {
            nodes {
              id
              displayName
              treeName
              prototype {
                name
                id
              }
              children {
                nodes {
                  id
                  displayName
                  treeName
                  prototype {
                    name
                    id
                  }
                  children {
                    nodes {
                      id
                      displayName
                      treeName
                      prototype {
                        name
                        id
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Arguments

Name	Type	Description
parentId	ID	Return only taxons with a given Parent Id
showOnlineOnly	Boolean	Return taxons that are related only to online Products
after	String	Pagination cursor for moving through result set - more on pagination here
before	String	Not in use - backwards pagination not supported
first	Int	Pagination page size - more on pagination here
last	Int	Not in use - backwards pagination not supported

Response

Returns TaxonsConnection

Error Responses

HTTP Error	Error Message	Meaning
401	Unauthorized	You don’t have access to the endpoint, likely Basic Authentication credentials are missing
401	API Token has expired	You don’t have access to the endpoint, likely that you are either not supplying an API Key, or the key you are supplying is invalid