Skip to main content
When to use this. Compliance categories are admin reference data that sit behind the Compliance module. You create them once in Admin, and they then appear as a dropdown choice whenever a user creates a certificate or compliance standard. Set these up before you start creating certificates. Categories classify by product type (e.g. Textiles, Footwear), while groups classify by purpose (e.g. Sustainability, Chain of Custody): they are separate resources.

​
The workflow

Compliance categories are prerequisites for the Compliance module. The typical path is to create your category vocabulary, optionally assign user-defined IDs for import/export alignment, and then reference categories from certificates and standards.
1

Create the categories

POST /api/compliance-categories with an array of one or more categories. Each category needs only a name; add a userDefinedId if you need to match against an external system.
2

List and verify

GET /api/compliance-categories to confirm all categories are in place. Filter by State, Names, or Search if you have a large vocabulary.
3

Retrieve a single category

GET /api/compliance-categories/{id} to inspect usedInStandard and usedInCertificates: these counters tell you whether a category is safe to delete.
4

Retire or remove

To stop offering the category to new certificates without losing history, set its state to inactive. PATCH /api/compliance-categories/{id} with a JSON Patch document changes only the state; PUT /api/compliance-categories/{id} is a full replace, so send the whole body (name, state and the current userDefinedId). To hard-delete the category instead, call DELETE /api/compliance-categories/{id} (blocked if usedInStandard > 0 or usedInCertificates > 0). To update or delete several categories in one call, send an array to PUT /api/compliance-categories with each item’s id: an item with state: "deleted" is hard-deleted, and the updates and deletes commit together in one all-or-nothing transaction.

​
Walkthrough

Create a compliance category for Footwear. The body is an array: one or many categories are created in a single all-or-nothing transaction.
The response wraps the created categories in the standard envelope. Hold onto each id: you will need it when updating or deleting individual categories.

​
Field reference

PUT /api/compliance-categories/{id} is a full replace: every field on the body is written verbatim. name and state are required, and a null or omitted userDefinedId clears the stored value. To deactivate a category without resending the other fields, send a JSON Patch document (Content-Type: application/json-patch+json) to PATCH /api/compliance-categories/{id}:
PATCH writes only the paths you send and preserves everything else.Bulk PUT /api/compliance-categories applies the same full replace to each item in the array, except that an item sent with state: "deleted" is hard-deleted instead. The batch is capped at 200 items.

​
Roles & permissions

Creating, updating and deleting compliance categories requires the compliance permission at admin level on a designer (brand) account: in practice the CompanyAdmin role. Requests from supplier accounts are rejected. The Compliance module itself requires a Professional licence subscription.

​
When things go wrong

Errors use the standard envelope (status: "error", a code, and error.details[]). Key cases to handle:
  • 409 Conflict: DELETE, or a bulk PUT item with state: "deleted", is rejected when usedInStandard > 0 or usedInCertificates > 0. Check the counts with GET /api/compliance-categories/{id} first, then reassign or remove the references before deleting. A bulk PUT also returns 409 when an item’s name or userDefinedId clashes with another category.
  • 400 validation_error: name and state are required on PUT (a bulk item sent with state: "deleted" needs only id and state), name is required on POST, and state: "deleted" is rejected on POST, single-item PUT and PATCH. A bulk PUT that lists the same id twice is also rejected.
  • 403 authorization_error: the id belongs to another organisation. This applies to GET, PUT and PATCH on /api/compliance-categories/{id}, and to any item in a bulk PUT.
  • 404 resource_error: the id does not exist. DELETE also returns 404 for an id that belongs to another organisation. In a bulk PUT, a missing id takes precedence: the batch returns 404 even if another item would be a 403.
See Errors & responses for the full list of codes and how to resolve them.

​
What to call next

Style categories

A parallel category vocabulary that organises styles: set these up alongside compliance categories for a consistent admin structure.

Item categories

Category classification for items (materials, fabrics, trims).

Groups

Compliance groups organise certificates and standards by purpose, e.g. Sustainability or Chain of Custody: the sibling resource to categories.

Size ranges

Another admin reference dataset needed before product data can be created.