---
title: "Events"
description: "A non-technical overview of Events in RevCent, focused on how account activity is recorded as item-specific event notations and used to trigger Functions, Email Templates, AI Assistants, and AI Voice Agents."
type: "feature"
company: "RevCent"
relationships:
  - name: "Function"
    url: "https://revcent.com/documentation/markdown/ecosystem/feature/Function.md"
  - name: "Email Template"
    url: "https://revcent.com/documentation/markdown/ecosystem/feature/EmailTemplate.md"
  - name: "AI Assistant"
    url: "https://revcent.com/documentation/markdown/ecosystem/feature/AIAssistant.md"
  - name: "AI Voice Agent"
    url: "https://revcent.com/documentation/markdown/ecosystem/feature/AIVoiceAgent.md"
technical_links:
  web_app: "https://kb.revcent.com/en/revcent-account/events"
---

# Events

Events are things that happened inside a RevCent account.

An Event is usually tied to a specific item, such as a Sale, Customer, Shipping record, Subscription, Transaction, Chargeback, Trial, or Fraud Detection. When that item is created, updated, deleted, alerted, renewed, shipped, delivered, failed, paid, or otherwise changed in a meaningful way, RevCent can record an Event for that activity.

Events are important because they let RevCent features react to what happened. A Function can run when a sale is created, an Email Template can send communication when an item reaches a certain state, an AI Assistant can review or act on an event, and an AI Voice Agent can use events to decide when an automated call should happen.

In simple terms:

```text
Something happens in RevCent
    ↓
RevCent records an Event
    ↓
The Event has one or more notations
    ↓
A RevCent feature can use the notation as a trigger
    ↓
The feature receives details about the item involved
```

## Why Events Are a Feature

Events are a feature because they provide the trigger layer for automation and customer operations in RevCent.

A user does not usually create an Event directly. Instead, RevCent creates Events as account activity happens. The user then configures other features to listen for specific Events and take action.

Examples:

- A Sale is created.
- A Sale is created and paid.
- A Sale is created but declined.
- A Customer is created.
- A Customer is added to a Customer Group.
- A Shipping record is created.
- A Shipping record is updated as shipped.
- A Shipping record is updated as delivered.
- A Subscription is renewed successfully.
- A Subscription renewal fails.
- A Chargeback is created.
- A Trial expires successfully.
- A Trial expires unsuccessfully.
- Sentinel creates a fraud alert.
- An AI Memo is created by an AI Assistant.

Each of these can become a meaningful trigger for another feature.

## Technical Links

| Area | Link |
|---|---|
| Web App / Knowledge Base | `https://kb.revcent.com/en/revcent-account/events` |

## Core Purpose

The purpose of Events is to turn account activity into structured trigger points.

Without Events, a user would need to constantly check whether something happened. With Events, RevCent can automatically recognize important moments and let other features respond.

Common reasons to use Events include:

- notifying a customer when something happens,
- running custom Function logic when an item changes,
- starting an AI Assistant workflow when a specific item is created or updated,
- deciding whether an AI Voice Agent should call a customer,
- sending an Email Template from an item lifecycle moment,
- reacting to payment success or failure,
- reacting to subscription renewal outcomes,
- reacting to shipping lifecycle changes,
- reacting to fraud, chargeback, refund, or support activity.

## Event Structure

An Event is made up of several important parts.

| Part | Meaning |
|---|---|
| `event_date` | When the Event happened. |
| `event_id` | Unique ID for the Event. |
| `event_notations` | All notations that describe the Event. |
| `event_trigger` | The specific notation that triggered the listening feature, when applicable. |
| `item_type` | The type of RevCent item involved in the Event. |
| `item_event` | The basic action that happened to the item. |
| `item_id` | The ID of the specific item involved. |
| `item_details` | The details of the item involved in the Event. |
| `item_extra` | Additional event-specific or item-specific context, when available. |

The most important fields for automation are usually:

```text
item_type
item_event
event_notations
event_trigger
item_id
item_details
```

These tell the receiving feature what happened, what item it happened to, which notation matched, and what item data is available for the workflow.

## Item Type

The item type identifies which kind of RevCent object the Event belongs to.

Examples include:

- `sale`
- `customer`
- `shipping`
- `subscription`
- `subscription_renewal`
- `trial`
- `transaction`
- `chargeback`
- `fraud_detection`
- `sentinel`
- `pending_refund`
- `product`
- `product_sale`
- `invoice`
- `note`
- `ai_memo`

