Custom events are used to trigger custom automation workflows through API. All custom events can have custom fields for any type of additional information, that could be used in the content of automated emails.
Explanation of Terms
There are basically two main terms used in this article:
- custom events,
- custom fields.
Custom event is something that happens on your store and is not passed on to Omnisend as a part of the standard API integration. This can be anything from loyalty points to some very custom information. They can be used as a trigger for your custom automation workflow.
Custom field is a property that a custom field contains. One custom event can have as many custom fields as you need. Custom fields can be used in the content of automated emails for personalisation purposes.
Custom events along with custom fields are currently only available for all integrations through our latest API. It is not available on Shopify, Bigcommerce or Tictail at the moment.
To start with custom events, you will need to set everything up from both your account side and your API side.
To start the setup from account side you will need to head to your account settings and choose Custom events from Integrations & API dropdown menu.
1. Add new custom event. Click Create event to start the process, add the name of your custom event and hit save. You can repeat these steps as many times as you need for every single custom event you need (up to 30 custom events at once).
2. Add custom fields. Once you have your custom event you can add custom fields to it. To set a custom field up, you will need to add:
- Custom field name - this name will be only seen on your account and can later be adjusted.
- Custom field system name - this is the system name that will be used to pass through API. This field cannot be adjusted later on.
- Custom field type - this defines how your data should be interpreted. Usually this is something your developer should help you with. You can choose from a list of field types (more about them below).
- This custom field is required - allows you to choose whether this particular field is very important and should be passed each time through API.
Custom field types:
- integer - should be used to pass number values only.
- float - should be used for numbers with a floating point.
- boolean - should be used for true or false values.
- string - should be used to pass any string of characters that should only used as values and not for calculations.
- email - should be used to pass an additional email address. If a second email address is not needed, there is no need to use this field.
- url - should be used to pass links.
- date - should be used to pass date information.
- dateTime - should be used to pass time information.
In most cases this information should come from your developer as it will be used in the code.
3. Enable and disable your custom events. To enable and disable custom events just use the toggle next to the event in question. By enabling a new custom event you agree that it's settings will be locked and custom field system name, custom field type, and required checkbox cannot be edited. You can still rename the custom field.
Disabling a custom event means that it is no longer being used by your account (regardless if you continue pushing it through API) and all automation sequences that use this particular custom event will be discontinued.
Reenabling a custom event does not automatically reenable the previously disabled sequences that this particular custom event is used at. Those should be manually reenabled at Automation.
4. Pass the Event ID to your developer. Event ID will be needed to pass all the custom event information through API. Setup from account's end is finished here and the development process should now move to the API end. You can also now start adding these fields on your automation or use it as custom data in your automated emails.
Once everything is setup from account's end, you can move to API setup. You should refer to our API documentation for further information.