Custom fields

Read and adjust the company's custom-field definitions: the extra attributes Hivebuy asks for on each purchase-request item (appliesTo: ITEM) or once per request (appliesTo: REQUEST). A definition has a type (BOOLEAN, TEXT, PRICE, SELECT, DATE), a label, help text per language, a default value, an active flag and, for a SELECT field, its option list.

Existing fields only. This resource lists, retrieves and patches definitions. There is no POST, PUT or DELETE (each returns 405): fields are created, linked to categories and removed in Hivebuy. Needs the Custom fields feature enabled for the company on top of External API; when it is off every verb returns 403.

What can change, and what it reaches

• Immutable:name, type and appliesTo. Sending them on a PATCH returns 200 with the stored values unchanged, so a GET body can be echoed back as-is. Any other unknown key is a 400.
• Writable:label, helpText, placeHolder, value, currency, mandatoryField, inputType, isActive, order, selectFields.
• Propagated to existing catalogue-item copies:label, helpText, placeHolder, mandatoryField, isActive. Not propagated: the option list, order, value, currency, inputType. These change the definition only, and nothing re-validates stored values against a changed option list.
• Options are replace-all.selectFields carries no option ids: the list you send replaces the list that was there. Omit the key to leave options alone. Values already chosen on past requests and catalogue items keep their own copy of value and label, so a removed option never breaks history. Only accepted on a SELECT field, including an empty list; each option needs a non-blank label and value, and value must be unique within the list. Otherwise 400.
• value is a string in storage: a PRICE is a decimal string with currency, a DATE an ISO date, a SELECT one of the option values. A BOOLEAN field reads back as a real true/false. Omitting value on a PATCH leaves it unchanged.
• helpText is a map of language code to string ({"en": "...", "de": "..."}) or null.
• Shared definitions. A definition shared into this company from another company of your tenant is listed and readable but read-only here: a PATCH returns 400 naming the owning company. Patching a definition this company shares with others updates their copies.
• No timestamps. This shape has no createdAt, updatedAt or deleted. A soft-deleted definition disappears from the list but is still retrievable by id and looks like a live one; a PATCH against it is 404.

Operations

Reads need master-data:read, the update master-data:write.

• GET/api/v2/{companyId}/custom-fields/: Paginated, in form order (order). Filters: isActive, appliesTo, type; ordering accepts order, name, createdAt. An unknown parameter or value is a 400 naming it.
• GET/api/v2/{companyId}/custom-fields/{id}/: One definition, with selectFields and categoryCustomFields nested.
• PATCH/api/v2/{companyId}/custom-fields/{id}/: Changes only the fields you send. selectFields replaces the whole option list. The response is the read shape.