> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt ## Resource: The Trigger Payload Schema ## Article: The Trigger Payload Schema ## Article Link: https://dev.wix.com/docs/api-reference/business-management/automations/triggers/the-trigger-payload-schema.md ## Article Content: # The Trigger Payload Schema The payload schema is at the core of your trigger. It determines what data is passed to Wix when your event is reported, what actions your trigger can be used with, and how much control your users have over their automations. This article will go over all the annotations you can add to the schema, and give you examples that you can copy and work off to build your own effective schema. ## Before you begin Before you start creating the schema, here’s a few important things to note: * The payload schema is a [JSON schema](https://json-schema.org/), and therefore follows the JSON schema guidelines. * The schema must have a minimum of one property. * The data you pass to [Report Event](https://dev.wix.com/docs/rest/business-management/automations/triggers/triggered-events/report-event.md) must align with the payload schema you create. * Users can view the properties you define in the payload when they work with certain actions, such as [Run Velo code](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/automations/about-custom-actions.md), or set up [conditions](https://dev.wix.com/docs/rest/business-management/automations/terminology.md#condition) in their automations.Let’s start by looking at the top-level schema structure. ## Top-level properties When you create your trigger in the app dashboard, the best way to start [building your payload schema](https://dev.wix.com/docs/rest/business-management/automations/triggers/add-a-trigger-to-your-app.md#step-2--configure-the-payload-schema) is to use the **Generate from Sample Data** button and enter a sample payload. This automatically creates a JSON schema for you, with the correct formatting and annotations. If you already have your own sample data, feel free to enter that (note that it must be in JSON format). Otherwise, press the `tab` key to use the data that already appears in the modal: ```json { "formId": "ca6385a-4fb6-bca0-ba0b286b6b75", "formName": "Contact Form", "submitterId": "66d55169-2bdb-4419-acdd-1883047c" } ``` Once you add sample data, click **Convert to schema**. The generator creates a schema that looks like this: ```json { "type": "object", "properties": { "formId": { "type": "string", "title": "Form Id", "examples": [ "ca6385a-4fb6-bca0-ba0b286b6b75" ] }, "formName": { "type": "string", "title": "Form Name", "examples": [ "Contact Form" ] }, "submitterId": { "type": "string", "title": "Submitter Id", "examples": [ "66d55169-2bdb-4419-acdd-1883047c" ] } }, "required": [ "formId", "formName", "submitterId" ] } ``` If you used your own sample payload, you’ll have different key-object pairs inside the `properties` object. But for now, let’s ignore the nested objects and look only at the top-level. Every payload schema that you generate will have three top-level keys: * `type`: This designates the type of the overall schema object, and always has a value of `”object”`. This key is required, so don’t remove it and don’t change its value. * `properties`: This object contains a set of nested objects that define the fields in your payload. This is the most significant part of your schema, and we review it in detail in the [properties](https://dev.wix.com/docs/rest/business-management/automations/triggers/the-trigger-payload-schema.md#the-properties-object) section. `Properties` is a required top-level key. * `required`: This is an optional, but recommended array that lists the properties that must be passed to Wix when your app reports the event. If the payload passed to [Report Event](https://dev.wix.com/docs/rest/business-management/automations/triggers/triggered-events/report-event.md) is missing any of the fields listed in the array, the trigger won’t activate its automation. If any of your properties are necessary for actions that follow the trigger, add them to `required`. The table below summarizes these top-level keys: | Property | Data type | Description | | ------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | string | *Required*. Must be `"object"`. | | `properties` | object | *Required*. Object containing payload property metadata as key-object pairs. See [the `properties` object](#the-properties-object) below for details. | | `required` | array | List of property keys that are required to be present in the [reported event](https://dev.wix.com/docs/rest/business-management/automations/triggers/triggered-events/report-event.md) payload. | ### The `properties` object The `properties` object is responsible for defining the fields in your trigger payload. The object contains one or more key-object pairs, each of which corresponds to a field in the payload. For example, if you have the following key-object pairs in `properties`: ```json "properties": {    "contactId": {       "type": "string",       "format": "uuid",       "title": "Contact ID",       "description": "The ID of the customer",       "examples": ["c4d4b61f-5a88-4b45-8bfb-5b7bda7d29e0"]     },    "numberOfsessions": { "type": "integer", "title": "Total previous sessions", "description": "The number of sessions the client has previously booked", "examples": [4]     } } ``` Your payload will contain the following 2 properties: ```json {    "contactId": "",    "numberOfSessions": } ``` Key names can include only alphanumeric characters or underscores (`A-Z`, `a-z`, `0-9`, `_`). They cannot start with underscores.The table below lists the possible keys that the paired object may contain. Some of the keys may vary depending on the object’s data type. However, every paired object must contain the following 4 keys: * `type:` Defines the field data type. Accepted values include standard JSON types or Wix custom types. The table below summarizes these types and we discuss them in detail in the following section. * `title`: Sets the field title. Users will see this title when they set up your trigger in the [Automations Builder](https://support.wix.com/en/article/wix-automations-creating-an-automation-with-the-new-builder#step-2-choose-a-trigger). * `examples`: Gives examples of valid values for the field. Users will see these examples when they set up your trigger in the Builder. * `description`: Gives users a brief explanation of the payload field. Though a schema property is valid without this key, we require it for user experience purposes. The description is visible to users in the Builder, and having an explanation of the field helps them better understand how to configure and use your trigger. The simple payload schema above shows some basic examples of properties. Each property contains `type`, `title`, `examples` and `description`. However, most properties you add to your schema include more annotations than just these four. In the next section, we discuss each data type and its possible annotations. Understanding these annotations will help you create a richer payload schema. | | | | | -------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Property** | **Data type** | **Description** | | `type` | string |

