These docs are a work in progress and may not be fully up to date. Some pages may contain internal notes for our team.
Skip to Content

API — Custom Fields

CRUD and reordering for CustomFieldDefinition records — the workspace-level schema that defines what custom fields locations can have. All endpoints require auth:api, auth_session, audit.

Endpoints

GET /custom-field-definitions

List all custom field definitions in the active workspace, ordered by sort_order.

Query params: workspace_id

Response 200: Array of definition objects:

[
  {
    "id": 1,
    "name": "Store Manager",
    "label": "Store Manager",
    "type": "text",
    "sort_order": 0,
    "workspace_id": 1
  }
]

POST /custom-field-definitions

Create a new custom field definition.

Body: { name, label, type, workspace_id, options?, required? }

type is one of the supported field types — see Data model: CustomFieldDefinition for the type enum clarification. options (json array) and required (boolean) are optional fields.

Response 201: Created definition.

PUT /custom-field-definitions/{id}

Update a definition’s label or type.

Body: { label?, type? }

⚠️ Warning: Changing the type of an existing field does not migrate existing location data. Values stored under the old type may not render correctly with the new type. Changing type is safe only if all locations have empty values for that field.

Response 200: Updated definition.

DELETE /custom-field-definitions/{id}

Delete a definition. Removes the field from the workspace schema; existing location values stored under this field are orphaned but not deleted from location records.

Response 204

POST /custom-field-definitions/reorder

Reorder all definitions in one atomic call.

Body: { ids: [3, 1, 2] } — array of definition IDs in the desired sort order.

Response 200: Updated definitions with new sort_order values.

Concepts