Skip to main content

Custom Scheduled Events

Zuora

Custom Scheduled Events

You can use the Scheduled Events API operations to define, update, and list scheduled events.

To define a custom scheduled event, you must specify the base object, the object’s base field and the scheduled time (hour and minute).

Once you have defined a custom scheduled event, you can create notification definitions for it and further refine the event trigger by specifying the notification parameters, including the number of days and the date evaluation condition (before or after a specified number of days).

A custom scheduled event notification is evaluated at the scheduled time of the related scheduled event on a daily basis. If the date meets the combination of the base field and the notification parameters, the notification will be triggered immediately.

Note: A maximum of 1000 scheduled event triggers can be created.

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
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
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
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
RatePlanChargeTier CreatedDate, UpdatedDate The profile associated with the account
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
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
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
Usage StartDateTime, EndDateTime, SubmissionDateTime, CreatedDate, UpdatedDate 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.