Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/polarsource/polar/llms.txt

Use this file to discover all available pages before exploring further.

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