Store additional structured data on customers, subscriptions, products, prices, invoices, and checkout sessions. Define typed fields with validation rules to extend PaymentKit’s data model for your business needs.

Overview

Custom fields let you attach structured, validated data to PaymentKit objects. Unlike free-form metadata, custom fields enforce data types, constraints, and provide a consistent schema across your integration.

You can manage custom fields via the Business Portal or the API.

1
{
2
  "id": "cus_abc123",
3
  "email": "jane@acme.com",
4
  "name": "Jane Smith",
5
  "custom_fields": {
6
    "company_size": "51-200",
7
    "sales_rep": "john@yourcompany.com",
8
    "is_enterprise": true
9
  }
10
}

These fields are defined once, then values can be set on any customer:

Supported entity types

Custom fields can be attached to these resources:

Data types

Custom fields support four data types with optional constraints:

Managing custom fields in the Business Portal

The Business Portal provides a complete UI for managing custom field definitions and values.

Creating and editing definitions

Navigate to Settings → Custom Fields to view all custom field definitions for your account. From here you can:

• Create new definitions — Click “Create Custom Field” and fill in the field key, display name, entity type, data type, constraints (if applicable), and visibility settings
• View definition details — Click any row to open a side panel with full details
• Edit definitions — Update the display name, description, constraints, and visibility settings (field key, entity type, and data type cannot be changed after creation)
• Delete definitions — Remove a definition and all its values across all entities (requires typing the field key to confirm)

List view visibility

Each custom field definition has a “Show in List View” setting that controls whether the field appears as a column in entity list views:

This is useful when you have many custom fields but only want a subset visible in tables.

Viewing and editing values on entities

Custom field values can be viewed and edited directly on entity detail pages. For example, on a Price detail page:

1. The Custom Fields section displays all current values for that price
2. Click Edit to open a side panel titled “Edit Custom Fields” with a form for all defined price custom fields
3. Each field type renders an appropriate input (text input, number input, select dropdown with clearable support, or toggle switch for booleans)
4. Clear a field to remove its value
5. Click Save Changes to persist changes, or Cancel to discard

Filtering by custom fields

In list views (like the Prices table on a Product detail page), you can filter by custom field values:

1. Click Filter by custom fields to expand or collapse the filter panel
2. Filter controls appear for each visible custom field:
   • Text fields — Type to filter (case-insensitive substring match)
   • Number fields — Enter a number to filter (partial match)
   • Boolean fields — Select “Yes”, “No”, or “Any”
   • Select fields — Check one or more options (prices matching ANY selected option are shown)
3. A badge next to the button shows the number of active filters (filters with at least one value selected)

Creating field definitions

Before storing values, create a field definition to establish the schema.

See Create Custom Field Definition for the full API reference.

Field definition examples

1
{
2
  "field_key": "internal_id",
3
  "entity_type": "customer",
4
  "data_type": "text",
5
  "display_name": "Internal ID",
6
  "is_visible_in_list": true
7
}

Listing field definitions

Retrieve all definitions for your account, optionally filtered by entity type.

See List Custom Field Definitions for the full API reference.

Setting custom field values

Set values when creating or updating entities by including a custom_fields object in your request body:

1
{
2
  "custom_fields": {
3
    "company_size": "51-200",
4
    "internal_id": "CRM-12345",
5
    "is_enterprise": true
6
  }
7
}

See Create Customer or Update Customer for examples. The same pattern applies to all supported entity types.

Updating custom fields on immutable entities

Some entities like prices are immutable after creation—you cannot change their core properties. However, custom fields can still be updated via the PATCH endpoint:

$
curl -X PATCH "https://api.paymentkit.com/api/{account_id}/prices/{price_id}" \
>
  -H "Authorization: Bearer {api_token}" \
>
  -H "Content-Type: application/json" \
>
  -d '{"custom_fields": {"internal_sku": "AC-2024-PREMIUM"}}'

See Update Price for the full API reference.

Reading custom field values

Custom fields are returned when you expand them in your request using ?expand=custom_fields:

1
{
2
  "id": "cus_abc123",
3
  "email": "jane@company.com",
4
  "name": "Jane Smith",
5
  "custom_fields": {
6
    "company_size": "51-200",
7
    "internal_id": "CRM-12345",
8
    "is_enterprise": true,
9
    "tier": "gold"
10
  }
11
}

See Get Customer for the full API reference.

Clearing field values

Set a field to null to remove its value:

1
{
2
  "custom_fields": {
3
    "internal_id": null
4
  }
5
}

See Update Customer for the full API reference.

Updating field definitions

You can update display_name, description, constraints, and is_visible_in_list on existing definitions.

See Update Custom Field Definition for the full API reference.

Updating select field options

When updating a select field’s options, you can add new options freely. However, you cannot remove options that are currently in use. If any entity has a value set to an option you’re trying to remove, the update will fail with a 422 error: "Cannot remove select options that are in use: ['option1', 'option2']".

To remove an option:

1. First update all entities using that option to a different value
2. Then update the definition to remove the option

Deleting field definitions

Deleting a definition removes all associated values across all entities. This is a destructive operation. The confirm_field_key parameter must match the definition’s field key to prevent accidental deletion. If the keys don’t match, the request fails with a 400 error. The response includes an X-Deleted-Values-Count header showing how many values were deleted.

See Delete Custom Field Definition for the full API reference.

Validation

Custom fields are validated on write:

Example error response:

1
{
2
  "type": "about:blank",
3
  "title": "HTTP Error",
4
  "status": 400,
5
  "detail": "Custom field 'tier' value 'unknown' is not a valid option. Valid: ['bronze', 'silver', 'gold', 'platinum']",
6
  "instance": "/api/acc_xxx/customers/cus_xxx",
7
  "request_id": "req_xxx"
8
}

Test and live mode

Custom field definitions are scoped to your account and are separate between test and live modes. Definitions you create in test mode won’t appear in live mode and vice versa. This lets you safely experiment with field schemas in test mode before creating them in production.

Webhooks

Custom field changes are included with the parent entity’s webhook events. For example, when you update a customer’s custom fields, the customer.updated webhook will include the updated custom_fields in the payload. There are no separate webhook events for custom field changes.

Best practices

Limits