Taxonomy ingestion

Taxonomy ingestion tells Zentail how your channel classifies products, so Zentail can send you listings already shaped for your channel.

What you’ll build

Your channel’s product types in Zentail, each with the attribute specs that describe it.

Before you start

You can authenticate as a seller.
Part of this step needs work on Zentail’s side, so start it early.

Terms used here

Term	Meaning
Attribute	The specification (name, type, product type and so on) of an attribute within a product type on your marketplace.
Product type	A detailed classification dictated by the marketplace. Product types specify which attributes are available, required and recommended for listings classified into them.

1. Create product types

Create each product type with POST /v2/storefront/taxonomy/product_type:

{
  "productType": {
    "productTypeId": "<a unique identifier for this product type>",
    "displayName": "<a user-friendly name for this product type>"
  }
}

The response wraps the product type you created, with the timestamps Zentail set:

{
  "productType": {
    "productTypeId": "mens-tshirts",
    "displayName": "Men's T-shirts",
    "createdAt": "2026-09-22T14:00:00.000Z",
    "updatedAt": "2026-09-22T14:00:00.000Z"
  }
}

2. Create attribute specs

Once a product type exists, create its attribute specs with POST /v2/storefront/taxonomy/attribute_spec/{productTypeId}:

{
  "attributeSpec": {
    "attributeSpecId": "<a unique identifier for this attribute, must only be unique within the productType ID>",
    "displayName": "<a user friendly display name>",
    "type": "<one of: TYPE_TEXT, TYPE_SELECT, TYPE_NUMERIC, TYPE_NUMERIC_WITH_UNITS, TYPE_MULTI_TEXT, TYPE_MULTI_SELECT, TYPE_MONEY, TYPE_MULTI_OBJECT>",
    // only include validValues if the type is SELECT or MULTI_SELECT
    "validValues": ["string"],
    // only include validUnits if the type is NUMERIC_WITH_UNITS
    "validUnits": ["string"],
    // unit is used only by NUMERIC types. If this numeric value has some
    // intrinsic unit associated with it, provide it here and Zentail will
    // ensure values in Zentail with differing units are converted properly
    // before including them on the listing.
    "unit": "string",
    "level": "<one of LEVEL_LISTING, LEVEL_VARIANT>",
    "usage": "<one of USAGE_AVAILABLE, USAGE_RECOMMENDED, USAGE_REQUIRED>",
    "classification": "<one of CLASSIFICATION_PRODUCT, CLASSIFICATION_INVENTORY, CLASSIFICATION_PRICING, CLASSIFICATION_LOGISTICS, CLASSIFICATION_IDENTIFIER>",
    // only include objectFieldSpecs if the type is TYPE_MULTI_OBJECT
    "objectFieldSpecs": {
      "<sub-attribute name>": {
        "type": "<the sub-attribute's own type, from the list above>",
        "validValues": ["string"],
      },
    },
    // the four below are optional on any type, and all four are for the seller
    "description": "<a human-readable description of the attribute>",
    "examples": ["<an example of a valid value, for a human to read>"],
    "maxUniqueItems": "<the largest number of unique values this attribute accepts>",
    "suggestedValues": [
      "<a value you recommend, without restricting the seller to it>",
    ],
  },
}

That covers every field you should set on a new spec. attributeSpecId, displayName and type are the only ones most attributes need; the rest are optional. One further settable field, the superseded objectSpec, is covered under object-shaped attributes below.

maxUniqueItems is a 64-bit integer, so send it as a JSON string, such as "5".

The response is the spec itself, not wrapped in attributeSpec. Zentail adds createdAt and updatedAt to it.

Object-shaped attributes

Use TYPE_MULTI_OBJECT for an attribute whose value is a repeated set of named fields rather than a single value — a nutrition panel or a compliance certificate, say. Describe each sub-attribute in objectFieldSpecs, keyed by its name, giving the sub-attribute’s own type and, for an enum sub-field, its validValues.

Listing level

The level property is only used to enforce that all variants must always carry the same value for this attribute spec. In general it is safe to use LEVEL_VARIANT for all attributes, but LEVEL_LISTING is available where you need that extra constraint.