> ## Documentation Index
> Fetch the complete documentation index at: https://integration.delogue.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Manage style custom fields
> Define and maintain the extra data fields that appear on every style — from free-text and date fields to dropdown lists and hierarchical selectors.
**When to use this.** Style custom fields are the extra data points your brand defines in Admin
and then fills in on each style — fabric composition, fit, sustainability score, and so on.
They are set up once at the organisation level and then appear on every style that matches the
field's brand/group/category restrictions. Use these endpoints to create and manage that field
catalogue and to bulk-update positions or lifecycle states.
## The workflow
Custom fields are admin data: a `CompanyAdmin` defines the fields, optionally restricts them to
certain brands, groups, or categories, and then users fill them in on individual styles. The
usual path is to create the field, verify it is visible on styles, and retire it when no longer
needed.
`POST /api/style-custom-fields` with the field name, type, and position. The body is an
array — one or many fields are created in a single all-or-nothing transaction.
For `allowedValue` and `nestedAllowedValue` fields, include `allowedValues` in the create
body, or add them later via `PUT /api/style-custom-fields/{id}` (full replacement).
`GET /api/style-custom-fields` to list fields by type, state, brand, group, or category.
Use cursor-based pagination for large catalogues.
`PUT /api/style-custom-fields` (bulk) to reorder positions or flip states across multiple
fields in one call. `DELETE /api/style-custom-fields/{id}` to soft-delete a single field
(sets `state` to `deleted`).
```mermaid theme={"dark"}
sequenceDiagram
participant A as Admin
participant API as Delogue API
A->>API: POST /api/style-custom-fields (create field)
API-->>A: field id + state: active
A->>API: GET /api/style-custom-fields?Types=allowedValue
API-->>A: paginated field list
A->>API: PUT /api/style-custom-fields/{id} (update / add allowed values)
API-->>A: updated field
A->>API: DELETE /api/style-custom-fields/{id} (soft-delete)
API-->>A: state: deleted
```
## Walkthrough
Create a mandatory text field called "Fabric Composition" that suppliers can edit. The body is
an array so you can create several fields in one request.
```bash cURL theme={"dark"}
curl -X POST "https://service.my.delogue.com/api/style-custom-fields" \
-H "Accept: application/json" \
-H "X-Auth-Token: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '[
{
"name": "Fabric Composition",
"userDefinedId": "FAB-01",
"type": "text",
"position": 5,
"state": "active",
"internalOnly": false,
"isMandatory": true,
"isSupplierEditable": true,
"isMultiLine": false,
"isSortByAllowedValueId": false,
"diffPerColor": false,
"diffPerSize": false,
"useInThumbnailViewGroupBy": false,
"maxChar": 200,
"allowedDecimals": 0,
"numericVariantCalculationFormula": "none",
"parentCustomFieldId": null,
"allowedValues": null,
"associatedBrands": null,
"associatedGroups": null,
"associatedStyleCategories": null
}
]'
```
```js JavaScript theme={"dark"}
const res = await fetch("https://service.my.delogue.com/api/style-custom-fields", {
method: "POST",
headers: {
"Accept": "application/json",
"X-Auth-Token": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify([
{
"name": "Fabric Composition",
"userDefinedId": "FAB-01",
"type": "text",
"position": 5,
"state": "active",
"internalOnly": false,
"isMandatory": true,
"isSupplierEditable": true,
"isMultiLine": false,
"isSortByAllowedValueId": false,
"diffPerColor": false,
"diffPerSize": false,
"useInThumbnailViewGroupBy": false,
"maxChar": 200,
"allowedDecimals": 0,
"numericVariantCalculationFormula": "none",
"parentCustomFieldId": null,
"allowedValues": null,
"associatedBrands": null,
"associatedGroups": null,
"associatedStyleCategories": null
}
]),
});
const { data } = await res.json();
```
```json theme={"dark"}
{
"status": "success",
"code": "style_custom_fields_created",
"data": [
{
"id": 30100,
"name": "Fabric Composition",
"userDefinedId": "FAB-01",
"type": "text",
"state": "active",
"position": 5,
"maxChar": 200,
"allowedDecimals": 0,
"numericVariantCalculationFormula": "none",
"parentCustomFieldId": null,
"parentCustomFieldName": null,
"allowedValues": [],
"associatedBrands": [],
"associatedGroups": [],
"associatedStyleCategories": [],
"properties": [
"mandatory",
"supplierEditable"
]
}
]
}
```
The response wraps the created fields in the standard envelope. Hold onto each `id` — updates
and deletes reference fields by it.
## Field reference
The fields that matter most when creating or updating a style custom field:
| Field | What it means at Delogue |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `allowedDecimals` | For numeric fields: number of decimal places permitted (0 = integers only). Defaults to 0. |
| `allowedValues` | Initial allowed value options for allowedValue and nestedAllowedValue fields. Omit or null to start with no options. |
| `associatedBrands` | Brands to restrict this field to. Omit or null to show the field on all styles regardless of brand. |
| `associatedGroups` | Style groups to restrict this field to. Omit or null to show the field on all styles regardless of group. |
| `associatedStyleCategories` | Style categories to restrict this field to. Omit or null to show the field on all styles regardless of category. |
| `diffPerColor` | When true, the field stores a separate value for each color variant of a style. |
| `diffPerSize` | When true, the field stores a separate value for each size of a style. |
| `internalOnly` | When true, the field is hidden from supplier users. |
| `isMandatory` | When true, the style cannot be set to 'Ready for Export' until this field is filled in. |
| `isMultiLine` | For text fields: when true, a multi-row text box is shown instead of a single-line input. |
| `isSortByAllowedValueId` | For allowedValue and nestedAllowedValue fields: when true, the dropdown is sorted by user-defined ID rather than value text. |
| `isSupplierEditable` | When true, supplier users may edit this field's value on a style. |
| `maxChar` | Maximum character limit for text or allowed-value fields. Null means no limit. |
| `name` | Display name of the custom field. Required. |
| `numericVariantCalculationFormula` | For numeric fields with diffPerColor or diffPerSize: how values are aggregated in reports. none, average, or sum. |
| `parentCustomFieldId` | For nestedAllowedValue child fields: the ID of the parent custom field. Null for top-level fields. |
| `position` | Display order position. Required. Lower values appear first in the Custom Fields tab. |
| `state` | Initial lifecycle state. active or inactive. Defaults to active. Cannot be deleted on create; use DELETE after creation. |
| `type` | Field type. One of: allowedValue, date, text, nestedAllowedValue, numeric, divider. Required. |
| `useInThumbnailViewGroupBy` | When true, styles can be grouped by this field's value in the Thumbnail View. |
| `userDefinedId` | Optional customer-assigned identifier. Used for ERP integrations and data imports/exports. |
## Roles & permissions
Managing style custom fields requires the **`custom_fields`** permission on a **designer (brand)
CompanyAdmin** account. `CompanyUser` accounts can read the field catalogue but cannot create,
update, or delete fields. Supplier accounts have no access to the admin catalogue.
`diffPerColor` and `diffPerSize` are **Professional-tier** features. Attempting to set them
on a non-Professional organisation returns a `403` permission denial.
## When things go wrong
Errors use the standard envelope (`status: "error"`, a `code`, and `error.details[]`). See
[Errors & responses](/concepts/errors) for the full list of codes and how to resolve them.
Common cases:
* **400 `validation_error.required_field`** — `name`, `type`, or `position` was omitted on create.
* **400 `validation_error.not_allowed`** — `position` was supplied on a single `PUT` (reordering requires the bulk endpoint).
* **400 `validation_error.invalid_value`** — `state=deleted` supplied on `PUT {id}` (use `DELETE` instead).
* **404 `resource_error.style_custom_field_not_found`** — the `{id}` does not exist or belongs to a different organisation.
## What to call next
Scope custom fields to specific style categories for cleaner per-product-type layouts.
Set up the sizes used with `diffPerSize` custom fields.
Manage the color library used with `diffPerColor` custom fields.
Full parameter reference for all style custom field endpoints.