BillingPreviewRun

Last updated
Save as PDF

The BillingPreviewRun object generates a preview of future invoice items for multiple customer accounts through a billing preview run. A billing preview run asynchronously generates a downloadable CSV file containing a preview of invoice item data for a batch of customer accounts. Alternatively, you can use data source to query Billing Preview Run Result if you do not want a CSV file to be generated.

You can run up to 20 billing preview runs in batches concurrently. A single batch of customer accounts can only have one billing preview run at a time. So you can have up to 20 batches running at the same time. If you create a billing preview run for all customer batches, you cannot create another billing preview run until this preview run is completed.

As of Zuora R181, WSDL version 61.0, the feature formerly known as forecast API was renamed to Billing Preview API. Zuora recommends that you upgrade to this latest version as soon as possible. Download WSDL version 61.0+ to use the Billing Preview API. See Zuora WSDL for information about downloading the current version.

Supported Calls

You can use this object with the following calls:

create
query

To preview invoice items for a single customer account, do not use BillingPreviewRun. Use BillingPreview() instead.

If you have the Invoice Settlement feature enabled, the BillingPreviewRun create() call is not supported. The alternative is to use the Create a billing preview run REST API operation.

Walkthroughs and Use Cases

The BillingPreviewRun object gets invoice item previews for multiple customer accounts. To use this object:

Call create using the BillingPreviewRun object. Results are generated asynchronously. If setup, a notification is sent on completion.
Call query with the ResultFileUrl field of the BillingPreviewRun object to obtain download URL for the results in zipped CSV format. See field descriptions for more information about the generated CSV result file.

Notifications

You can create email and callout notifications to signal that the billing preview run completed successfully and results are available for download or completed with errors. To create a billing preview run notification and select the following options:

Define Notification : Z-Billing
Event Category: Billing Preview RunCompletion
Billing Preview Run Status: Completion or Error

See Create and Edit Notifications and Supported Event Types for more information.

Field Descriptions

All field names are case sensitive. Check enumerated values in descriptions to confirm capitalization and spacing. See Field Types for additional information.