The item type matters because it tells the receiving feature how to interpret `item_details`.

For example:

```text
sale.created
```

has `item_type = sale`, while:

```text
shipping.updated.shipped
```

has `item_type = shipping`.

## Item Event

The item event describes the basic thing that happened to the item.

Common item event values include:

- `created`
- `updated`
- `deleted`
- `alert`

Some Events then include additional details after the item event.

For example:

```text
sale.created.success.paid
```

means the item type is `sale`, the item event is `created`, the result was successful, and the sale was paid.

## Event Notations

An Event notation is the structured name used to describe what happened.

Event notations are dot-separated and become more specific as they get longer.

Pattern:

```text
item_type.item_event.detail.detail.detail
```

Examples:

```text
customer.created
sale.created
sale.created.success
sale.created.success.paid
sale.created.success.paid.is_upsell
shipping.updated.shipped
shipping.updated.delivered
subscription.updated.renewed.success
trial.updated.expired.failed
pending_refund.created.shipping.full.has_fulfillment
```

A single Event can have multiple notations. This allows a user to trigger broadly or specifically.

## Broad vs Specific Notations

Choosing the right notation is important.

A broad notation catches more activity. A specific notation catches a narrower case.

Example sale event:

```text
sale.created
sale.created.success
sale.created.success.paid
sale.created.success.paid.is_upsell
```

These notations represent increasing specificity.

| Notation | Meaning |
|---|---|
| `sale.created` | A sale was created, regardless of outcome. |
| `sale.created.success` | A sale was created successfully, either pending or paid. |
| `sale.created.success.paid` | A sale was created successfully and was paid. |
| `sale.created.success.paid.is_upsell` | A sale was created successfully, was paid, and was an upsell. |

Use the broadest notation that matches the business need, but not so broad that the workflow runs for unrelated activity.

## Event Details

When a feature is triggered by an Event, the feature receives details about the Event and the item involved.

For example, if a Function is triggered by:

```text
sale.created
```

then the Function receives a Sale event object. That object includes the Event information and the Sale details in `item_details`.

Conceptually:

```json
{
  "event_date": "2026-01-01T12:00:00.000Z",
  "event_id": "XXXXXXXXXXXXXXXXXXXX",
  "event_notations": [
    "sale.created",
    "sale.created.success",
    "sale.created.success.paid"
  ],
  "event_trigger": "sale.created.success.paid",
  "item_type": "sale",
  "item_id": "XXXXXXXXXXXXXXXXXXXX",
  "item_event": "created",
  "item_details": {
    "id": "XXXXXXXXXXXXXXXXXXXX"
  }
}
```

The receiving feature should use `item_type` to know what kind of item is present and `item_details` to work with that item's data.

## Events and Functions

Functions can use Events as account-event triggers.

This is one of the most direct ways to automate custom business logic in RevCent. A user can configure a Function to listen for one or more event notations, and RevCent will run the Function when a matching Event happens.

Examples:

| Event Notation | Function Use Case |
|---|---|
| `sale.created.success.paid` | Send paid-sale data to an external system. |
| `sale.created.failed.declined` | Send declined sale data to a recovery workflow. |
| `shipping.updated.shipped` | Notify an external tracking system. |
| `subscription.updated.renewed.failed` | Add customer to a retention workflow. |
| `chargeback.created` | Alert support or finance team. |
| `fraud_detection.created` | Send item to manual review. |
| `customer.created` | Sync customer to a CRM. |

When triggered by an Event, a Function can read:

```text
event.data.event_trigger
event.data.item_type
event.data.item_id
event.data.item_details
```

This allows the Function to act on the exact item that caused the Event.

## Events and Email Templates

Email Templates can be associated with item lifecycle moments so customers or internal teams receive communication when something happens.

Events provide the underlying idea of “what happened” in the account. Email Templates use this event-driven model to send the right message at the right time.

Examples:

- A sale is created successfully.
- A shipment is created.
- A shipment is marked shipped.
- A shipment is marked delivered.
- A subscription renewal succeeds.
- A subscription renewal fails.
- A refund or chargeback-related event occurs.

The Email Template should match the item context. For example, a shipping-related template should expect shipping details, while a sale-related template should expect sale details.

