MarketplaceHub Docs Docs

Product types and taxonomy versions

How marketplace schemas are versioned, what triggers a new version, and why only the current one is worth building against.

Marketplace schemas change. A product type that required eight fields last quarter may require ten now, with two of last quarter's renamed. MarketplaceHub handles that by versioning the taxonomy rather than overwriting it.

What a version is

A product type version is one marketplace product type, for one marketplace and country, as it stood at one import. It holds the field list — which fields exist, which are required, what each means and what an accepted value looks like — plus the marketplace's own schema version string.

How versions are created

A recurring taxonomy import pulls product types and categories from each connected marketplace. When it finds a schema that differs from the stored one it creates a new version and activates it; the previous version stays until it is pruned.

A taxonomy import creates and activates a new product type version when the marketplace schema changes; the previous version stays until pruned, and existing listings keep working against it until next published RECURRING TAXONOMY IMPORT Version 1 — superseded 8 fields, schema v2026.03 Kept until pruned Existing listings still work against it schema changed Version 2 — active 10 fields, schema v2026.09 ACTIVE Resolved for every new publish New publish resolves the active version Every completed taxonomy pull chains a cleanup sweep that prunes versions strictly below the active one — a newer, still-inactive version is treated as an import in flight and is never pruned.
A new version activates on schema change; a new publish always resolves the active one.

Two consequences worth knowing:

  • A new version does not invalidate your listings. Existing listings keep working against the version they were built on until they are next published.
  • The required-field list you build against should be the current one. A superseded field list is a list of fields the marketplace may already have stopped accepting, which is why a product type is always resolved against the version in force at that moment rather than one captured earlier.

Why a product type may have no fields yet

A product type that reports no fields is one whose taxonomy import has not completed for that marketplace and country. It resolves on its own once the next import finishes — there is nothing to configure.