Skip to main content
When to use this. Groups are optional admin-defined labels that organise styles (e.g. Woven, Knitwear, Denim) and compliance certificates (e.g. Sustainability, Chain of Custody) by fabric type, product purpose, or compliance focus. You create them once in Admin and users then select from them in the style header and the compliance module. Use these endpoints to build and maintain that library programmatically: for example when syncing with an ERP or migrating a client’s existing group taxonomy.

​
The workflow

Groups are organisation-scoped reference data. The typical path is to create your group taxonomy, then reference groups from styles or certificates through the respective style/compliance endpoints.
1

Create groups

POST /api/groups with an array of one or more groups: name is required, userDefinedId is optional but strongly recommended for ERP alignment. All items are created in a single all-or-nothing transaction.
2

Find groups

GET /api/groups with filters (State, Names, UserDefinedId, or free-text Search) to look up group IDs before referencing them on styles or in bulk operations. GET /api/groups/{id} reads a single group by its id.
3

Update or deactivate

PATCH /api/groups/{id} to change only the fields you send (for example state to inactive so the group no longer appears in new-style dropdowns) or PUT /api/groups/{id} to replace the group in full. Use the bulk PUT /api/groups to update many groups at once, including soft-deleting individual items within the same call.
4

Delete when unused

DELETE /api/groups/{id} soft-deletes a group. The call returns 400 if the group is still assigned to one or more styles (usedInStyles > 0); reassign those styles first.

​
Walkthrough

Create two groups in a single request. The body is an array: Knitwear and Denim are created together in one all-or-nothing transaction.
The response wraps the created groups in the standard envelope. Hold onto each id: styles and compliance certificates reference groups by it.

​
Field reference

The bulk PUT /api/groups endpoint accepts an array of GroupBulkUpdateCommand objects. Setting state: "deleted" on an item within the array triggers the same delete-time rules as DELETE /api/groups/{id}: the group must not be in use on any style.
PUT /api/groups/{id} is a full replace: name and state are required, and a userDefinedId sent as null is cleared. PATCH /api/groups/{id} accepts an RFC 6902 JSON Patch document (Content-Type: application/json-patch+json) and touches only the paths you send: an omitted name or userDefinedId keeps its current value, and replace /userDefinedId with null clears it. Neither route accepts state: "deleted"; use DELETE /api/groups/{id} so the delete-time rules run.

​
Roles & permissions

Managing groups requires admin-level access to the groups permission on a designer (brand) account: by default the CompanyAdmin role. Supplier accounts cannot create or modify groups.

​
When things go wrong

Errors use the standard envelope (status: "error", a code, and error.details[]). See Errors & responses for the full list of codes and how to resolve them. Common cases to handle:
  • 400 validation_error.*: name missing, or state: deleted sent to PUT /api/groups/{id} or PATCH /api/groups/{id} (use DELETE instead).
  • 400 on DELETE /api/groups/{id}: the group is still assigned to one or more styles (usedInStyles > 0). Reassign those styles to a different group first.
  • 403 authorization_error.group_access_denied: your account lacks the groups permission, or GET, PUT or PATCH on /api/groups/{id} targets a group that belongs to another organisation.
  • 404 resource_error.group_not_found: the id does not exist. DELETE /api/groups/{id} also returns 404 for a group that belongs to another organisation.
  • 409 resource_conflict_error.*: name or userDefinedId already exists in the organisation, a PATCH operation tried to change /id to a different value, or a PATCH test operation did not match.
  • 422: a PATCH operation could not be applied, for example a path that is not on the group (such as /organizationId).

​
What to call next

Style categories

Organise styles by product type (e.g. T-shirts, Dresses): complements groups.

Seasons

The top-level structure every style is filed under; create seasons before styles.

Size ranges

Define the size sets that styles and items reference.

Styles

Create and manage styles that reference groups: POST /api/styles.