## Events and AI Assistants

AI Assistants can use Events to decide when an autonomous workflow should start.

For example, an AI Assistant might be configured to run when:

- a sale is created successfully,
- a sale fails due to a decline,
- a chargeback is created,
- a fraud detection is created,
- a shipment is delayed or updated,
- a subscription renewal fails,
- an AI Memo should be created for human review.

Events give the AI Assistant a concrete item and context to work from.

A useful pattern is:

```text
Event happens
    ↓
AI Assistant receives item context
    ↓
Optional filter Function decides pass/fail
    ↓
AI Assistant performs the configured workflow
    ↓
AI Thread records the execution
```

If a filter Function is used, it should return exactly:

```javascript
callback(null, "pass");
```

or:

```javascript
callback(null, "fail");
```

## Events and AI Voice Agents

AI Voice Agents can use Events to decide when voice workflows should run.

Examples:

- A payment fails and a customer should be called for recovery.
- A subscription renewal fails and a retention call should be attempted.
- A shipment-related issue needs customer follow-up.
- A customer action creates a support or sales opportunity.

Like AI Assistants, an AI Voice Agent can use a filter Function to determine whether it should proceed for a specific Event item. This helps prevent calls when the customer, campaign, item status, or business rule makes the call inappropriate.

For AI Voice Agents, Events are useful because they connect a real account action to a real customer or item context.

## Event Notation Categories and Selection Guide

RevCent event notations can be read as a hierarchy. The first part identifies the item type, the second part identifies what happened to that item, and later parts make the notation more specific.

For example:

```text
sale.created
sale.created.success
sale.created.success.paid
sale.created.success.paid.is_upsell
```

Each step becomes more precise. A broad notation is useful when the workflow should catch many related outcomes. A specific notation is better when the workflow should only run for one exact business moment.

Use the broadest notation that still matches the business goal, and use the most specific notation when a customer-facing, payment-facing, fulfillment-facing, or risk-facing workflow must not run for unrelated activity.

