taxons

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

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

NameTypeDescription
parentIdIDReturn only taxons with a given Parent Id
showOnlineOnlyBooleanReturn taxons that are related only to online Products
afterStringPagination cursor for moving through result set - more on pagination here
beforeStringNot in use - backwards pagination not supported
firstIntPagination page size - more on pagination here
lastIntNot in use - backwards pagination not supported

Response

Returns TaxonsConnection


Error Responses

HTTP ErrorError MessageMeaning
401UnauthorizedYou don’t have access to the endpoint, likely Basic Authentication credentials are missing
401API Token has expiredYou 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

Further Reading