By default, the Checkout form will only ask basic information from the customer to fulfill the order: a name, an email address, billing information, etc. But you might need more! A few examples:
- A checkbox asking the customer to accept your terms
- An opt-in newsletter consent
- A select menu to ask where they heard from you
- …
With Polar, you can easily add such fields to your checkout using Custom Fields.
Create Custom Fields
Custom Fields are managed at an organization’s level. To create them, go to Settings → Custom Fields. You’ll see the list of all the available fields on your organization.
Click on New Custom Field to create a new one. You can also manage them programmatically using the Custom Fields API.
Type
The type of the field is the most important thing to select. It determines what type of input will be displayed to the customer during checkout.
The type can’t be changed after the field is created.
We support five types of fields:
Text
This will display a simple text field to input textual data. By default, it’ll render a simple input field but you can render a textarea by toggling the option under Form input options.
Under Validation constraints, you can add minimum and maximum length validation.
Underneath, the data will be stored as a string.
Number
This will display a number input field. Under Validation constraints, you can add minimum (Greater than or equal) and maximum (Less than or equal) validation.
Underneath, the data will be stored as an integer.
Date
This will display a date input field. Under Validation constraints, you can add minimum and maximum validation.
Underneath, the data will be stored as a string using the ISO 8601 format.
Checkbox
This will display a checkbox field.
Underneath, the data will be stored as a boolean (true or false).
Select
This will display a select field with a predefined set of options. Each option is a pair of Value and Label, the first one being the value that’ll be stored underneath and the latter the one that will be shown to the customer. At least one option is required, and you can drag options to reorder them.
Slug and name
The slug determines the key that’ll be used to store the data inside objects related to the checkout, like Orders and Subscriptions. It must be unique across your organization and can only contain lowercase letters, numbers, hyphens and underscores. You can change it afterwards, we’ll automatically update the data stored on existing Checkouts, Orders and Subscriptions to reflect the new slug.
The name is what will be displayed to you to recognize the field across your dashboard. By default, it’ll also be the label of the field displayed to the customer, unless you customize it under Form input options.
Those options allow you to customize how the field is displayed to the customer. You can set:
- The label, displayed above the field
- The help text, displayed below the field
- The placeholder, displayed inside the field when there is no value
The label and help text support basic Markdown syntax, so you can add bold, italic or even links.
Add Custom Field to Checkout
Custom Fields are enabled on Checkout specifically on each product. While creating or updating a product, expand the Checkout Page section and select the fields you want to include under Checkout Fields.
Note that you can make each field Required for that product.
If you make a checkbox field required, customers will have to check
the box before submitting the checkout. Very useful for terms acceptance!
custom_field_data property, keyed by the slug of each field.
Read data
The values input by the customer are stored on the Order or Subscription resulting from the checkout. From your dashboard, open an order or subscription from the Sales section: the values are displayed under the Custom Fields section of the detail view.
This data is also available from the Orders and Subscriptions API, under the custom_field_data property. Each value is referenced by the slug of the field.