| Category | Event Notation | Description | Reason to Use This Notation |
|---|---|---|---|
| AI Memo | `ai_memo.created` | An AI Memo was created by an AI Assistant. | Use when a workflow should react to an AI-generated memo or internal AI observation. |
| Chargeback | `chargeback.created` | A chargeback was created. | Use when support, finance, or risk teams need to respond as soon as a chargeback appears. |
| Check | `check_direct.created` | A check was created. | Use when a workflow should respond to a direct-check payment record. |
| Customer | `customer.created` | A customer was created. | Use when onboarding, CRM sync, segmentation, or welcome workflows should start for every new customer. |
| Customer | `customer.updated.add_card` | A credit card was added to a customer. | Use when payment-method updates should trigger follow-up, verification, or recovery workflows. |
| Customer | `customer.updated.address` | A customer's address was updated. | Use when shipping, billing, fraud review, or customer-profile sync should react to address changes. |
| Customer | `customer.updated.customer_group` | A customer's customer group was updated, either added to or removed from a group. | Use when any customer-group membership change matters, regardless of whether it was an add or remove. |
| Customer | `customer.updated.customer_group.added` | A customer was added to one or more customer groups. | Use when a workflow should run only when a customer enters a group or segment. |
| Customer | `customer.updated.customer_group.removed` | A customer was removed from one or more customer groups. | Use when a workflow should run only when a customer leaves a group or segment. |
| Customer | `customer.updated.disabled` | A customer was disabled. | Use when account-blocking, compliance, suppression, or internal review workflows should react to disabled customers. |
| Customer | `customer.updated.enabled` | A customer was re-enabled. | Use when reactivation workflows should run after a customer becomes enabled again. |
| Discount | `discount.created` | A discount was created. | Use when discount activity should be recorded, reviewed, or synced to another system. |
| Fraud Detection | `fraud_detection.created` | A fraud detection was created. | Use when fraud-review, manual-review, alerting, or risk-analysis workflows should start. |
| Fraud Detection | `fraud_detection.updated.false_positive` | A fraud detection was updated and marked as a false positive. | Use when fraud-review records need correction, reporting cleanup, or customer/service follow-up after a false-positive decision. |
| Invoice | `invoice.created` | An invoice was created. | Use when invoice delivery, invoice tracking, or accounting workflows should begin. |
| Note | `note.created` | A note was created. | Use when internal note activity should notify another system or preserve support context. |
| Offline Payment | `offline_payment.created` | An offline payment was created. | Use when alternate-payment, manual-payment, or external-payment workflows should respond to a new offline payment. |
| PayPal Dispute | `paypal_dispute.created` | A PayPal dispute was created. | Use when PayPal dispute review, evidence collection, or support escalation should start. |
| PayPal Transaction | `paypal_transaction.created` | A PayPal transaction was created. | Use when PayPal payment activity should trigger fulfillment, accounting, support, or reporting workflows. |
| Pending Refund | `pending_refund.created` | A pending refund was created. | Use when any refund activity matters, regardless of item type or refund scope. |
| Pending Refund | `pending_refund.created.product_sale` | A pending refund was created for a product sale. | Use when a workflow should run only for product-line refund activity. |
| Pending Refund | `pending_refund.created.product_sale.full` | A pending refund was created for a product sale, for the full amount. | Use when a fully refunded product line should trigger restock, cancellation, support, or reporting workflows. |
| Pending Refund | `pending_refund.created.product_sale.partial` | A pending refund was created for a product sale, for a partial amount. | Use when a partial product refund needs different handling than a full product refund. |
| Pending Refund | `pending_refund.created.shipping` | A pending refund was created for a shipment. | Use when shipping-related refund activity should trigger fulfillment, carrier, or support review. |
| Pending Refund | `pending_refund.created.shipping.full` | A pending refund was created for a shipment, for the full amount. | Use when the entire shipping charge was refunded and shipping/customer communication may need review. |
| Pending Refund | `pending_refund.created.shipping.full.has_fulfillment` | A pending refund was created for a shipment, for the full amount, and the shipment is associated with a fulfillment account. | Use when a full shipping refund should notify or audit a connected fulfillment process. |
| Pending Refund | `pending_refund.created.shipping.full.no_fulfillment` | A pending refund was created for a shipment, for the full amount, and the shipment is not associated with a fulfillment account. | Use when a full shipping refund should be handled internally because no fulfillment account is attached. |
| Pending Refund | `pending_refund.created.shipping.has_fulfillment` | A pending refund was created for a shipment and the shipment is associated with a fulfillment account. | Use when any shipping refund tied to fulfillment should trigger fulfillment-aware review. |
| Pending Refund | `pending_refund.created.shipping.no_fulfillment` | A pending refund was created for a shipment and the shipment is not associated with a fulfillment account. | Use when any shipping refund without a fulfillment account should be handled by internal support or operations. |
| Pending Refund | `pending_refund.created.shipping.partial` | A pending refund was created for a shipment, for a partial amount. | Use when partial shipping-refund handling differs from full shipping-refund handling. |
| Pending Refund | `pending_refund.created.shipping.partial.has_fulfillment` | A pending refund was created for a shipment, for a partial amount, and the shipment is associated with a fulfillment account. | Use when a partial shipping refund should trigger fulfillment-aware investigation or adjustment. |
| Pending Refund | `pending_refund.created.shipping.partial.no_fulfillment` | A pending refund was created for a shipment, for a partial amount, and the shipment is not associated with a fulfillment account. | Use when a partial shipping refund should be handled internally without fulfillment-account involvement. |
| Pending Refund | `pending_refund.created.subscription_renewal` | A pending refund was created for a subscription renewal. | Use when refund handling should target recurring-billing renewal activity. |
| Pending Refund | `pending_refund.created.subscription_renewal.full` | A pending refund was created for a subscription renewal, for the full amount. | Use when a full renewal refund should trigger subscription support, retention, or accounting review. |
| Pending Refund | `pending_refund.created.subscription_renewal.partial` | A pending refund was created for a subscription renewal, for a partial amount. | Use when a partial renewal refund needs different handling than a full renewal refund. |
| Pending Refund | `pending_refund.created.tax` | A pending refund was created for a tax. | Use when tax-specific refund handling or accounting visibility is needed. |
| Pending Refund | `pending_refund.created.tax.full` | A pending refund was created for a tax, for the full amount. | Use when the full tax amount was refunded and tax/accounting workflows should react. |
| Pending Refund | `pending_refund.created.tax.partial` | A pending refund was created for a tax, for a partial amount. | Use when partial tax refunds require separate accounting or review. |
| Product | `product.created` | A product was created. | Use when catalog setup, product sync, or product-review workflows should respond to new products. |
| Product | `product.deleted` | A product was deleted. | Use when catalog cleanup, external sync, or operational review should respond to product removal. |
| Product | `product.updated` | A product was updated. | Use when product changes should sync to shops, reporting systems, or review workflows. |
| Product Sale | `product_sale.created` | A product sale was created. | Use when line-item purchase activity should trigger product-level fulfillment, reporting, or automation. |
| Sale | `sale.created` | A sale was created. | Use when every sale attempt matters, regardless of payment outcome. |
| Sale | `sale.created.failed` | A sale was created, but with an unsuccessful result, either due to an error, payment decline, merchant error, merchant hold, or fraud detection. | Use when all failed sale outcomes should enter one broad recovery or review workflow. |
| Sale | `sale.created.failed.declined` | A sale was created, but the payment attempt failed due to a payment decline. | Use when decline-specific recovery, retry, or customer follow-up should run. |
| Sale | `sale.created.failed.error` | A sale was created, but the payment attempt failed due to an error. | Use when gateway/system error handling should be separated from normal declines. |
| Sale | `sale.created.failed.fraud_detected` | A sale was created, but the payment attempt failed due to a fraud detection. | Use when fraud-blocked purchase attempts should go to risk review instead of payment recovery. |
| Sale | `sale.created.failed.merchant_error` | A sale was created, but the payment attempt failed due to a merchant error. | Use when merchant-account or gateway-configuration problems should alert operations. |
| Sale | `sale.created.failed.merchant_hold` | A sale was created, but the payment attempt failed due to a merchant hold. | Use when held transactions need merchant-account review or manual follow-up. |
| Sale | `sale.created.failed.no_gateway` | A sale was created, but the payment profile cascade did not have an available gateway to process payment. | Use when payment-routing configuration needs immediate attention. |
| Sale | `sale.created.success` | A sale was created with a successful result. | Use when successful sales should trigger a workflow whether the sale is paid immediately or pending payment. |
| Sale | `sale.created.success.has_salvage` | A sale was created with a successful result and has a salvage transaction. | Use when successful sale creation still includes salvage/recovery context that should be reviewed. |
| Sale | `sale.created.success.is_upsell` | A sale was created with a successful result and is marked as an upsell. | Use when successful upsell activity should trigger a separate workflow from normal sales. |
| Sale | `sale.created.success.paid` | A sale was created with a successful result and has a payment. | Use when the workflow should only run after a paid sale, not merely any successful sale creation. |
| Sale | `sale.created.success.paid.has_salvage` | A sale was created with a successful result, has a payment and a salvage transaction. | Use when paid sales with salvage context need special revenue-recovery or review handling. |
| Sale | `sale.created.success.paid.is_upsell` | A sale was created with a successful result, has a payment and is marked as an upsell. | Use when the workflow should run only for paid upsell sales. |
| Sale | `sale.created.success.pending` | A sale was created with a successful result and is pending payment. | Use when pending-payment sales should be handled separately from paid sales. |
| Sale | `sale.created.success.pending.is_upsell` | A sale was created with a successful result, is pending payment and is marked as an upsell. | Use when pending-payment upsells need special follow-up. |
| Sale | `sale.updated.fraud_alert.added` | A sale was updated with a fraud alert being added. | Use when a sale that now has a fraud alert should trigger risk review or customer-service caution. |
| Sale | `sale.updated.fraud_alert.removed` | A sale was updated with a fraud alert being removed. | Use when a sale is cleared from fraud alert and downstream workflows can resume. |
| Salvage Transaction | `salvage_transaction.updated.processed` | A salvage transaction was processed, regardless of result. | Use when every salvage processing attempt should be tracked or logged. |
| Salvage Transaction | `salvage_transaction.updated.processed.failed` | A salvage transaction was processed but payment was unsuccessful. | Use when failed salvage attempts should trigger continued recovery or escalation. |
| Salvage Transaction | `salvage_transaction.updated.processed.success` | A salvage transaction was processed and payment was successful. | Use when recovered revenue should trigger fulfillment, accounting, or customer communication. |
| Sentinel | `sentinel.alert` | Sentinel rejected a purchase attempt due to fraud detection or fraud firewall. | Use when all Sentinel blocks should trigger the same fraud-prevention workflow. |
| Sentinel | `sentinel.alert.firewall_block` | Sentinel rejected a purchase attempt due to fraud firewall. | Use when firewall-specific blocks should be tracked or handled differently from fraud-detection blocks. |
| Sentinel | `sentinel.alert.fraud_detected` | Sentinel rejected a purchase attempt due to fraud detection. | Use when fraud-detected blocks should trigger risk review or fraud-analysis workflows. |
| Shipping | `shipping.created` | A shipment was created. | Use when any new shipment should trigger fulfillment, tracking, or customer communication. |
| Shipping | `shipping.created.has_fulfillment` | A shipment was created and is associated with a fulfillment account. | Use when the shipment should trigger fulfillment-account-aware automation. |
| Shipping | `shipping.created.no_fulfillment` | A shipment was created and is not associated with a fulfillment account. | Use when internal operations should handle shipments without fulfillment-account routing. |
| Shipping | `shipping.updated.delivered` | A shipment was updated as delivered. | Use when delivery confirmation should trigger customer communication, support follow-up, or completion workflows. |
| Shipping | `shipping.updated.ship_to` | A shipment was updated with the ship-to information being modified. | Use when address-change review, fulfillment correction, or fraud review should run. |
| Shipping | `shipping.updated.shipped` | A shipment was updated as shipped with tracking number. | Use when tracking notifications or shipped-status workflows should run. |
| Subscription | `subscription.created` | A subscription was created. | Use when a new recurring customer relationship should trigger onboarding, welcome, or monitoring workflows. |
| Subscription | `subscription.updated.renewed` | A subscription was renewed, regardless of result. | Use when every renewal attempt should be tracked at the subscription level. |
| Subscription | `subscription.updated.renewed.failed` | A subscription was renewed but with an unsuccessful result either due to error, payment decline, merchant error or merchant hold. | Use when failed renewal outcomes should trigger retention or payment recovery. |
| Subscription | `subscription.updated.renewed.success` | A subscription was renewed successfully with payment. | Use when successful renewal payment should trigger fulfillment, reporting, or customer communication. |
| Subscription | `subscription.updated.status` | A subscription's status was updated, regardless of new status. | Use when any subscription status change should be monitored. |
| Subscription | `subscription.updated.status.active` | A subscription's status was updated, with a status of Active. | Use when activation/reactivation should trigger a workflow. |
| Subscription | `subscription.updated.status.cancelled` | A subscription's status was updated, with a status of Cancelled. | Use when cancellation should trigger retention, support, or account-update workflows. |
| Subscription | `subscription.updated.status.occurrence_limit` | A subscription's status was updated, with a status of Occurrence Limit. | Use when a subscription reaches its planned renewal limit and should be reviewed or communicated. |
| Subscription | `subscription.updated.status.overdue` | A subscription's status was updated, with a status of Overdue. | Use when overdue subscriptions should trigger payment recovery or customer outreach. |
| Subscription | `subscription.updated.status.suspended` | A subscription's status was updated, with a status of Suspended. | Use when paused subscriptions should trigger support, retention, or internal review. |
| Subscription Renewal | `subscription_renewal.updated.failed` | A subscription renewal was updated as unsuccessful. Useful for identifying a specific renewal as unsuccessful either during or after the renewal was created. | Use when the exact renewal item failed and the workflow needs renewal-level context. |
| Subscription Renewal | `subscription_renewal.updated.success` | A subscription renewal was updated as successful. Useful for identifying a specific renewal as successful either during or after the renewal was created. | Use when the exact renewal item succeeded and the workflow needs renewal-level context. |
| Tax | `tax.created` | A tax was created. | Use when tax creation should trigger accounting, audit, or tax-reporting workflows. |
| Transaction | `transaction.created` | A credit card transaction was created. | Use when credit-card transaction activity should trigger payment, accounting, fraud, or support workflows. |
| Trial | `trial.created` | A trial was created. | Use when a new trial should trigger onboarding, trial tracking, or customer communication. |
| Trial | `trial.updated.cancelled` | A trial was cancelled. | Use when cancellation of a trial should trigger support, retention, or reporting workflows. |
| Trial | `trial.updated.expired` | A trial was updated as expired, either successfully or not. | Use when all trial expirations should be handled in one workflow. |
| Trial | `trial.updated.expired.failed` | A trial was expired but payment was unsuccessful. | Use when failed trial-expiration payments should trigger recovery or follow-up. |
| Trial | `trial.updated.expired.success` | A trial was expired and payment was successful. | Use when successful trial conversion should trigger fulfillment, subscription, or customer communication. |
| Trial | `trial.updated.extended` | A trial was updated and extended by a specific number of days. | Use when extension activity should be tracked, communicated, or reviewed. |
| Trial | `trial.updated.shortened` | A trial was updated and shortened by a specific number of days. | Use when shortened-trial activity should trigger internal review or customer communication. |

