Knowledge Center

Knowledge Center > API > SOAP API > SOAP API Object Reference > BillingPreviewRun

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.

You can run up to 10 billing previews 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 10 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.

This feature is in Limited Availability. If you wish to have access to the feature, submit a request at Zuora Global Support

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.

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.

Batch optional Create
Query
Filter

The customer batch to include in the billing preview run. If not specified, all customer batches are included.

Type: string

Character limit: 25

Version notes: WSDL 61.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

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

Id of a product 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.

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, C-00000060.
Invoice Item: ChargeNumber The charge number of the invoice item. For example, A-S00000019.
Last modified

Tags

Classifications

(not set)