Custom Scheduled Events
You can manage custom scheduled events through the Zuora UI, such as creating, editing, deleting, or cloning. See Custom Scheduled Events API for more information about managing custom scheduled events through the API.
To define a custom scheduled event, you must specify the base object, base field, and scheduled time (hour and minute). Zuora evaluates each custom scheduled event at the scheduled time on a daily basis.
Once you have defined a custom scheduled event, you can specify a date condition (N days before or after) when creating a notification definition for this event. Zuora will send the notification based on the date in the base field of the custom scheduled event and the date condition in the notification definition. For more information, see Evaluation and triggering strategy for custom scheduled events and notifications.
Note that a maximum of 1000 scheduled event triggers can be created.
Evaluation and triggering strategy for custom scheduled events and notifications
The following table lists evaluation and triggering-related configurations in custom scheduled events and notification definitions:
| Field | Description | |
|---|---|---|
| Custom scheduled event | Base Object | The object that the event is associated with. |
| Base Field | The date that the date condition in notification definitions is based on. The base field must be a date or timestamp formatted field on the base object. |
|
| Hour | The scheduled time (hour) at which the event and associated notifications are evaluated on a daily basis. | |
| Minute | The scheduled time (minute) at which the event and associated notifications are evaluated on a daily basis. | |
| Notification definition | Days | The date condition (number of days) that determines the day that the notification will be triggered. |
| Condition | The date condition (before or after) that determines the day that the notification will be triggered. |
Zuora evaluates each custom scheduled event and associated notification definitions at the scheduled time (the Hour and Minute) on a daily basis.
During the evaluation, Zuora compares today’s date with the target date based on the Base Field, Days, and Condition. If they match, the notification is triggered. See Use Cases for examples of how to calculate the target date.
The trigger condition in a custom scheduled event serves the same purpose as it does in a custom event: to apply additional criteria to determine whether the event should be triggered. For example, you can define a trigger condition to check whether the invoice amount is greater than a given value. However, you cannot specify the date condition (N days before or after) in trigger conditions. You must specify the date condition in the Days and Condition fields in notification definitions.
Base objects for scheduled events
Custom scheduled event triggers created against base objects such as AccountingCode do not have the context of a customer account, and the default communication profile of the tenant is used for notifications.
For example, the Accounting Code object is set up in your Zuora tenant based on your corporate business rules. This does not vary or depend on any configuration of the account. Instead, accounting codes are settings on the system level. Therefore, no customer account is associated with this object and Zuora uses and localizes notification messages based on the default communication profile.
In contrast, custom event triggers created against objects like Invoice have the context of a customer account, and thus the the communication profile specified in the account is used for notifications. Zuora sends localized data, such as date formatting, based on the communication profile associated with the account.
The following table summarizes the supported base objects, base fields, and the corresponding communication profile used for notifications. For more information, see Communication profiles.
| Supported base object | Supported base field | Communication profile used |
|---|---|---|
| Account | CreatedDate, LastInvoiceDate, UpdatedDate, TaxExemptEffectiveDate, TaxExemptExpirationDate | The profile associated with the account |
| AccountingCode | CreatedDate, UpdatedDate | Tenant default profile |
| AccountingPeriod | CreatedDate, StartDate, EndDate, UpdatedDate | Tenant default profile |
| Amendment | ContractEffectiveDate, CustomerAcceptanceDate, EffectiveDate, ResumeDate, SpecificUpdateDate, SuspendDate, TermStartDate, ServiceActivationDate, BookingDate, CreatedDate, UpdatedDate | The profile associated with the account |
| BillingRun | CreatedDate, EndDate, ExecutedDate, InvoiceDate, PostedDate, StartDate, TargetDate, LastEmailSentTime, ScheduledExecutionTime, UpdatedDate | Tenant default profile |
| Contact | CreatedDate, UpdatedDate | The profile associated with the account |
| CreditBalanceAdjustment | AdjustmentDate, CancelledOn, CreatedDate, UpdatedDate | The profile associated with the account |
| CreditMemo | CancelledOn, ExchangeRateDate, MemoDate, PostedOn, TargetDate, CreatedDate, UpdatedDate | The profile associated with the account |
| CreditMemoApplication | CreatedDate, EffectiveDate, UpdatedDate | The profile associated with the account |
| CreditMemoApplicationItem | CreatedDate, EffectiveDate, UpdatedDate | The profile associated with the account |
| CreditMemoItem | ChargeDate, ServiceEndDate, ServiceStartDate, CreatedDate, UpdatedDate | The profile associated with the account |
| CreditMemoPart | CreatedDate, UpdatedDate | The profile associated with the account |
| DebitMemo | CancelledOn, DueDate, ExchangeRateDate, MemoDate, PostedOn, TargetDate, CreatedDate, UpdatedDate | The profile associated with the account |
| DebitMemoItem | ChargeDate, ServiceEndDate, ServiceStartDate, CreatedDate, UpdatedDate | The profile associated with the account |
| Feature | CreatedDate, UpdatedDate | Tenant default profile |
| Fulfillment | CreatedDate, UpdatedDate, FulfillmentDate, BillTargetDate | The profile associated with the account |
| Fund | CreatedDate, UpdatedDate | The profile associated with the account |
| Invoice | DueDate, InvoiceDate, LastEmailSentDate, PostedDate, TargetDate, CreatedDate, UpdatedDate | The profile associated with the account |
| InvoiceAdjustment | AdjustmentDate, CancelledOn, CreatedDate, UpdatedDate | The profile associated with the account |
| InvoiceItem | ChargeDate, RevRecStartDate, ServiceEndDate, ServiceStartDate, CreatedDate, UpdatedDate | The profile associated with the account |
| InvoiceItemAdjustment | AdjustmentDate, CancelledDate, ServiceEndDate, ServiceStartDate, CreatedDate, UpdatedDate | The profile associated with the account |
| JournalEntry | JournalEntryDate, TransferDate, CreatedDate, UpdatedDate | Tenant default profile |
| JournalEntryItem | CreatedDate, UpdatedDate | Tenant default profile |
| Order | CreatedDate, OrderDate, UpdatedDate | The profile associated with the account |
| OrderAction | CreatedDate, UpdatedDate, ContractEffectiveDate, CustomerAcceptanceDate, ServiceActivationDate, TermStartDate, SuspendDate, ResumeDate, CancellationEffectiveDate | The profile associated with the account |
| OrderLineItem | CreatedDate, UpdatedDate | The profile associated with the account |
| Payment | CancelledOn, MarkedForSubmissionOn, SettledOn, SubmittedOn, CreatedDate, EffectiveDate, LastEmailDateTime, UpdatedDate | The profile associated with the account |
| PaymentApplication | EffectiveDate, CreatedDate, UpdatedDate | The profile associated with the account |
| PaymentMethod | LastFailedSaleTransactionDate, LastTransactionDateTime, MandateCreationDate, MandateUpdateDate, CreatedDate, UpdatedDate | The profile associated with the account |
| PaymentPart | CreatedDate, UpdatedDate | The profile associated with the account |
| PaymentSchedule | CreatedDate, UpdatedDate, StartDate, NextPaymentDate, RecentPaymentDate | The profile associated with the account |
| PaymentScheduleItem | CreatedDate, UpdatedDate, ScheduledDate | The profile associated with the account |
| Product | EffectiveStartDate, EffectiveEndDate, CreatedDate, UpdatedDate | Tenant default profile |
| ProductFeature | CreatedDate, UpdatedDate | Tenant default profile |
| ProductRatePlan | EffectiveStartDate, EffectiveEndDate, CreatedDate, UpdatedDate | Tenant default profile |
| ProductRatePlanCharge | CreatedDate, UpdatedDate | Tenant default profile |
| ProductRatePlanChargeTier | CreatedDate, UpdatedDate | Tenant default profile |
| RatePlan | CreatedDate, UpdatedDate | The profile associated with the account |
| RatePlanCharge | ChargedThroughDate, EffectiveEndDate, EffectiveStartDate, ProcessedThroughDate, SpecificEndDate, TriggerDate, OriginalOrderDate, AmendedByOrderOn, CreatedDate, UpdatedDate | The profile associated with the account |
| RatePlanChargeTier | CreatedDate, UpdatedDate | The profile associated with the account |
| RatingResult | CreatedDate, UpdatedDate, ServiceStartDate, ServiceEndDate | The profile associated with the account |
| Refund | CancelledOn, MarkedForSubmissionOn, RefundDate, RefundTransactionTime, SettledOn, SubmittedOn, CreatedDate, UpdatedDate | The profile associated with the account |
| RefundApplication | EffectiveDate, CreatedDate, UpdatedDate | The profile associated with the account |
| RefundPart | CreatedDate, UpdatedDate | The profile associated with the account |
| RevenueEvent | RecognitionEnd, RecognitionStart, CreatedDate, UpdatedDate | The profile associated with the account |
| RevenueEventItem | CreatedDate, UpdatedDate | The profile associated with the account |
| RevenueSchedule | ExchangeRateDate, RecognitionPeriodEnd, RecognitionPeriodStart, RevenueScheduleDate, TransactionDate, CreatedDate, UpdatedDate | The profile associated with the account |
| RevenueScheduleItem | CreatedDate, UpdatedDate | The profile associated with the account |
| Subscription | CancelledDate, ContractAcceptanceDate, ContractEffectiveDate, OriginalCreatedDate, ServiceActivationDate, SubscriptionEndDate, SubscriptionStartDate, TermStartDate, TermEndDate, LastBookingDate, CreatedDate, UpdatedDate | The profile associated with the account |
| SubscriptionProductFeature | CreatedDate, UpdatedDate | The profile associated with the account |
| TaxationItem | TaxDate, CreatedDate, UpdatedDate | The profile associated with the account |
|
UpdaterDetail (Payment Method Update object) |
CreatedDate, UpdatedDate, SubmittedResponseTime |
The profile associated with the account |
| Usage | StartDateTime, EndDateTime, SubmissionDateTime, CreatedDate, UpdatedDate | The profile associated with the account |
| ValidityPeriodSummary | CreatedDate, UpdatedDate, StartDate, EndDate | The profile associated with the account |
Custom scheduled event triggers
When you create a custom scheduled event trigger, you must specify the base object, the base field, and the schedule.
Specify the base object
Use the apiObject field to specify which base object to use to evaluate the scheduled events. All available base objects are listed in the table above.
Specify the base field
Use the apiField field to specify which field of the base object to use to evaluate the scheduled events. Note that this must be a date or timestamp format field. All available base fields for each base object are listed in the table above.
Define the schedule
Use the hours and minutes fields to specify the evaluation time of the scheduled events on a daily basis.
Use Cases
Create a "3 days before subscription term end date" scheduled event notification
Follow these steps to create a scheduled event notification:
- Define a “subscription term end date” scheduled event through the Create a scheduled event API operation. Configure the settings as follows:
Field Value apiObject Subscription apiField TermEndDate
(assume the term end date is Oct 5th)hours 10 minutes 30 - Create a "3 days before subscription term end date" scheduled event notification through Zuora UI or the Create a notification definition API operation. Configure the event parameters as follows:
Event parameter Value Days 3 Condition Before
After the notification is created, Zuora evaluates it every day at 10:30 AM. The notification will be triggered on Oct 2nd at 10:30 AM, three days before the subscription term end date (Oct 5th).
Limitations
The custom scheduled events have the following limitations:
- A maximum of 1000 custom scheduled event triggers can be created.
- The trigger for custom scheduled events is based on the localized default timezone of your tenant.