Taxons

Overview of the Taxon resource and associated endpoints.

  4 minute read  

Taxons in Marketplacer represent the categories for adverts in a heirarchical fashion. For instance, on Bike Exchange the “Hybrid Bikes” taxon is one of the children of the “Bikes” taxon.

Deprecations

  • 28/06/2023:
    • The relationships feature_option_types, variant_option_types, dropdown_option_types, and freetext_option_types have been deprecated in favour of option_types which contains all.
    • The option type attributes variant and feature have been deprecated in favour of applied_to and field_type.

Listing taxons

This endpoint returns all taxons.

Request

GET /api/v2/taxons

Response

Status: 200 OK
{
  "data": [
    {
      "id": 1,
      "type": "taxons",
      "attributes": {
        "name": "Hybrid Bikes",
        "tree_name": "Bikes - Hybrid Bikes",
        "slug": "hybrid-bikes"
      }
    }
  ]
}

Search for taxons

This endpoint allows you to search for a taxon by a word in its name or by a substring of its name.

Request

If you want to search for the “Hybrid Bikes” taxon, make a query like this:

GET /api/v2/taxons/search?name=Hybrid%20Bikes

If you want to search for all taxons that include the word “Hybrid”:

GET /api/v2/taxons/search?name=Hybrid

If you want to search by a substring of a word, add the autocomplete parameter, like:

GET /api/v2/taxons/search?name=Bik&autocomplete=1

If you want to get the option value information for an individual taxon, use the taxon id or slug:

GET /api/v2/taxons/4

or

GET /api/v2/taxons/bikes

Response


Status: 200 OK
{
  "data": [
    {
      "id": 1,
      "type": "taxons",
      "attributes": {
        "name": "Hybrid Bikes",
        "tree_name": "Bikes - Hybrid Bikes",
        "slug": "hybrid-bikes"
      }
    }
  ]
}

Obtaining Option Types and Option Values

When creating an Advert as described here or a Variant as described here, the marketplace taxonomy may require that you supply advert_option_values or variant_option_values as part of the relationships object.

In order to understand what advert_option_values or variant_option_values you need to supply when creating an Advert or a Variant, you can call the taxonomy endpoint with the taxon_slug, for example:


GET /api/v2/taxons/cars

Would return a payload for the cars taxons such as:

{
  "links": {
    "self": "https://bestfriendbazaar.com/api/v2/taxons/80-cars"
  },
  "data": {
    "type": "taxons",
    "id": "80",
    "attributes": {
      "name": "cars",
      "tree_name": "cars",
      "slug": "cars",
      "taxon_type": "product"
    },
    "has_whitelisted_secondary_taxons": false,
    "relationships": {
      "option_types": [ ⬅ HERE
        {
          "type": "option_types",
          "id": "235"
        },
        {
          "type": "option_types",
          "id": "236"
        }
      ],
      ...

Here you can see that we have 2 option_types, scrolling further down the payload and looking for the included option_types you’ll see:

  "included": [
    {
      "type": "option_types",
      "id": "235",
      "attributes": {
        "name": "Type",
        "presentation": "Product Type",
        "optional": false,
        "applied_to": "advert",
        "field_type": "multi_select",
        "variant": false, ⬅ DEPRECATED
        "feature": true ⬅ DEPRECATED
      },
      "relationships": {
        "option_values": {
          "data": [
            {
              "type": "option_values",
              "id": "703",
              "attributes": {
                "name": "1",
                "presentation": "1"
              }
            },
            {
              "type": "option_values",
              "id": "704",
              "attributes": {
                "name": "2",
                "presentation": "2"
              }
            }
          ]
        }
      }
    },
    {
      "type": "option_types",
      "id": "236",
      "attributes": {
        "name": "Length",
        "presentation": "Length",
        "optional": true,
        "applied_to": "advert",
        "field_type": "free_text",
        "variant": false, ⬅ DEPRECATED
        "feature": false ⬅ DEPRECATED
      },
      "relationships": {
        "option_values": {
          "data": []
        }
      }
    }
    ...

Both option types can be used with adverts ("applied_to": "advert") as you can see. You would then select the relevant id for the option_value that you want to use (id for the option_type for the free_text field type), and supply that with your advert create payload, an example JSON payload for this is shown below:

    {
      "data": {
        "type": "adverts",
        "attributes": {
          "title": "Wiper Blades",
          "description": "Replacement wiper blades",
          "price": 18.00,
          "condition": "new",
          "brand_slug": "other",
          "taxon_slug": "cars",
          "published": false,
          "external_id": "WH1000XMB4",
          "code": "",
          "notes": "",
          "features": {
            "product_features": [],
          }
        }
      },
      "relationships": {
        "advert_option_values": [
          {
            "type": "advert_option_values",
            "option_value_id": 703
          },
          {
            "type": "advert_option_values",
            "option_type_id": 236,
            "text_value": "500mm 20in"
          }
        ]
      }
    }