Setting up custom fields

Custom fields give you the ability to store custom data in Orders, Tickets, Contacts and Events. In its simplest form it allows you to store extra data with a Contact. Let’s say you want to keep track of who is subscribed to your newsletter. You can easily add a checkbox that is shown whenever you add or edit a Contact.

Custom fields are treated internally exactly the same way as regular fields, so there is no performance penalty for using them. Several datatypes are available: simple string, int or date types, but also checklist or optionset types.

Custom fields for Orders and Contacts can be configured to be shown during the checkout process. This makes it possible to ask the buyer extra info during the checkout proces, either on the Order or on the Contact level. Use cases for this are for example:

  • “Where do you know us from?” (for an order)
  • “Newsletter opt-in” (for a contact)

As custom fields are also exposed via the Ticketmatic API it also enables you to control external systems via custom field data. An example for this is that you could list all currently published Events on your website via a (custom) CMS integration. If a custom field called “Genre” is added to “Event”, your CMS could also list the “Genre” of the “Event” on your website. This way all your “Event” related data is stored in one place.

Custom fields are managed in the Custom fields module in the Settings app. Click the button below to go there:

Go to custom fields

Getting started: setting up a new custom field

Let’s add a new customfield for “Contact”. The custom field’s name will be “Newsletter” and it will indicate if the Contact is subscribed to your newsletter.

To create this custom field execute the following steps:

  1. Go to the “Settings app”.
  2. Click on “Custom fields” (in the “System” section).
  3. In the “Contact field” section, click on “Add”.
  4. Fill in the name “Newsletter”.
  5. Fill in the key “newsletter”. This key will be seen whenever an object is requested via the API or when the public data model is used (To define a new “Filter” for example).
  6. Indicate if the field is required, in this case it’s not needed to enable this.
  7. Set the Data type to “Boolean”.
  8. Set the visibility to “Backoffice”. This means that the custom field will be visible in the backoffice applications.
  9. Click “Save”.

If you go back to the list of custom fields you can see the new custom field in the “Contact” section.

When you add a new Contact you will see the new “Newsletter” field in the “Extra” section on the right side of the screen. The field will also appear when you edit an existing Contact.


Custom fields visibility

For each custom field, the visibility can be defined:

  • Hidden: the custom field is only available through the API or the public data model. It will not be visible in the applications. This can be used to integrate with external services.
  • Backoffice: the custom field is available in the backoffice applications, so users can view and edit the value of the custom field
  • Checkout: the custom field is available during the checkout process. This visibility is only possible for custom fields of type Order or Contact.
  • Read-only in sales views: the custom field is read-only available for users during sales. This visibility is only possible for custom fields of type Event.

When setting the visiblity to Checkout, you can further refine when the custom field will be shown by selecting the sales channels and optionally provide an availability script. More info on creating availability scripts

Availability

Custom fields of type Read-only in sales views can be used to provide event information to users during sales. The event information will be available during box office sales and external sales.

Read-only sales info


Custom field types

The table below lists all the possible custom field types, the best way to use them and how they are represented in the UI. To see how they are returned via the API, check the API documentation

TypeUsageUI element
StringSmall amounts of text (under 255 characters).Simple text input field.
TextLarger amounts of text (larger than 255 characters).Simple text input field
Text (with formatting)Larger amounts of text (larger than 255 characters). Allows basic Markdown formatting (headers, bold/italic, links)Text input field
IntegerWhole numeric value, for instance 0, 1, 238. But not 234.23Number input field
DecimalNumeric value, for instance 2347.234Number input field
DateDate, for instance 2015-03-23 12:30Date input field. Will show a datepicker with time input.
BooleanCheckboxCheckbox
Multi-language stringSmall amounts of translatable text (under 255 characters). Translations are enabled via the translations workflow.Text input field (+translation workflow)
Multi-language textLarger amounts of translatable text (larger than 255 characters)Textarea (+translation workflow)
Single selectChoose a single option from a list of values.Dropdown
Single select (option set)Choose a single option from a list of values.List of radio buttons
Multi selectChoose one or more options from a list of values.Dropdown with ability to select multiple values
Multi select (checklist)Choose one or more options from a list of values.List of checkboxes

Using custom fields

From the backoffice applications

Custom fields are easy to use from the backoffice applications. Each time a Contact, Order or Event is edited the UI will show the defined custom fields in a specific section. A user will not see the difference between regular and custom fields.

From the API or the public data model

It’s also possible to fetch the data behind the custom fields via the Ticketmatic API. If you request a Contact, Order or Event via the API it will also contain a set of fields that start with c_, these are all custom fields. The custom field are also autmatically exposed through the public data model.

For example, the previously created custom field “Newsletter” will be added to the Contact object whenever you request it via the API. The key for this customfield will be c_newsletter because we filled in “newsletter” as key. You can find more information about custom fields in our API here.

You can query the public data model for example like this:

1 select id,c_newsletter from tm.contact

Questions?

We're always happy to help! Send us an e-mail