Skip to main content

BillingPreviewRun

Zuora

BillingPreviewRun

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:

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:

  1. Call create using the BillingPreviewRun object. Results are generated asynchronously. If setup, a notification is sent on completion.
  2. 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 NotificationZ-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.

Typezns: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.

TypedateTime

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.

TypedateTime

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 chargeTypeToExcludetargetDateincludingEvergreenSubscription, 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.

TypedateTime

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.

Typeint

Version notes: WSDL 61.0+

Values: automatically generated

UpdatedById optional Query
Filter

The ID of the user who last updated the billing preview run.

Typezns: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.