Setting up custom fields

Custom fields give you the ability to store custom data for the most important objects in your account, like Orders, 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:

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:

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

You can define custom fields for following items:

• Contact
• Delivery scenario
• Event
• Event location
• Order
• Payment method
• Payment scenario
• Price type
• Product
• Ticket

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

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.

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

Custom field values

Some types of custom fields allow you to select one or more options from a list of possible values. These values are defined in a separate module Custom field values. For each custom field you can specify whether the values should be ordered alphabetically or with a custom sort order that you define.

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:

1select id,c_newsletter from tm.contact