Supported values: 
- Standard JSON types: `string`, `number`, `integer`, `boolean`, `array`, `object`.
- Wix custom types: `MONEY`, `ATTACHMENT`

*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.

| | `description` | string |

*Required*. A short description of the property that is displayed to users in the site dashboard.

| | `format` | string |

Validated string format. Used only when `type` is `"string"`. See [built-in formats](https://json-schema.org/understanding-json-schema/reference/string.html#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. A property annotated with `futureDate` must be marked as required.

| | `items` | object |

Object that contains a list of array items.

Required if `type` is `"array"`. Omitted for other data types. See [the `items` object](https://dev.wix.com/docs/rest/business-management/automations/triggers/the-trigger-payload-schema.md#the-items-object) below for details.

| | `oneOf` | array |

Creates a field that lets a user select one from multiple options. See the [`oneOf`](#the-oneof-object) 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](https://dev.wix.com/docs/rest/business-management/automations/triggers/triggered-events/report-event.md) payload.

Used only when `type` is `"object"` or `"array"`.

| ### The `items` object The items object is a special object only required for properties with data type `“array”`. The table below gives the keys `items` must contain when defined in the payload 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](#the-properties-object) above for details. | | `required` | array | List of property keys that are required to be present in the [reported event](https://dev.wix.com/docs/rest/business-management/automations/triggers/triggered-events/report-event.md) payload. | ### The `oneOf` object `oneOf` is an array of objects. It defines a field in which a user can choose one of multiple options. | Property | Data Type | Description | | ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------ | | `type` | string | *Required*. Defines the expected data type of the option. Must match the parent type defined for the entire field. | | `title` | string | *Required*. The option value displayed to users. This value can be translated into another language. | | `const` | varies | Required if type is `"string"`. Strings must be in English. The option value that is sent to the backend for validation. | | `description` | string | Provides more information about an option. This value can be translated into another language. | ## Data types This section details each of the possible data types you can assign to properties, how to define each one, and the available annotations for each type. ### String property To define a string property in the payload, set `type` to `”string”`. For a string type, you can also define specific formats. To do so, add the `format` key to the object and give it one of the following values: * `date-time` * `date` * `time` * `email` * `uuid` * `uri` * `regex` * `number` (**Note**: You can use this format to pass a string-type number, or just use the [number](#number-property) type.) There are also several special keys that are added to the property if you decide to enrich your trigger: * Strings with format `uuid` may contain the `identityType` key. This key is added automatically if you [connect contact ID data](https://dev.wix.com/docs/rest/business-management/automations/triggers/add-a-trigger-to-your-app.md#add-contact-data-to-the-payload) to the property when you configure your trigger. * Strings with format `date-time` may contain the `futureDate` key. This is a required key that is added automatically if the date-time field is configured to allow [scheduled triggers](https://dev.wix.com/docs/rest/business-management/automations/triggers/add-a-trigger-to-your-app.md#allow-scheduled-events-with-predefined-date--time). Here’s an example of a string property with date-time format: ```json "orderDate": { "type": "string", "format": "date-time", "title": "Order date", "description": "Date and time when the order was placed.", "examples": ["2024-09-05T15:30:00Z"] } ``` ### Number property To define a number property, set `type` to `”number”`. Here’s an example: ```json "averageScore": { "type": "number", "title": "Average score", "description": "The user's average score across all quizzes.", "examples": [79.43] } ``` Note that you can also pass a number as a string type, using the `number` or `DECIMAL_VALUE` formats. ### Integer property To define an integer property, set `type` to `”integer”`. Here’s an example: ```json "previousSessions": { "type": "integer", "title": "Number of previous sessions", "description": "The number of previous sessions the customer has joined.", "examples": [ 7 ] } ``` ### Boolean property To define a boolean property, set `type` to `”boolean”`. Here’s an example: ```json "invoicePaid": { "type": "boolean", "title": "Invoice has been paid", "description": "Indicates if the customer has paid the invoice.", "examples": ["true"] } ``` ### Array property To define an array property, set `type` to `”array”`. In addition to `type`, `title`, and `examples`, an array property requires the [`items`](#the-items-object) key. `items` is an object that defines the data type of the elements in the array. If the elements are objects, it also defines the following: * A nested `properties` object. This defines the properties of the objects in the array and is mandatory. * An nested `required` array. This defines the properties that each element in the array must contain. At this level, `required` is optional. Here’s a very simple example: ```json "wishlist": { "type": "array", "title": "Wishlist", "description": "List all the things you want for your birthday", "examples": [ ["Tesla", "PS4", "cruise tickets"] ], "items": { "type": "string" } } ``` In this case the array elements are strings, so `items` only needs to define the `type` key. Here’s a more complex example that uses objects as array elements: ```json "logins": { "type": "array", "title": "logins", "examples": [ [ { "contactId": "a2e7684d-1812-46a2-aecb-c4b27ed4aa91", "lastLogin": "2024-09-03" }, { "contactId": "2b699cd4-7142-4fa8-96a4-320d7a82c4c5", "lastLogin": "2024-06-15" } ] ], "items": { "type": "object", "required": ["contactId", "lastLogin"], "properties": {     "contactId": {         "title": "Name",         "type": "string",         "format": "uuid"     },     "lastLogin": {         "title": "Last login",         "description": "Date of last login",         "type": "string",         "format": "date"     } } } } ``` Here `items` defines the expected properties of each object in the array. It also defines the `required` key, indicating that any objects in the `logins` array must contain both of the properties that were defined. ### Object property To define an object property, set `type` to `”object”`. In addition to `type`, `title`, and `example`, you’re required to define a `properties` object for this type of property. This nested `properties` object defines the fields inside your object property. Optionally, you can define a `required` array to indicate which nested object properties are mandatory. Here’s an example of an object property: ```json "businessInfo": { "title": "Business Information", "type": "object", "examples": [ {     "businessName": "Friendly's",     "businessAddress": "33 Main St, New York, NY" }, { "businessName": "Yukon Deli", "businessAddress": "45 Dalton Highway, Fairbanks, AK" } ], "properties": { "businessName": {     "type":"string",     "title": "Business name" }, "businessAddress": {     "type": "string",     "title": "Business address" } } } ``` Note that this particular example doesn’t define a `required` array. ### OneOf property To define a oneof, set type to `“string”` and add a `oneOf` annotation. A oneOf defines a dropdown field in which a user can choose one of multiple options. Here’s an example: ```json "paymentStatus": { "title": "Payment status",   "type": "string",   "examples": ["Pending", "Paid", "Payment failed"],   "oneOf": [     {     "type": "string",     "title": "Pending",     "const": "pending" }, {     "type": "string",     "title": "Completed",     "const": "completed" }, {     "type": "string",     "title": "Failed",     "const": "failed" }, {     "type": "string",     "title": "Refunded",     "const": "refunded" } ] } ``` ## Special annotations While the payload schema accepts the standard JSON annotations, there are also a number of custom annotations made by Wix that you can apply to your schema. We’ll go over these special annotations here and how you can apply them. ### `futureDate` This annotation is added automatically to a property if the property is configured for scheduled triggers. The property must also be added to the `required` array. The property must be of type `”string”` and format `“date-time”`. `futureDate` is a boolean that is always marked true. Here’s an example usage of the annotation: ```json "dateSubmitted": { "format": "date-time", "examples": [     "2024-07-06" ], "title": "Date Submitted", "type": "string", "futureDate": true }, ``` ### `identityType` This annotation is added automatically to a property that is connected to a contact ID. The connected property must be of type `”string”` and format `”uuid”`. `identityType` is a string with value `contact`. Don’t change this value if you have selected the property to connect to a contact ID, or it may not work properly when you report the event. Here’s an example usage: ```json "submitterId": { "type": "string", "title": "Submitter Id", "format": "uuid", "examples": [     "4084b830-39d9-46f3-9e6e-56be95997efa" ], "identityType": "contact" } ``` ### `MONEY` This annotation is used to represent a price. It combines the numeric value with its currency symbol (e.g., $15). Here’s an example usage: ```json "price":{ "title": "Price", "type": "object", "wixCustomType": "MONEY", "examples": [ { "value": 15, "currency": "EUR" }, { "value": 20, "currency": "USD" } ], "properties": { "value": { "title": "Money value", "type": "string" }, "currency": { "title": "Currency", "type": "string" } }, "required": ["value", "currency"] } ``` ### `ORDER_ID` This annotation is used to link a trigger to an action that requires an order ID to function. For example, if the trigger schema includes the `ORDER_ID` annotation, the "Payment Request" action will be available for users to select when building an automation. Without this annotation, actions that depend on an order reference, like "Payment Request," will not appear as options. Here’s an example usage: ```json "order_id":{ "format": "uuid", "examples": [ "2231beb4-33ec-471b-9143-d6b57aec7c00" ], "wixCustomType": "ORDER_ID", "title": "Order ID", "type": "string" } ``` ### `IMAGE_URL` This annotation detects dynamic variables containing an image URL in the email content, and displays the URL as an actual image. Here’s an example usage: ```json "service_image_url":{ "title": "Service image URL", "type": "string", "format": "uri", "wixCustomType": "IMAGE_URL", "examples": [ "https://static.wixstatic.com/media/my-service-img.png" ] } ``` ### `ATTACHMENT` This annotation enables users to add attachments to their emails by specifying a downloadable URL. The attachment requires both a file name and a valid download URL. ```json "ics": { "title": "Calendar Invite File (ICS Format)", "type": "object", "wixCustomType": "ATTACHMENT", "examples": [ { "fileName": "event-invite.ics", "downloadUrl": "https://www.wix.com/bookings/automations/v2/ics/123" } ], "properties": { "fileName": { "type": "string", "title": "Attachment Filename", "description": "The name of the calendar invite file to be displayed to the email recipient." }, "downloadUrl": { "type": "string", "title": "File Download URL", "format": "uri", "description": "The direct URL where the recipient can download the calendar invite file." } }, "required": [ "fileName", "downloadUrl" ] } ``` ### `number` This format is used to represent a string as a numerical value. It allows users to set conditions with numeric operators, even when the property type is defined as a string. Here’s an example usage: ```json "price": { "type": "string", "format": "number", "title": "Item price", "description": "Price of the item in the order." } ``` ## Full schema example Below is an example of a complete payload schema: ```json { "type": "object", "$schema": "http://json-schema.org/draft-07/schema", "required": [ "id", "contactId", "totalAmount", "orderDate", "status", "items" ], "properties": { "id": { "type": "string", "format": "uuid", "title": "Order ID", "description": "Unique identifier for the order.", "examples": ["3d6f7f5e-0bdf-4f87-bb98-6a06b03b8b44"] }, "contactId": { "type": "string", "format": "uuid", "title": "Contact ID", "description": "This is the ID of the order buyer.", "identityType": "contact", "examples": ["c4d4b61f-5a88-4b45-8bfb-5b7bda7d29e0"] }, "totalAmount": { "type": "string", "format": "DECIMAL_VALUE", "title": "Total amount", "description": "Total value of the order.", "examples": ["1234.56"] }, "orderDate": { "type": "string", "format": "date-time", "title": "Order date", "description": "Date and time when the order was placed.", "examples": ["2024-09-05T15:30:00Z"] }, "shipmentDate": { "type": "string", "format": "date", "title": "Shipment date", "description": "Date when the order is expected to be shipped.", "examples": ["2024-09-10"] }, "deliveryTime": { "type": "string", "format": "time", "title": "Expected delivery time", "description": "Time when the order is expected to be delivered.", "examples": ["14:00:00"] }, "customerEmail": { "type": "string", "format": "email", "title": "Customer email", "description": "Email address of the customer who placed the order.", "examples": ["customer@example.com"] }, "invoiceUrl": { "type": "string", "format": "uri", "title": "Invoice URL", "description": "URL to access the invoice for the order.", "examples": ["https://example.com/invoice/12345"] }, "products": { "type": "array", "title": "Order items", "examples": [ [ { "productId": "e6c1b944-9a64-4a3f-a8d7-0c26eb8d0f75", "quantity": 3, "price": "49.99", "isShippable": true } ] ], "items": { "type": "object", "required": ["productId", "quantity"], "properties": { "productId": { "type": "string", "format": "uuid", "title": "Product ID", "description": "Unique identifier for the product." }, "quantity": { "type": "number", "title": "Quantity", "description": "Number of items of the product in the order." }, "price": { "type": "string", "format": "number", "title": "Item price", "description": "Price of the item in the order." }, "isShippable": { "type": "boolean", "title": "Is shippable", "description": "Indicates if the item is eligible for shipping." } } } } } } ``` The payload schema above tells Wix to expect, at a minimum, the following 5 fields: * A string `id` with format `uuid`. * A string `contactId` with format `uuid`. * A string `totalAmount` with format `DECIMAL_VALUE`. * A string `orderDate` with format `date-time`. * An array `products` containing object values. All the above properties are listed in the `required` array, so Wix expects all of them every time the event is reported. The automation won’t run if any of these properties are missing from the payload. Other non-required properties like `isShippable` and `invoiceUrl` may also appear in the payload, but the automation still runs if they don’t. You can use this example to get started as you [create your trigger](https://dev.wix.com/docs/rest/business-management/automations/triggers/add-a-trigger-to-your-app.md#add-a-trigger-to-your-app) in the app dashboard.