Custom Fields

Use this page to extend the default product schema with typed metadata on licenses and customers.

Who This Is For

• teams adding business metadata without overloading core license fields
• developers integrating typed back-office attributes
• operators segmenting licenses or customers by internal metadata

When To Use This

Use custom fields when the metadata belongs in LicenseKit but should remain typed and explicit.

How It Works

Custom fields are a management-only feature.

Flow:

1. create a field definition on the product
2. write values to licenses or customers
3. read those values back through the list routes

Field definition types:

• string
• integer
• boolean
• datetime
• enum

License value scopes:

• license:read
• license:write

Customer value scopes:

• admin

Example

Create a license-level enum field:

curl -X POST https://api.licensekit.dev/api/v1/products/prod_123/custom-fields \
  -H "Authorization: Bearer $LICENSEKIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resource_type": "license",
    "code": "deployment_region",
    "name": "Deployment Region",
    "value_type": "enum",
    "enum_options": ["us-east", "us-west", "eu-central"],
    "is_required": true
  }'

Write a license value:

curl -X PUT https://api.licensekit.dev/api/v1/licenses/lic_123/custom-fields/fld_123 \
  -H "Authorization: Bearer $LICENSEKIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enum_value": "us-east"
  }'

Common Mistakes

• sending the wrong typed value field for the definition type
• expecting customer custom field value writes to work with non-admin scoped keys
• clearing a required field without changing the definition first

Related Pages

• Metering
• Orders And Subscriptions
• Error Handling