Update a custom field

Lifecycle-gated edit. Scope: custom_fields:write. What’s allowed depends on whether the field is in use (usage_count > 0):

Change	Field unused	Field in use
label, description, position	✅	✅
ADD options	✅	✅
REMOVE option values	✅	❌ 409 custom_field_in_use
Rename key	✅	❌ (would diverge from form_builder.fields[].id on referencing cards)
Change field_type	✅	❌ (stored values would violate the new type)

To make a blocked change: remove the field from all referencing cards first, or create a new field and migrate.

PATCH /v1/custom_fields/{id}

cURL

Add options + relabel

curl --request PATCH \ --url https://api.vexioncards.one/v1/custom_fields/{id} \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "label": "Hospital department", "options": [ { "value": "cardio", "label": "Cardiology" }, { "value": "neuro", "label": "Neurology" }, { "value": "ortho", "label": "Orthopedics" }, { "value": "derma", "label": "Dermatology" } ] } '

200

{
  "id": "cf_department",
  "object": "custom_field",
  "key": "department",
  "label": {
    "en": "Hospital department",
    "sk": "Oddelenie"
  },
  "description": "Which department issued the card.",
  "field_type": "select",
  "number_format": null,
  "position": 2,
  "options": [
    {
      "value": "cardio",
      "label": {
        "en": "Cardiology",
        "sk": "Kardiológia"
      }
    },
    {
      "value": "derma",
      "label": {
        "en": "Dermatology",
        "sk": "Dermatológia"
      }
    }
  ],
  "date_granularity": "date",
  "usage_count": 2,
  "cards_using": [
    "crd_qitthvziwgn552o6evjqm425im",
    "crd_w2x2l45kffgkdaq62fhp7fuee4"
  ],
  "created_at": 1750000000,
  "updated_at": 1752200000
}

Authorizations

Authorization · string · header · required

Your secret API key as a Bearer token: Authorization: Bearer vxn_sk_.... Keys are created and scoped in the dashboard - see Authentication.

Headers

Idempotency-Key · string

Recommended on PATCH and DELETE for safe retries.

Path Parameters

id · string · required

Custom field identifier (cf_ prefix).

Pattern: ^cf_[A-Za-z0-9]+$

Body

application/json

Lifecycle-gated PATCH. While the field is IN USE (usage_count > 0): key renames, field_type changes, and option-value removals are BLOCKED (409 custom_field_in_use). Always editable: label, description, position, required, and ADDING options.

label · string Per-language labels · object

Customer-facing label - shown on the signup form, referenced on wallet passes, and used in the dashboard. Plain string or per-language object (the platform localization pattern, same as Card.name). This is the DEFAULT - each card's form_builder can override the label per card.

Required string length: 1 - 50

description · string | null

Always editable.

Maximum string length: 500

position · integer

Always editable.

options · object[]

Adding options is always allowed; removing a value that customers already stored is blocked while in use.

key · string

Rename - BLOCKED while usage_count > 0.

Pattern: ^[a-z][a-z0-9_]{1,49}$

field_type · enum<string>

Field type - see the type table on the Custom Field object. Immutable while in use.

Available options: text, textarea, number, currency, date, boolean, select, multiselect

Example:

"select"

Response

200

application/json

Updated custom field (full object).

A reusable custom field DEFINITION - the single vocabulary used across the whole platform: the signup form (via each card's form_builder), the customer record (Customer.custom.<key>), wallet pass slots ({{custom.<key>}} in Card.pass_fields), and notification templates. Define once, reference everywhere.

The definition owns IDENTITY (key, type, options, granularity) and DEFAULTS (label translations, required, position); each card's form owns USAGE (which fields, per-card required/order/label overrides). Limits: 50 definitions per organization (409 custom_field_limit_reached), 20 fields per card form.

id · string · required

Opaque, stable, immutable. cf_ prefix.

Pattern: ^cf_[A-Za-z0-9]+$

Example:

"cf_01HW9R9Z4EF7N8MTX1RVCFLD01"

object · string · required

Always "custom_field".

Allowed value: "custom_field"

key · string · required

Stable machine identifier, unique within the organization (2-50 chars, lowercase snake). Used in {{custom.<key>}} templates and Customer custom.<key> payloads. Renames are blocked while the field is in use (usage_count > 0) to prevent keys diverging across cards.

Pattern: ^[a-z][a-z0-9_]{1,49}$

Example:

"department"

label · string Per-language labels · object · required

Customer-facing label - shown on the signup form, referenced on wallet passes, and used in the dashboard. Plain string or per-language object (the platform localization pattern, same as Card.name). This is the DEFAULT - each card's form_builder can override the label per card.

Required string length: 1 - 200

field_type · enum<string> · required

What kind of data the field holds - drives form input, validation, and typed pass/notification rendering:

type	value shape	pass rendering
text	string ≤200	as-is
textarea	string ≤2000	back of pass only
number	number (number_format controls integer vs decimal)	locale-formatted number
currency	integer, minor units, organization currency	locale-formatted amount (native on Apple via ISO 4217; server-formatted on Google)
date	string per date_granularity (YYYY / YYYY-MM / YYYY-MM-DD)	locale-formatted date
boolean	true / false	localized Yes/No
select	one option value	the option's label, customer language
multiselect	array of option values	comma-joined labels

Immutable while the field is used by any card (409 custom_field_in_use).

Available options: text, textarea, number, currency, date, boolean, select, multiselect

Example:

"select"

created_at · integer · required

Unix seconds.

Example:

1750000000

description · string | null

Internal helper text for the dashboard.

Maximum string length: 500

Example:

"Clinic department the patient is assigned to."

position · integer

DEFAULT form position when added to a card; each card's form_builder ordering overrides.

Example:

2

options · object[]

Choices for select / multiselect (required for those types). Each option is {value, label} - labels are always editable (display only); values are immutable once any customer has stored them and removing a used value is blocked (409 custom_field_in_use). Adding options is always allowed.

Show child attributes

Example:

[
  { "value": "cardio", "label": "Cardiology" },
  { "value": "neuro", "label": "Neurology" }
]

date_granularity · enum<string>

DATE type only - controls the stored format: date → YYYY-MM-DD, monthYear → YYYY-MM, year → YYYY. Forced to date for non-date types.

Available options: year, monthYear, date

Example:

"date"

usage_count · integer

Read-only. Number of cards referencing this field. Renames + type changes + deletes are blocked while > 0.

Example:

3

cards_using · string[]

Read-only. The referencing card ids.

Example:

["crd_sophcrprtvpmmnwxah2lomnkee"]

updated_at · integer

Unix seconds.

Example:

1750000000

number_format · enum<string> | null

number fields only: integer rejects fractional input; decimal (default) allows it. Null on other types.

Available options: integer, decimal, null