Name	Required to Create?	Allowed Operations	Description
AssumeRenewal	optional	Create Filter	Indicates whether to generate a preview of future invoice items with the assumption that the subscriptions are renewed. Type: string Character limit: 50 Version notes: WSDL 81.0+ Values: Set one of the following values in this field to decide how the assumption is applied in the billing preview. All: The assumption is applied to all the subscriptions. Zuora generates preview invoice item data from the first day of the customer's next billing period to the target date. None: (Default) The assumption is not applied to the subscriptions. Zuora generates preview invoice item data based on the current term end date and the target date. If the target date is later than the current term end date: Zuora generates preview invoice item data from the first day of the customer's next billing period to the current term end date. If the target date is earlier than the current term end date: Zuora generates preview invoice item data from the first day of the customer's next billing period to the target date. Autorenew: The assumption is applied to the subscriptions that have auto-renew enabled. Zuora generates preview invoice item data from the first day of the customer's next billing period to the target date. Note: This field can only be used if the subscription renewal term is not set to 0. If the `AssumeRenewal` field is set to `Autorenew` or `All`, the returned result includes the renewed rate plan charge which is a non-permanent object, so the ID is a transient ID.
Batches	optional	Create Query Filter	The customer batches to include in the billing preview run. You can specify multiple batches separated by comma in this field. If not specified, all customer batches are included. Type: string Character limit: 100 Version notes: WSDL 113.0+ Values: Batchn where n is a number between 1 and 20, e.g., Batch15
CreatedById	optional	Query Filter	The ID of the user who created the BillingPreviewRun object. Type: zns:ID Character limit: 32 Version notes: WSDL 61.0+ Values: automatically generated
CreatedDate	optional	Query Filter	The date when the BillingPreviewRun object was created in Zuora. Type: dateTime Character limit: 29 Version notes: WSDL 61.0+ Values: automatically generated
ChargeTypeToExclude	optional	Create Query Filter	The charge types to exclude from the forecast run. Type: string Character limit: 50 Version notes: WSDL 61.0+ Values: OneTime, Recurring, Usage including any comma-separated combination of these values.
EndDate	optional	Query Filter	The date and time when the billing preview run completes. Type: dateTime Character limit: 29 Version notes: WSDL 61.0+ Values: automatically generated
ErrorMessage	optional	Query Filter	The error message generated by a failed billing preview run. Type: string Character limit: 255 Version notes: WSDL 61.0+ Values: automatically generated
Id	optional	Query Filter	The ID of this object. Type: zns:ID Character limit: 32 Version notes: WSDL 61.0+ Values: automatically generated
IncludingDraftItems	optional	Create Query Filter	Whether draft document items are included in the billing preview run. By default, draft document items are not included. This field loads draft invoice items and credit memo items. Draft credit memo items are available only if you have the Invoice Settlement feature enabled. The `chargeTypeToExclude`, `targetDate`, `includingEvergreenSubscription`, and `assumeRenewal` fields do not affect the behavior of the `includingDraftItems` field. Type: boolean Character limit: 5 Version notes: WSDL 110.0+ Values: FALSE (default), TRUE
IncludingEvergreenSubscription	optional	Create Query Filter	Indicates if evergreen subscriptions are included in the billing preview run. By default, evergreen subscriptions are not included. Type: boolean Character limit: 5 Version notes: WSDL 61.0+ Values: FALSE (default), TRUE
ResultFileUrl	optional	Query Filter	The URL of the zipped CSV result file generated by the billing preview run. This file contains the preview invoice item data for the specified customers. See field descriptions for more information about the generated CSV result file. Type: string Character limit: 255 Version notes: WSDL 61.0+ Values: automatically generated
RunNumber	optional	Query Filter	The run number of the billing preview run. Type: string Character limit: 50 Version notes: WSDL 61.0+ Values: automatically generated and prefixed with BPR, such as BPR-10000001.
StartDate	optional	Query Filter	The date and time when the billing preview run starts. Type: dateTime Character limit: 29 Version notes: WSDL 61.0+ Values: automatically generated
Status	optional	Query Filter	The status of the >billing preview run. Type: string  (enum) Character limit: 50 Version notes: WSDL 61.0+ Values: Pending, Processing, Completed, Error
SucceededAccounts	optional	Query Filter	The number of accounts for which preview invoice item data was successfully generated during the billing preview run. Type: int Version notes: WSDL 61.0+ Values: automatically generated
TargetDate	required	Create Query Filter	The target date for the billing preview run. The billing preview run generates preview invoice item data from the first day of the customer's next billing period to the TargetDate. If the TargetDate is later than the subscription current term end date, the preview invoice item data is generated from the first day of the customer's next billing period to the current term end date. If you want to generate preview invoice item data past the end of the subscription current term, specify the AssumeRenewal field in the request. Type: date: Supported as of WSDL version 69+ dateTime: Supported through WSDL version 68 Character limit: 29 Version notes: WSDL 61.0+
TotalAccounts	optional	Query Filter	The total number of accounts in the billing preview run. Type: int Version notes: WSDL 61.0+ Values: automatically generated
UpdatedById	optional	Query Filter	The ID of the user who last updated the billing preview run. Type: zns:ID Character limit: 32 Version notes: WSDL 61.0+ Values: automatically generated
UpdatedDate	optional	Query Filter	The date when the billing preview run was last updated. Type: dateTime Character limit: 29 Version notes: WSDL 61.0+ Values: automatically generated

Additional Field Detail

SucceededAccounts

The number of accounts for which preview invoice item data was successfully generated during the billing preview run.

Details of any accounts which fail during the billing preview operation are recorded in a separate file. This is included in the zip file along with the CSV.

TargetDate

The target date for the billing preview run. The billing preview run generates preview invoice item data from the first day of the customer's next billing period to the TargetDate.

The next billing period is the period for which the customer has yet to be invoiced. The billing preview run will start the preview from the next billing period that customers expect for their next invoice.

This date can be in the past or the future, depending on the target date of the last bill run for this customer.

Field Descriptions of the CSV Output File

Name	Description
Account: ID	The account ID of the invoice item owner.
Rate Plan Charge: ID	The ID of the rate plan charge associated with this invoice item.
Invoice Item: Charge Amount	The amount being charged for this invoice item.
Invoice Item: Processing Type	The kind of charge: charge discount prepayment tax
Invoice Item: Service Start Date	The start date of the service period associated with this invoice item.
Invoice Item: Service End Date	The end date of the service period associated with this invoice item.
Invoice Item: Charge Date	The date when the Invoice Item is created.
Invoice Item: ID	The ID of the rate plan charge that is associated with this invoice item.
Subscription: SubscriptionId	The ID of the subscription associated with the invoice item. If renewal is supported in the preview run, the corresponding subscription will be renewed. After the preview run is completed, the renewed subscription will be rolled back. Therefore, the subscription ID is transient for renewed subscriptions; you cannot retrieve information about the subscription by `SubscriptionId` from the Zuora system.
Invoice Item: AppliedToInvoiceItemId	Associates a discount invoice item to a specific invoice item.
Invoice Item: Quantity	The number of units for this invoice item.
Invoice Item: UOM	The units of this invoice item.
Invoice Item: ChargeType	The type of the charge: OneTime Recurring Usage
Invoice Item: SubscriptionNumber	The subscription number of the invoice item. For example, A-S00000019.
Invoice Item: ChargeNumber	The charge number of the invoice item. For example, C-00000060.