A useful decision rule:

| Question | Better Choice |
|---|---|
| Should this workflow run for every item in a category? | Use a broad notation, such as `sale.created`, `shipping.created`, or `subscription.updated.status`. |
| Should this workflow run only after payment succeeds? | Use a paid/success notation, such as `sale.created.success.paid`, `subscription.updated.renewed.success`, or `trial.updated.expired.success`. |
| Should this workflow run only for failure/recovery? | Use a failed notation, such as `sale.created.failed.declined`, `subscription_renewal.updated.failed`, or `trial.updated.expired.failed`. |
| Should this workflow run only for fulfillment-specific cases? | Use a fulfillment-aware notation, such as `shipping.created.has_fulfillment` or `pending_refund.created.shipping.full.has_fulfillment`. |
| Should this workflow run only for a status transition? | Use a status-specific notation, such as `subscription.updated.status.cancelled` or `subscription.updated.status.overdue`. |

## Event Data Should Drive the Workflow

Features that listen to Events should use the Event data rather than guessing what happened.

Good event-driven workflow logic checks:

- the exact `event_trigger`,
- the `item_type`,
- the `item_event`,
- the current item status inside `item_details`,
- the related customer, sale, shipping, subscription, or transaction context,
- whether the item still qualifies for the intended action.

This is especially important when multiple notations may exist on one Event.

