Payload Schema

When you configure your app's triggers, you must provide a payload schema. The payload schema defines the required and validated fields in your event payloads, and it's used to display available options to your users when they configure their automations.

A payload schema allows you to define scheduled events and can give your users enriched payloads by linking your trigger to a site contact. Wix also uses the payload schema to determine the available actions for a trigger.

The payload schema must be a JSON Schema object. See the tables in Schema Properties (below) for the expected structure.

Connecting payload schema properties

When you configure your trigger to connect a contact ID or a scheduled event, you're indicating that Wix can handle your trigger in a specialized way and present additional automation configuration options to users. The requirements for each property, as well as how Wix handles these changes, are covered in this section.

Contact ID property

You can connect a payload property to a contact ID when the property's value will always be a contact ID from Wix. You can retrieve the relevant contact ID using the Contacts API.

Requirements:
This option is available only for properties where the type is "string" and the format is "uuid".

Effect on your user's automations:
Connecting a payload property to a contact ID allows users to use the related contact information (such as name, emails, or phone numbers) in their automation actions. It also allows them to email the contact as an automation action.

Scheduled event property

You can set a payload property as a scheduled event when the property's date-time will always be at some point in the future, relative to the time the event is reported. Some examples of scheduled event properties are an invoice due date or a session start time. For more information, see Overview of events.

Requirements:
This option is available only for properties where the type is "string" and the format is "date-time".

Effect on your user's automations:
Setting a payload property as a scheduled event allows users to configure automations to run before, at the time of, or after the time specified in the payload.

Schema properties

These properties are at the schema's root level:

Property	Data type	Description
$schema	string	When you save the trigger configuration, Wix overrides this property to set it to "http://json-schema.org/draft-07/schema".
type	string	Required. Must be "object".
properties	object	Required. Object containing payload property metadata as key-object pairs. See the properties object below for details.
required	array	List of property keys that are required to be present in the reported event payload.
additionalProperties	boolean	When you save the trigger configuration, Wix overrides this property to set the value to true, which allows additional, unspecified properties to be sent in the payload.

The properties object

properties is an object that contains key-object pairs.

The key name can include only alphanumeric characters or underscores (A-Z, a-z, 0-9, _). It cannot start with an underscore.

The paired object contains display and validation metadata. This table gives the expected data structure:

Property	Data type	Description
type	string	Supported values: string, number, integer, boolean, array, object. Required. Expected data type of the payload property. Note: Only the 1st-level properties object supports "object" and "array" types.
title	string	Required. Display name for the property. Shown to users when they create or edit an automation.
examples	array	Example values, displayed as placeholders when users test certain automation actions. Must be the same data type defined in type. Required in the 1st-level properties object. Omitted in the 2nd-level properties object.
format	string	Validated string format. Used only when type is "string". See built-in formats (from the JSON Schema 2020-12 docs) for supported formats. If set to "uuid", the property can be connected to a site's contacts. This allows Wix to enrich the payload with contact data and allows the site owner to use actions that work with their contacts. If set to "date-time", the property can be used to add support for scheduled events.
identityType	string	Supported value: contact If the property is specified with Connect a property to a contactId, identityType is automatically set to "contact". In all other cases, identityType is omitted. Limited to 1 payload property.
futureDate	boolean	If the property is specified with Allow scheduled events with predefined date & time, futureDate is automatically set to true. In all other cases, futureDate is omitted. Limited to 1 payload property.
items	object	Object that contains a list of array items. Required if type is "array". Omitted for other data types. See the items object below for details.
properties	object	Object containing 2nd-level payload property metadata as key-object pairs. Accepts the same data as the 1st-level properties object, but can contain only strings, numbers, integers, or booleans. Required if type is "object". Omitted for other data types.
required	array	List of property keys that are required to be present in the reported event payload. Used only when type is "object" or "array".

The items object

items is an object that contains an array schema.

Property	Data type	Description
type	string	Required. Must be set to "object".
properties	object	Required. Object containing 2nd-level payload property metadata as key-object pairs. Accepts the same data as the 1st-level properties object. See the properties object above for details.
required	array	List of property keys that are required to be present in the reported event payload.