Skip to main content
Custom Fields allow you to collect additional information from customers during checkout. You can create text, number, select, date, checkbox, and textarea fields.

​
Base URL

https://api.polar.sh/v1/custom-fields

​
Authentication

All custom field endpoints require authentication with an Organization Access Token or Personal Access Token with appropriate scopes.

​
List Custom Fields

curl -X GET "https://api.polar.sh/v1/custom-fields" \
  -H "Authorization: Bearer polar_oat_..."

​
Query Parameters

​
organization_id
string
Filter by organization ID
​
page
integer
default:1
Page number
​
limit
integer
default:10
Results per page (max 100)

​
Response

Returns an array of custom field objects with their configuration.

​
Get Custom Field

Retrieve a specific custom field by ID.
cURL
curl -X GET "https://api.polar.sh/v1/custom-fields/{id}" \
  -H "Authorization: Bearer polar_oat_..."

​
Path Parameters

​
id
string
required
The custom field ID

​
Create Custom Field

Create a new custom field for checkout forms. 
curl -X POST "https://api.polar.sh/v1/custom-fields" \
  -H "Authorization: Bearer polar_oat_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "text",
    "slug": "company_name",
    "name": "Company Name",
    "required": true,
    "properties": {
      "min_length": 2,
      "max_length": 100
    }
  }'

​
Request Body

​
type
string
required
Field type: text, number, select, date, checkbox, textarea
​
slug
string
required
Unique identifier for the field (immutable, alphanumeric with underscores)
​
name
string
required
Display name shown to customers
​
required
boolean
default:false
Whether the field is required
​
properties
object
Type-specific properties:
  • text/textarea: min_length, max_length
  • number: min, max, integer_only
  • select: options (array of )
  • date: min_date, max_date
​
metadata
object
Custom metadata for the field

​
Field Type Properties

{
  "type": "text",
  "properties": {
    "min_length": 1,
    "max_length": 255
  }
}

{
  "type": "number",
  "properties": {
    "min": 0,
    "max": 1000,
    "integer_only": true
  }
}

{
  "type": "select",
  "properties": {
    "options": [
      {"value": "small", "label": "Small (1-10)"},
      {"value": "medium", "label": "Medium (11-50)"},
      {"value": "large", "label": "Large (50+)"}
    ]
  }
}

{
  "type": "date",
  "properties": {
    "min_date": "2024-01-01",
    "max_date": "2024-12-31"
  }
}

{
  "type": "checkbox",
  "name": "Accept Terms"
}

{
  "type": "textarea",
  "properties": {
    "min_length": 10,
    "max_length": 1000
  }
}

​
Update Custom Field

Update an existing custom field.
cURL
curl -X PATCH "https://api.polar.sh/v1/custom-fields/{id}" \
  -H "Authorization: Bearer polar_oat_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Company Name",
    "required": false
  }'

​
Path Parameters

​
id
string
required
The custom field ID

​
Request Body

​
name
string
Updated display name
​
required
boolean
Updated required status
​
properties
object
Updated type-specific properties
​
metadata
object
Updated metadata
The slug and type fields cannot be changed after creation.

​
Delete Custom Field

Delete a custom field. This will remove it from all checkout forms.
cURL
curl -X DELETE "https://api.polar.sh/v1/custom-fields/{id}" \
  -H "Authorization: Bearer polar_oat_..."

​
Path Parameters

​
id
string
required
The custom field ID to delete

​
Response

Returns 204 No Content on success.

​
Accessing Field Data

Custom field responses are stored in the order’s custom_field_data as JSONB: 
const order = await polar.orders.get(orderId);
console.log(order.custom_field_data);
// {
//   "company_name": "Acme Corp",
//   "team_size": "medium",
//   "start_date": "2024-06-01"
// }

​
Use Cases

​
Lead Qualification

await polar.customFields.create({
  type: 'select',
  slug: 'company_size',
  name: 'Company Size',
  required: true,
  properties: {
    options: [
      { value: '1-10', label: '1-10 employees' },
      { value: '11-50', label: '11-50 employees' },
      { value: '51-200', label: '51-200 employees' },
      { value: '200+', label: '200+ employees' }
    ]
  }
});

​
Compliance

await polar.customFields.create({
  type: 'checkbox',
  slug: 'gdpr_consent',
  name: 'I agree to the GDPR terms',
  required: true
});

​
Custom Onboarding

await polar.customFields.create({
  type: 'textarea',
  slug: 'use_case',
  name: 'How will you use this product?',
  required: false,
  properties: {
    minLength: 20,
    maxLength: 500
  }
});

Build docs developers (and LLMs) love

Get started for freeTalk to us