## Events Are Not the Action Themselves

An Event is the signal that something happened. It is not the action that responds.

For example:

```text
shipping.updated.shipped
```

means a Shipping record was updated as shipped.

The Event itself does not send an email, call a customer, run custom code, or trigger an AI workflow by itself. A RevCent feature must be configured to listen for that Event and perform the desired action.

## Best Practices

- Use descriptive event notations that match the exact business need.
- Avoid overly broad triggers when the workflow should only run for a narrow condition.
- Use broad triggers only when the workflow intentionally handles multiple outcomes.
- Confirm the `item_type` before using `item_details`.
- Use filter Functions for AI Assistants and AI Voice Agents when custom eligibility logic is required.
- Be careful with customer-facing actions such as emails and calls; make sure the Event actually represents the intended moment.
- For sale outcomes, distinguish `sale.created`, `sale.created.success`, `sale.created.success.paid`, and failed-sale notations.
- For shipping outcomes, distinguish `shipping.created`, `shipping.updated.shipped`, and `shipping.updated.delivered`.
- For subscription outcomes, distinguish subscription-level events from subscription-renewal-level events.

## Common Mistakes to Avoid

Do not:

- assume every Event has only one notation,
- use a broad notation when a specific notation is required,
- use `sale.created` when the workflow should only run after payment,
- treat `sale.created.success` as always paid without checking the notation or item details,
- use a shipping Event without confirming whether it means created, shipped, or delivered,
- ignore the `item_type` when reading `item_details`,
- assume an Event performs an action unless a feature is configured to listen for it,
- trigger customer-facing automation without verifying the event condition,
- confuse Events with item records themselves.

## Summary

Events are RevCent's structured way of describing what happened inside an account.

Each Event is tied to an item type, an item event, one or more notations, and item details. Other RevCent features use those Events as trigger points.

Functions can run custom JavaScript when an Event happens. Email Templates can communicate at important lifecycle moments. AI Assistants can start autonomous workflows from event context. AI Voice Agents can use Events to decide when customer calls or voice workflows should happen.

The key to using Events well is choosing the correct notation. Broad notations catch more activity; specific notations capture narrower business moments. A good RevCent workflow uses the notation, item type, and item details together so the right feature runs for the right reason.


---
Document Parent Directory
* [Features](https://revcent.com/documentation/markdown/ecosystem/feature/index.md) - Non-technical markdown documentation for features within the RevCent ecosystem. A feature is a part of the RevCent ecosystem that a user can create and configure.