Collect custom data at checkout with custom fields

Define structured fields — text, number, date, checkbox, or select — and attach them to checkout sessions to capture data like VAT IDs or seat counts.

Custom fields let you collect arbitrary structured data from customers at checkout — company names, VAT IDs, license seat counts, terms acceptance, and more. Define the fields once in Polar via the LaravelPolar facade, attach them to a checkout session, and read the captured values back from the resulting Order.

How it flows: Create field definition in Polar → attach slug-keyed data to a checkout session with withCustomFieldData() → customer fills it in (or it’s pre-filled) → read it back from $order->customFieldData() after purchase.

Field types

Polar supports five field types, each with its own create class:

Type	Class	Stores
Text	CustomFieldCreateText	Free-form string
Number	CustomFieldCreateNumber	Numeric value
Date	CustomFieldCreateDate	Date value
Checkbox	CustomFieldCreateCheckbox	Boolean (true/false)
Select	CustomFieldCreateSelect	One of N options

Creating a custom field

1. Choose a field type and create the definition

   Pass a create class to LaravelPolar::createCustomField(). The slug is a unique machine-readable identifier used to reference the field’s value later.

   use Danestves\LaravelPolar\LaravelPolar;
   use Polar\Models\Components;
   
   $field = LaravelPolar::createCustomField(
       new Components\CustomFieldCreateText(
           slug: 'company',
           name: 'Company name',
           properties: new Components\CustomFieldTextProperties(),
       )
   );
   

   The same pattern works for all field types:

   // Number field
   LaravelPolar::createCustomField(new Components\CustomFieldCreateNumber(
       slug: 'seats',
       name: 'Number of seats',
       properties: new Components\CustomFieldNumberProperties(),
   ));
   
   // Checkbox field (e.g. terms acceptance)
   LaravelPolar::createCustomField(new Components\CustomFieldCreateCheckbox(
       slug: 'accept_terms',
       name: 'I accept the terms of service',
       properties: new Components\CustomFieldCheckboxProperties(),
   ));
   
2. Manage the definition over time

   Use the management methods on the facade to keep your field definitions up to date:

   // Update a field's display name
   LaravelPolar::updateCustomField('cf_xxx', new Components\CustomFieldUpdateText(
       name: 'Organisation name',
   ));
   
   // Delete a field
   LaravelPolar::deleteCustomField('cf_xxx');
   
   // List all custom fields
   $response = LaravelPolar::listCustomFields();
   
   // Fetch a single field
   $field = LaravelPolar::getCustomField('cf_xxx');
   
3. Attach field data at checkout

   When creating a checkout session, call withCustomFieldData() and pass the slug-keyed values you want to pre-fill or require:

   $user->checkout('product_id_123')
       ->withCustomFieldData([
           'company'      => 'Acme, Inc.',
           'seats'        => 10,
           'accept_terms' => true,
       ]);
   

   The customer sees the fields rendered inside the Polar checkout form. Any fields you do not pre-fill can be completed by the customer.

Reading custom field data from an order

After a customer completes checkout, retrieve the captured field values from the Order model:

$data = $order->customFieldData();
// array<string, string|int|bool|\DateTime|null>

Access individual values by their slug:

$company = $order->customFieldData()['company'];  // string
$seats   = $order->customFieldData()['seats'];    // int

customFieldData() fetches the data from Polar on demand — it is not stored in your local database. The result is memoized on the Order instance for the lifetime of the request, so calling the method multiple times in the same controller only hits the Polar API once.