Assign external product classifications

This reference is for integrators classifying products for different platforms. Maintain shop navigation and external classifications separately. A product can appear under “Leisure” in a B2C shop, “Work equipment” in a B2B shop, and the platform's own category elsewhere. A taxonomy import does not change local categories or public URLs.

The contract covers manual normalized imports, mapping rules, proposals, explicit confirmation, and local requirement checks. It does not publish products to Amazon, Google, or Kaufland or automatically synchronize their taxonomies.

Import a revision

An import pins the platform profile, market, and version. Supported profiles are google_product_category, amazon_product_type, amazon_browse_node, amazon_item_type_keyword, and kaufland_category.

Prepare the external source as normalized JSON:

{
  "schemaVersion": "1",
  "profile": "google_product_category",
  "market": "DE",
  "version": "2026-10",
  "nodes": [
    {
      "externalId": "example-category",
      "label": "Example category",
      "requirements": [
        {"key": "color", "type": "string", "required": true, "enum": ["blue"]}
      ]
    }
  ]
}

The example ID and requirements illustrate the format; use actual values from your platform source. Optional parentExternalId represents the external hierarchy. requirements must contain the complete applicable requirement set for the selected node; parent requirements are not inherited implicitly. Include inherited constraints in normalized data and name unsupported conditions, nested schemas, remote references, or platform business rules as gaps. Imports accept at most 10,000 nodes and do not fetch remote schemas. Unknown JSON fields are rejected.

nucli --tenant <tenant> pim taxonomies import --input taxonomy.json --json

An identical repeat is idempotent. Different content for the same profile, market, and version is a conflict; use a new version. Imported revisions are immutable. An external ID is not a local category UUID.

Propose and confirm

Maintain rules through integrations-external-mapping-rules; metadata provides writable fields:

nucli --tenant <tenant> resources meta integrations-external-mapping-rules

Each rule binds a sales channel, revision, and external target ID. Predicates test internal family categories or product attributes with equals, in, or exists; all predicates must match. Variant attributes override matching family values. Proposals record rule, revision, and reason. Conflicting targets require an explicit selection.

nucli --tenant <tenant> pim taxonomies propose --publication <publication-uuid> --json
nucli --tenant <tenant> pim taxonomies confirm --publication <publication-uuid> --revision <revision-uuid> --external-id <platform-id> --json
nucli --tenant <tenant> pim taxonomies check --publication <publication-uuid> --json

Confirm only on a mutable variant publication in draft or rejected. Optional --rule <rule-uuid> records selection provenance. Confirmation pins the revision. Later imports, rules, and proposals do not replace the chosen mapping. Incomplete product data can still be edited; confirmation and requirement checking are separate steps. Selection is per publication, profile, and market, allowing several Amazon classifications alongside Google and Kaufland targets.

HTTP contracts use the /api/v1 prefix:

Select internal categories for rules

The private authenticated selector uses GET /api/v1/pim/categories?treePurpose=internal. It returns only live categories in live internal trees of the same tenant, excluding unbound, deleted, or foreign-tenant nodes. Optional treeId narrows the result. salesChannelId selects allowed shop trees; combining it with treePurpose=internal therefore produces an empty intersection. This private selector is not called from a public storefront.

With source=internal_category, equals and in match direct family assignments. Shop categories and implicit ancestors or descendants are excluded. Category IDs compare UUID identity; uppercase or 32-character hexadecimal spelling represents the same UUID. With source=attribute, keys and string values remain case-sensitive. External IDs are also preserved without case normalization.

Check requirements

Server-side requirement checks support string, number, integer, boolean, required values, enumerations, and minItems/maxItems. The server compares numeric JSON values exactly through HTTP and NuCLI, including integers that cannot be represented exactly as float64. Numeric tokens are limited to 256 characters, and scientific exponents must be between -308 and 308. Numeric rule values and imported enumerations exceeding these bounds are rejected. For product values outside supported bounds, local checking reports a type error and does not assert readiness. Unsupported requirements must be named through unsupportedFeatures, for example conditionalRequired. Such gaps prevent ready=true; they are never silently treated as satisfied.

Without a confirmed selection, checking returns checks: [], which is not a readiness assertion. A positive local result means only that supported imported requirements are met. It does not certify complete platform compliance or a successful transfer. Check the platform contract and any later connector separately.

Edit numbers in admin forms

Admin forms for rule literals and the nodes import check numbers before writing. An entered JSON numeric token must retain its mathematical value through parsing and serialization. Rounding, nonfinite values, and integers outside JavaScript's safe range are rejected with an editor-limit message and a NuCLI hint. Equivalent exponent notation or trailing zeros are accepted when this check passes.

For example, 9007199254740993 cannot be saved as a number through the admin form. Use the original JSON file through NuCLI or the HTTP contract for such exact numeric values within the server bounds above. The value type must still match the requirement.

This form check applies to entered JSON tokens and the write operation. If the browser has already parsed a server response value as a JavaScript number, it cannot establish or restore precision lost during that earlier parse. The admin interface provides no exactness guarantee for those already-parsed values.

Verify

After import, compare profile, market, version, and external IDs with the source. Test matching and conflicting rules, missing required values, and an unsupported requirement. A later import must retain the selected revision. Shop navigation and category URLs must remain unchanged.