# About the Triggered Events API

The Triggered Events API allows you to turn events in your service into [triggers](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/automations/triggers/about-triggers). Using this API, your app can report events to Wix. A reported event becomes a trigger that site owners can use when they create their site [automations](fallback::https://dev.wix.com/docs/rest/business-management/automations/introduction).

With the Triggered Events API, you can:

- [Report events](fallback::https://dev.wix.com/docs/sdk/backend-modules/automations/triggered-events/report-event) to trigger site automations.
- [Bulk report](portalId::b85dea5b-341b-493b-b99e-4d4ca12baaa2resourceId::1dfeda34-7917-4ae5-834d-5fe1c34b7081slug::bulk-report-event*fallback::https://dev.wix.com/docs/sdk/backend-modules/automations/triggered-events/bulk-report-event) multiple events simultaneously to activate corresponding automations.
- [Cancel](portalId::b85dea5b-341b-493b-b99e-4d4ca12baaa2resourceId::1dfeda34-7917-4ae5-834d-5fe1c34b7081slug::cancel-event*fallback::https://dev.wix.com/docs/sdk/backend-modules/automations/triggered-events/cancel-event) and [bulk cancel](portalId::b85dea5b-341b-493b-b99e-4d4ca12baaa2resourceId::1dfeda34-7917-4ae5-834d-5fe1c34b7081slug::bulk-cancel-event*fallback::https://dev.wix.com/docs/sdk/backend-modules/automations/triggered-events/bulk-cancel-event) events to stop any remaining actions associated with a trigger and external entities.

## Before you begin

It's important to note the following points before starting to code:

- You must [add a trigger](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/automations/triggers/add-an-automations-trigger-extension) to your app and define its payload schema in the app dashboard before you report an event.
- Only the app that the trigger belongs to can report the event.
- Make sure you know your trigger key. You can find this by selecting your trigger in the [app dashboard](fallback::https://dev.wix.com/app-selector?title=Select+an+App&primaryButtonText=Select+Site&actionUrl=https%3A%2F%2Fdev.wix.com%2Fapps%2F%7BappId%7D%2Fautomations-dev-center).

## Use cases

- Report an invoice overdue event, then cancel it when the customer pays the invoice.
- If a customer has booked multiple sessions then canceled all of them, you can use `bulkCancel()` to cancel all reminders for those sessions.

## Terminology

- **Trigger Key**: A unique string that identifies the trigger.
- **External Entity ID**: A GUID that identifies the related resource for an event, such as a contact or session ID. This allows you to identify the specific case for which the event was reported. See [Reporting and Canceling Events](portalId::b85dea5b-341b-493b-b99e-4d4ca12baaa2resourceId::1dfeda34-7917-4ae5-834d-5fe1c34b7081slug::reporting-and-canceling-events*fallback::https://dev.wix.com/docs/sdk/backend-modules/automations/triggered-events/reporting-and-canceling-events) for more information.
- **Idempotency**: A mechanism to ensure that multiple identical requests don't cause unnecessary automation activation. You pass in a unique idempotency key for the event when you report it. If an event with the same idempotency key is reported multiple times, Wix ignores it for the duration of time that you define.

@package_metadata:@wix/automations

To use the Activations API, install the `@wix/automations` package.

#### Install the package

Follow the installation instructions for your development environment.

| Development environment | Installation method |
|--|--|
| Wix sites (editor or IDE) | Use the [package manager](fallback::https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/packages/work-with-npm-packages-in-the-editor). |
| Wix sites (local IDE) | Run `wix install @wix/automations` using the [Wix CLI](fallback::https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/packages/work-with-npm-packages-with-the-wix-cli).|
| Blocks apps | Use the same installation method as Wix sites. |
| CLI and self-hosted apps | Run `npm install @wix/automations` or `yarn add @wix/automations`. |
| Headless sites and apps | Run `npm install @wix/automations` or `yarn add @wix/automations`. |

#### Import the package

To import the package in your code:

```js
import { activations } from '@wix/automations'
```

# Reporting and Canceling Events

Before diving in, it's important to understand the difference between a trigger and an event and what all this means for your users.

A trigger is the configuration you create for your app in your app's dashboard. On the other hand, an event is what takes place in your service, which you then report to Wix.

The distinction between triggers and events is hidden from your users. From their perspective,they interact with triggers only. Users who install your app are able to use your triggers when they create new automations for their site. When your app reports an event, all site automations that use the specified trigger are activated.

## Event types

Wix Automations supports 2 types of events for triggers: real-time events and scheduled events.

Each trigger can support either real-time events or scheduled events, but not both. However, you can call [reportEvent()](portalId::b85dea5b-341b-493b-b99e-4d4ca12baaa2resourceId::1dfeda34-7917-4ae5-834d-5fe1c34b7081slug::report-event*fallback::https://dev.wix.com/docs/sdk/backend-modules/automations/triggered-events/report-event) multiple times in response to a single business event in your system.

This table lays out the differences between real-time events and scheduled events:

| Real-time event | Scheduled event |
| -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Takes place the moment it's reported. | Takes place at a date and time specified in the payload. |
| Supported by default in new triggers. | Supported only when your trigger meets both of these criteria: <ul> <li>A `date-time` property is specified in the trigger's [payload schema](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/automations/triggers/payload-schema).</li><li>You select the **Allow scheduled events with predefined date & time** option in your trigger configuration. </li> </ul> |
| Supports automation actions: <ul> <li>Immediately when the event is reported.</li><li>After the event is reported. </li> </ul> | Supports automation actions: <ul> <li>At the event time in the payload.</li><li>Before the event time in the payload.</li><li>After the event time in the payload. </li> </ul> |

## Canceling events

Your users may configure actions to be carried out some time after you report an event. If you create a trigger for something that could be canceled or deleted, we strongly recommend canceling events when they're no longer relevant. If your app doesn't cancel events, your users' automations may carry out undesired actions, like sending overdue notices for invoices after they've been paid.

Events are not cancelable by default. To make an event cancelable, you must first pass an `externalEntityId` and the applicable `triggerKey`to [reportEvent()](portalId::b85dea5b-341b-493b-b99e-4d4ca12baaa2resourceId::1dfeda34-7917-4ae5-834d-5fe1c34b7081slug::report-event*fallback::https://dev.wix.com/docs/sdk/backend-modules/automations/triggered-events/report-event). When you call [cancelEvent()](portalId::b85dea5b-341b-493b-b99e-4d4ca12baaa2resourceId::1dfeda34-7917-4ae5-834d-5fe1c34b7081slug::cancel-event*fallback::https://dev.wix.com/docs/sdk/backend-modules/automations/triggered-events/cancel-event) with the same `externalEntityId` and `triggerKey`, the event is canceled, as are all other events that share the same `externalEntityId` and `triggerKey`.

### Choose the right `externalEntityId`

It's important to know that the Cancel Event endpoint cancels *all* events with the specified combination of `triggerKey` and `externalEntityId`. You must think through your implementation carefully to make sure you don't pass an `externalEntityId` that could cancel events you don't mean to cancel.

Consider what kind of relationship between entities you're trying to support. These general guidelines might help you decide what ID to use for `externalEntityId`:

* If you're supporting a one-to-many relationship, use the ID from the *many* side of the relationship.

 For example, in a contact-to-invoices relationship: An invoice relates to a single contact, but a contact can relate to multiple invoices. The invoice ID is the appropriate `externalEntityId`.

* If you're supporting a many-to-many relationship, create a unique event ID for each reported event.

 For example, in a students-to-classes relationship: Each student relates to multiple classes, and each class relates to multiple students. A new event ID is the appropriate `externalEntityId`.

<blockquote class="important">

**Important:** The scenarios here are for illustration only. Always evaluate your implementation against your users' real-world requirements.

</blockquote>

### Scenario 1: One-to-many relationship

**The scenario**: Customers can schedule appointments with site collaborators.

**Suggested value for `externalEntityId`**: Appointment ID

**Suggested triggers and how your users might use them**:

| Trigger key and description | How your users might use the trigger |
| ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appointment_scheduled` Real-time event. Triggered when someone schedules an appointment. | <ul><li>Immediately send a confirmation email to the customer.</li> <li>Immediately send a notification to site collaborators.</li> </ul> |
| `appointment_starting` Scheduled event. Triggered in relation to the appointment's start time. | <ul> <li>Send a reminder email *x* days before the appointment.</li> <li>Notify the applicable site collaborator *x* minutes before the appointment.</li> </ul> |
| `appointment_canceled` Real-time event. Triggered when someone cancels an appointment. | <ul> <li>Immediately send a cancellation email to the customer.</li> <li>Immediately notify site collaborators of the cancellation.</li> </ul> |

**Example logic for your app**:

| Business event | Your app's API calls |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Customer schedules an appointment | <ol> <li>Report `appointment_scheduled` event.</li> <li>Report `appointment_starting` event.</li> </ol> |
| Customer cancels an appointment | <ol> <li>Report `appointment_canceled` event.</li> <li>Cancel `appointment_scheduled` event.</li> <li>Cancel `appointment_starting` event.</li> </ol> |

### Scenario 2: Many-to-many relationship

**The scenario**: Participants can enroll in multiple courses. Each course can contain multiple participants.

**Suggested value for `externalEntityId`**: A generated enrollment ID, unique to each student-class combination.

**Suggested triggers and how your users might use them**:

| Trigger key and description | How your users might use the trigger |
| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `participant_enrolled_in_class` Real-time event. Triggered when someone signs up for a class. | <ul> <li>Immediately send a confirmation email to the participant.</li> <li>Immediately send a notification to the site owner.</li> </ul> |
| `class_starting` Scheduled event. Triggered in relation to the class's start time. | <ul> <li>Send a reminder email *x* days before the class.</li> <li>Notify the site owner *x* minutes before the class.</li> </ul> |
| `participant_left_class` Real-time event. Triggered when someone is unenrolled from a class. | <ul> <li>Immediately send a confirmation email to the participant.</li> <li>Immediately notify the site owner that someone left their class.</li> </ul> |
| `class_canceled` Real-time event. Triggered when a class is canceled. | <ul> <li>Immediately send a confirmation email to each participant.</li> <li>Immediately notify the site owner that a class is canceled.</li> </ul> |

**Example logic for your app**:

| Business event | Your app's API calls |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Participant enrolls in a class | <ol> <li>Report `participant_enrolled_in_class` event.</li> <li>Report `class_starting` event.</li> </ol> |
| Participant leaves a class | <ol> <li>Report `participant_left_class` event.</li> <li>Cancel `participant_enrolled_in_class` event.</li> <li>Cancel `class_starting` event.</li> </ol> |
| Class is canceled | <ol> <li>Report `class_canceled` event.</li> <li>Cancel `participant_enrolled_in_class` event.</li> <li>Cancel `class_starting` event.</li> </ol> |

Coding Examples

Sled Tests

Go Headless

Build Apps

Client

API Preview

Ricos

Develop Websites

API Reference

Velo

Picasso

GraphQL (Alpha)

Activations

Activations 1 0 0

Trigger key whose events you want to cancel.
For example, `form_submitted` or `invoice_due`.

triggerKey

string

Repeated list of external_entity_id, representing the related resources' IDs.

externalEntityIds

Bulk cancels any remaining actions for a trigger and external entities.

import { activations } from '@wix/automations';

async function bulkCancelEvent(triggerKey, externalEntityIds) {
  const response = await activations.bulkCancelEvent(triggerKey, externalEntityIds);
};

bulkCancelEvent

import { activations } from '@wix/automations';
import { auth } from '@wix/essentials';

async function myBulkCancelEventMethod(triggerKey, externalEntityIds) {
  const elevatedBulkCancelEvent = auth.elevate(activations.bulkCancelEvent);
  const response = await elevatedBulkCancelEvent(triggerKey, externalEntityIds);
}

bulkCancelEvent (with elevated permissions)

import { createClient } from '@wix/sdk';
import { activations } from '@wix/automations';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { activations },
  // Include the auth strategy and host as relevant
});


async function bulkCancelEvent(triggerKey, externalEntityIds) {
  const response = await myWixClient.activations.bulkCancelEvent(triggerKey, externalEntityIds);
};

Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client).

bulkCancelEvent (self-hosted)

BulkCancelEventResponse

Trigger key as defined in your app's trigger configuration
in the app dashboard.
For example, `form_submitted` or `invoice_due`.

Repeated list of event details for bulk reporting.

eventsInfo

Bulk reports events and activates site automations with the specified trigger key.

import { activations } from '@wix/automations';

async function bulkReportEvent(triggerKey, eventsInfo) {
  const response = await activations.bulkReportEvent(triggerKey, eventsInfo);
};

bulkReportEvent

import { activations } from '@wix/automations';
import { auth } from '@wix/essentials';

async function myBulkReportEventMethod(triggerKey, eventsInfo) {
  const elevatedBulkReportEvent = auth.elevate(activations.bulkReportEvent);
  const response = await elevatedBulkReportEvent(triggerKey, eventsInfo);
}

bulkReportEvent (with elevated permissions)

import { createClient } from '@wix/sdk';
import { activations } from '@wix/automations';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { activations },
  // Include the auth strategy and host as relevant
});


async function bulkReportEvent(triggerKey, eventsInfo) {
  const response = await myWixClient.activations.bulkReportEvent(triggerKey, eventsInfo);
};

bulkReportEvent (self-hosted)

BulkReportEventResponse

Trigger key whose event you want to cancel.
For example, `form_submitted` or `invoice_due`.

ID of the related resource in GUID format.
For example, `fc81a355-3429-50fc-a4c7-def486e828f3`.

Typically, this ID is defined in your system,
but you can also use any Wix resource GUID,
such as contact ID, member ID, or invoice ID.
See
[Choose the right `externalEntityId`](https://dev.wix.com/docs/rest/business-management/automations/triggered-events/reporting-and-canceling-events#choose-the-right-externalentityid)
for more information.

externalEntityId

Cancels any remaining actions for a trigger and external entity.


Events are not cancelable by default.
To make an event cancelable,
you must first pass an `externalEntityId`
and the applicable `triggerKey` to [reportEvent()](#report-event).
When you call cancelEvent() with the same `externalEntityId` and `triggerKey`,
the event is canceled,
as are all other events that share the `externalEntityId` and `triggerKey`.

import { activations } from '@wix/automations';

async function cancelEvent(triggerKey, externalEntityId) {
  const response = await activations.cancelEvent(triggerKey, externalEntityId);
};

cancelEvent

import { activations } from '@wix/automations';
import { auth } from '@wix/essentials';

async function myCancelEventMethod(triggerKey, externalEntityId) {
  const elevatedCancelEvent = auth.elevate(activations.cancelEvent);
  const response = await elevatedCancelEvent(triggerKey, externalEntityId);
}

cancelEvent (with elevated permissions)

import { createClient } from '@wix/sdk';
import { activations } from '@wix/automations';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { activations },
  // Include the auth strategy and host as relevant
});


async function cancelEvent(triggerKey, externalEntityId) {
  const response = await myWixClient.activations.cancelEvent(triggerKey, externalEntityId);
};

cancelEvent (self-hosted)

void

options

ReportEventOptions

Reports an event and activates site automations with the specified trigger key.


Only the app that created a trigger can report events for it.
This means other apps can't report events for your triggers,
and you can't report events for another app's triggers.

If your app supports canceling events,
`externalEntityId` must be provided.
`externalEntityId` is required when calling [cancelEvent()](#cancel-event).

import { activations } from '@wix/automations';

async function reportEvent(triggerKey, options) {
  const response = await activations.reportEvent(triggerKey, options);
};

reportEvent

import { activations } from '@wix/automations';
import { auth } from '@wix/essentials';

async function myReportEventMethod(triggerKey, options) {
  const elevatedReportEvent = auth.elevate(activations.reportEvent);
  const response = await elevatedReportEvent(triggerKey, options);
}

reportEvent (with elevated permissions)

import { createClient } from '@wix/sdk';
import { activations } from '@wix/automations';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { activations },
  // Include the auth strategy and host as relevant
});


async function reportEvent(triggerKey, options) {
  const response = await myWixClient.activations.reportEvent(triggerKey, options);
};

reportEvent (self-hosted)

ReportEventResponse

---
title: Introduction
---

# About the Triggered Events API

The Triggered Events API allows you to turn events in your service into [triggers](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/automations/triggers/about-triggers). Using this API, your app can report events to Wix. A reported event becomes a trigger that site owners can use when they create their site [automations](https://dev.wix.com/docs/rest/business-management/automations/introduction).

With the Triggered Events API, you can:

- [Report events](https://dev.wix.com/docs/sdk/backend-modules/automations/triggered-events/report-event) to trigger site automations.
- [Bulk report](https://dev.wix.com/docs/sdk/backend-modules/automations/triggered-events/bulk-report-event) multiple events simultaneously to activate corresponding automations.
- [Cancel](https://dev.wix.com/docs/sdk/backend-modules/automations/triggered-events/cancel-event) and [bulk cancel](https://dev.wix.com/docs/sdk/backend-modules/automations/triggered-events/bulk-cancel-event) events to stop any remaining actions associated with a trigger and external entities.

## Before you begin

It's important to note the following points before starting to code:

- You must [add a trigger](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/automations/triggers/add-an-automations-trigger-extension) to your app and define its payload schema in the app dashboard before you report an event.
- Only the app that the trigger belongs to can report the event.
- Make sure you know your trigger key. You can find this by selecting your trigger in the [app dashboard](https://dev.wix.com/app-selector?title=Select+an+App&primaryButtonText=Select+Site&actionUrl=https%3A%2F%2Fdev.wix.com%2Fapps%2F%7BappId%7D%2Fautomations-dev-center).

## Use cases

- Report an invoice overdue event, then cancel it when the customer pays the invoice.
- If a customer has booked multiple sessions then canceled all of them, you can use `bulkCancel()` to cancel all reminders for those sessions.

## Terminology

- **Trigger Key**: A unique string that identifies the trigger.
- **External Entity ID**: A GUID that identifies the related resource for an event, such as a contact or session ID. This allows you to identify the specific case for which the event was reported. See [Reporting and Canceling Events](https://dev.wix.com/docs/sdk/backend-modules/automations/triggered-events/reporting-and-canceling-events) for more information.
- **Idempotency**: A mechanism to ensure that multiple identical requests don't cause unnecessary automation activation. You pass in a unique idempotency key for the event when you report it. If an event with the same idempotency key is reported multiple times, Wix ignores it for the duration of time that you define.


@package_metadata:@wix/automations

To use the Activations API, install the `@wix/automations` package.

#### Install the package

Follow the installation instructions for your development environment.

| Development environment | Installation method |
|--|--|
| Wix sites (editor or IDE) | Use the [package manager](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/packages/work-with-npm-packages-in-the-editor). |
| Wix sites (local IDE) | Run `wix install @wix/automations` using the [Wix CLI](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/packages/work-with-npm-packages-with-the-wix-cli).|
| Blocks apps | Use the same installation method as Wix sites. |
| CLI and self-hosted apps | Run `npm install @wix/automations` or `yarn add @wix/automations`. |
| Headless sites and apps | Run `npm install @wix/automations` or `yarn add @wix/automations`. |

#### Import the package

To import the package in your code:

```js
import { activations } from '@wix/automations'
```
  

---
title: Reporting and Canceling Events
---

# Reporting and Canceling Events

Before diving in, it's important to understand the difference between a trigger and an event and what all this means for your users.

A trigger is the configuration you create for your app in your app's dashboard. On the other hand, an event is what takes place in your service, which you then report to Wix.

The distinction between triggers and events is hidden from your users. From their perspective,they interact with triggers only. Users who install your app are able to use your triggers when they create new automations for their site. When your app reports an event, all site automations that use the specified trigger are activated.

## Event types

Wix Automations supports 2 types of events for triggers: real-time events and scheduled events.

Each trigger can support either real-time events or scheduled events, but not both. However, you can call [reportEvent()](https://dev.wix.com/docs/sdk/backend-modules/automations/triggered-events/report-event) multiple times in response to a single business event in your system.

This table lays out the differences between real-time events and scheduled events:

| Real-time event | Scheduled event |
| -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Takes place the moment it's reported. | Takes place at a date and time specified in the payload. |
| Supported by default in new triggers. | Supported only when your trigger meets both of these criteria: <ul> <li>A `date-time` property is specified in the trigger's [payload schema](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/automations/triggers/payload-schema).</li><li>You select the **Allow scheduled events with predefined date & time** option in your trigger configuration. </li> </ul> |
| Supports automation actions: <ul> <li>Immediately when the event is reported.</li><li>After the event is reported. </li> </ul> | Supports automation actions: <ul> <li>At the event time in the payload.</li><li>Before the event time in the payload.</li><li>After the event time in the payload. </li> </ul> |

## Canceling events

Your users may configure actions to be carried out some time after you report an event. If you create a trigger for something that could be canceled or deleted, we strongly recommend canceling events when they're no longer relevant. If your app doesn't cancel events, your users' automations may carry out undesired actions, like sending overdue notices for invoices after they've been paid.

Events are not cancelable by default. To make an event cancelable, you must first pass an `externalEntityId` and the applicable `triggerKey`to [reportEvent()](https://dev.wix.com/docs/sdk/backend-modules/automations/triggered-events/report-event). When you call [cancelEvent()](https://dev.wix.com/docs/sdk/backend-modules/automations/triggered-events/cancel-event) with the same `externalEntityId` and `triggerKey`, the event is canceled, as are all other events that share the same `externalEntityId` and `triggerKey`.

### Choose the right `externalEntityId`

It's important to know that the Cancel Event endpoint cancels *all* events with the specified combination of `triggerKey` and `externalEntityId`. You must think through your implementation carefully to make sure you don't pass an `externalEntityId` that could cancel events you don't mean to cancel.

Consider what kind of relationship between entities you're trying to support. These general guidelines might help you decide what ID to use for `externalEntityId`:

* If you're supporting a one-to-many relationship, use the ID from the *many* side of the relationship.

 For example, in a contact-to-invoices relationship: An invoice relates to a single contact, but a contact can relate to multiple invoices. The invoice ID is the appropriate `externalEntityId`.

* If you're supporting a many-to-many relationship, create a unique event ID for each reported event.

 For example, in a students-to-classes relationship: Each student relates to multiple classes, and each class relates to multiple students. A new event ID is the appropriate `externalEntityId`.

<blockquote class="important">

**Important:** The scenarios here are for illustration only. Always evaluate your implementation against your users' real-world requirements.

</blockquote>

### Scenario 1: One-to-many relationship

**The scenario**: Customers can schedule appointments with site collaborators.

**Suggested value for `externalEntityId`**: Appointment ID

**Suggested triggers and how your users might use them**:

| Trigger key and description | How your users might use the trigger |
| ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appointment_scheduled` Real-time event. Triggered when someone schedules an appointment. | <ul><li>Immediately send a confirmation email to the customer.</li> <li>Immediately send a notification to site collaborators.</li> </ul> |
| `appointment_starting` Scheduled event. Triggered in relation to the appointment's start time. | <ul> <li>Send a reminder email *x* days before the appointment.</li> <li>Notify the applicable site collaborator *x* minutes before the appointment.</li> </ul> |
| `appointment_canceled` Real-time event. Triggered when someone cancels an appointment. | <ul> <li>Immediately send a cancellation email to the customer.</li> <li>Immediately notify site collaborators of the cancellation.</li> </ul> |

**Example logic for your app**:

| Business event | Your app's API calls |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Customer schedules an appointment | <ol> <li>Report `appointment_scheduled` event.</li> <li>Report `appointment_starting` event.</li> </ol> |
| Customer cancels an appointment | <ol> <li>Report `appointment_canceled` event.</li> <li>Cancel `appointment_scheduled` event.</li> <li>Cancel `appointment_starting` event.</li> </ol> |

### Scenario 2: Many-to-many relationship

**The scenario**: Participants can enroll in multiple courses. Each course can contain multiple participants.

**Suggested value for `externalEntityId`**: A generated enrollment ID, unique to each student-class combination.

**Suggested triggers and how your users might use them**:

| Trigger key and description | How your users might use the trigger |
| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `participant_enrolled_in_class` Real-time event. Triggered when someone signs up for a class. | <ul> <li>Immediately send a confirmation email to the participant.</li> <li>Immediately send a notification to the site owner.</li> </ul> |
| `class_starting` Scheduled event. Triggered in relation to the class's start time. | <ul> <li>Send a reminder email *x* days before the class.</li> <li>Notify the site owner *x* minutes before the class.</li> </ul> |
| `participant_left_class` Real-time event. Triggered when someone is unenrolled from a class. | <ul> <li>Immediately send a confirmation email to the participant.</li> <li>Immediately notify the site owner that someone left their class.</li> </ul> |
| `class_canceled` Real-time event. Triggered when a class is canceled. | <ul> <li>Immediately send a confirmation email to each participant.</li> <li>Immediately notify the site owner that a class is canceled.</li> </ul> |

**Example logic for your app**:

| Business event | Your app's API calls |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Participant enrolls in a class | <ol> <li>Report `participant_enrolled_in_class` event.</li> <li>Report `class_starting` event.</li> </ol> |
| Participant leaves a class | <ol> <li>Report `participant_left_class` event.</li> <li>Cancel `participant_enrolled_in_class` event.</li> <li>Cancel `class_starting` event.</li> </ol> |
| Class is canceled | <ol> <li>Report `class_canceled` event.</li> <li>Cancel `participant_enrolled_in_class` event.</li> <li>Cancel `class_starting` event.</li> </ol> |

automations_activations

ApplicationError

code

data

description

BulkActionMetadata

Number of items that couldn't be processed.

totalFailures

number

Number of items that were successfully processed.

totalSuccesses

Number of failures without details because detailed failure threshold was exceeded.

undetailedFailures

Metadata for the overall bulk action, including success and failure counts.

bulkActionMetadata

List of results for each item in the bulk cancel event request.

results

Trigger key related to the canceled event.

BulkCancelEventResult

ID of the related resource in GUID format.

Metadata of the item, including its ID and success or failure status.

itemMetadata

ItemMetadata

List of results for each item in the bulk report event request.

BulkReportEventResult

The activation IDs of triggered ReportEvents.

activationIds

Event details for the item in the request.

eventInfo

EventInfo

Metadata for the individual item in the request.

idempotency

Idempotency

Event payload, formatted as key:value pairs.
Must comply with the payload schema
if you provided one when configuring your trigger.

payload

A unique identifier for the event.
If you send the same idempotency key in multiple report event requests, for the same trigger key and app id,
consecutive requests will be ignored after the first one. Note that the idempotency key is kept for a week before it expires.

Optional. The time to live (TTL) in milliseconds before the key will expire. Default is a week.

ttlInMilliseconds

Item ID. Should always be available, unless it's impossible (for example, when failing to create an item).

Details about the error in case of failure.

error

Index of the item within the request array. Allows for correlation between request and response items.

originalIndex

Whether the requested action was successful for this item. When `false`, the `error` field is populated.

success

boolean

ID of the related resource in GUID format.
For example, `fc81a355-3429-50fc-a4c7-def486e828f3`.

Required if your app needs to
[cancel the event](https://dev.wix.com/docs/sdk/backend-modules/automations/triggered-events/cancel-event)
if the automation becomes no longer relevant.

Typically, this ID is defined in your system,
but you can also use any Wix resource GUID,
such as contact ID, member ID, or invoice ID.
See
[Choose the right `externalEntityId`](https://dev.wix.com/docs/rest/business-management/automations/triggered-events/reporting-and-canceling-events#about-canceling-events)
for more information.

Event payload, formatted as key:value pairs.
Must comply with the payload schema
if you provided one when configuring your trigger.

Key names can include only alphanumeric characters or underscores
(`A-Z`, `a-z`, `0-9`, `_`).
They cannot start with an underscore.

Values can be strings, numbers, integers, booleans, or arrays.
If a value is an array, the array items must be objects,
and nested object properties must be
strings, numbers, integers, or booleans only.

bulkCancelEvent( )