Skip to main content

Custom Scheduled Events

Zuora

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
PaymentMethodTransactionLog CreatedDate, TransactionDate 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
PaymentTransactionLog CreatedDate, TransactionDate 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:

  1. 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
  2. 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.