CN and CPA Classification

Boundary

VAT Engine accepts explicit CN and CPA codes only. It does not infer codes from product titles, descriptions, tags, categories, or AI. A resolved mapping is a product-classification input—not a final VAT treatment, rate, place-of-supply, or liability decision.

Catalog updates and review

Official CN 2021–2026 and CPA 2.1/2.2 catalogs can be acquired and checked through the administrator review workflow. Synchronization prepares candidates; it does not approve them or create VAT mappings. Daily checks must be explicitly enabled. Approval uses a sealed impact preview. If the administrator's recent MFA window has expired, the same review card asks for the current authenticator code and continues with that exact preview; signing out is not required.

A correction remains under review while the previously approved catalog stays available. Once approved, current assignments or classifications that still rely on superseded evidence may require transition review while revalidation runs. Previously sealed historical results retain their original evidence. Catalog approval alone does not publish authoritative tax-class mapping coverage. If an official source row has no legal applicability date, it remains visible for review but cannot become authoritative coverage; its retrieval time is never used as a substitute legal date.

When tax-source review is still required

Approving CN or CPA catalogs validates product codes; it does not decide which VAT treatment applies to a transaction. Source rates restricted to particular codes or additional conditions still need reviewed treatment coverage. A blocked comparison is shown as Not compared, not as a successful comparison with no changes.

The source-review workflow preserves original conditions and distinguishes percentage rates from exemptions, outside-scope treatments, and source not-applicable markers. Those markers must not be interpreted as a universal zero rate or permission to file. Separate evidence is needed for deduction rights and any other tax obligations. Component-aware treatment calculation and its separate approval and activation workflow are available only where reviewed treatment coverage has been explicitly cut over; catalog approval alone does not enable them.

Validate an exact code

GET /v1/classification-codes/{scheme}/{code}?catalog_version=...

Authentication is not required. The optional catalog version must be an approved immutable edition covering the applicable period. Responses include the normalized/display code, official description, source link, catalog digest, applicability, and database-recorded knowledge time.

Examples after catalog approval

Validate a CN code for a legal date

curl "https://api.vat-engine.app/v1/classification-codes/cn/49090000?catalog_version=2026&legal_date=2026-06-01"

Validate a CPA code for a legal date

curl "https://api.vat-engine.app/v1/classification-codes/cpa/58.11.11?catalog_version=2.2&legal_date=2026-06-01"

Before approval, either validation request returns:

{
  "detail": "no approved catalog covers that legal date",
  "error": "catalog_unavailable"
}

Resolve a tax-class mapping

POST /v1/tax-class/resolve
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "scheme": "cn",
  "exact_code": "49090000",
  "catalog_version": "2026",
  "jurisdiction": "DE",
  "legal_date": "2026-06-01"
}

Use a key with classification-resolve or full. Resolution checks the jurisdiction exact rule, its nearest catalog ancestor, then the equivalent EU rules. Review-only, conflicting, withdrawn, unavailable, or unmapped evidence returns needs_review. A resolved response explicitly reports authoritative_for_mapping: true and not_final_tax_treatment: true. It also returns the mapping rule's governed supply_kind; VAT Engine never assumes that every CN code is goods or every CPA code is a service.

Example after coverage publication

curl -X POST https://api.vat-engine.app/v1/tax-class/resolve \-H "X-API-Key: YOUR_API_KEY" \-H "Content-Type: application/json" \-d '{  "scheme": "cn",  "exact_code": "49090000",  "catalog_version": "2026",  "jurisdiction": "DE",  "legal_date": "2026-06-01"}'

Authoritative resolution is enabled only after the complete reviewed CN/CPA coverage set has a published classification_coverage_v1 manifest. Until that gate is complete, exact catalog validation remains available but mapping resolution fails closed with needs_review.

Submit a product-code assignment

POST /v1/integrations/{integration_id}/product-code-assignments
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "scheme": "cpa",
  "exact_code": "58.11.11",
  "product_reference": "gid://shopify/Product/123",
  "variant_reference": null,
  "requested_valid_from": "2026-09-05",
  "requested_valid_to": null
}

Use classification-write or full. Tenant, integration ownership, provenance, timestamps, catalog binding, mappings, and tax classes are derived by the server. An identical retry is idempotent only while that immutable revision remains the current assignment head. Reusing an older request after a successor creates a new revision. When requested_valid_to is omitted for a bounded catalog edition, the server records the catalog's exclusive end date; an explicitly later date is rejected as assignment_outside_catalog_interval. This preserves historical assignments without allowing an expired edition to block its successor. Submitted assignments do not participate until reviewed and validated in Integrations. Backdated entries require an attestation and impact review; archival creates a tombstone successor.

Example after catalog approval

Replace 123 with an integration ID owned by the account represented by the API key.

curl -X POST https://api.vat-engine.app/v1/integrations/123/product-code-assignments \-H "X-API-Key: YOUR_API_KEY" \-H "Content-Type: application/json" \-d '{  "scheme": "cpa",  "exact_code": "58.11.11",  "product_reference": "gid://shopify/Product/123",  "variant_reference": null,  "requested_valid_from": "2026-09-05",  "requested_valid_to": null}'

Every new assignment head and each validated/archived successor enqueue bounded background reprocessing. Each economic order is updated atomically. Locked or filed periods, manually reviewed classifications, inconsistent source scopes, and oversized orders are kept unchanged and routed to correction review.

Publishing the complete coverage manifest also reprocesses affected mappings, including decisions that previously stopped for review while the coverage gate was closed. Assignment validation and archival remain subject to the account's retained revision limit, just like new submissions.

The Integrations assignment list is paginated. Use Load more assignments to continue through all current heads; active records are not hidden behind a fixed dashboard cap. Reprocessing also preserves downstream imported-goods classification when a product mapping is refreshed. If classification authority is removed, VAT Engine restores the persisted Shopify source product facts before applying the replacement decision. Catalog and mapping work is limited to assignment-backed orders or orders carrying a sealed decision from the affected authority.

The governed CN/CPA mapping authority is EU-scoped. Shopify orders whose tax destination is outside the EU bypass assignment resolution and continue through the existing product-classification workflow.

Classification endpoints have dedicated distributed limits in addition to the API key quota. If the distributed limiter is unavailable, they fail closed.