Skip to main content

BillingPreviewRequest

Zuora

BillingPreviewRequest

  1. Last updated
  2. Save as PDF

The BillingPreviewRequest object is used with a billingPreview call to request a preview of invoice items for a single customer account. This SOAP API reference describes this complex type including supported calls and field descriptions.

This feature is in Limited Availability. If you want 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 complex type with the billingPreview call.

​Walkthroughs and Use Cases

The BillingPreviewRequest complex type is used to request an invoice item preview for a single customer account. To use this complex type:

  1. Request an invoice item billing preview for a single customer account by using a BillingPreviewRequest complex type as the argument to a billingPreview call.
  2. Results are returned synchronously as an array of InvoiceItem objects in a BillingPreviewRequest complex type.

Field Descriptions

Name Required? Allowed Operations Description
AssumeRenewal optional Create

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.

AccountId

required

Create

The ID of the customer account to which the billing preview applies.

Type: string

Character limit: 25

Version notes: WSDL 61.0+

Values: ID of the customer account to which the billing preview applies.

ChargeTypeToExclude

optional

Create

The charge types to exclude from the billing preview.

Type: string

Character limit: 50

Version notes: WSDL 61.0+

Values: OneTime, Recurring, Usage including any comma-separated combination of these values.

TargetDate

required

Create

The target date for the billingPreview call. The billingPreview call 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+

Values: a valid date and time value

IncludingEvergreenSubscription

optional

Create

Indicates if evergreen subscriptions are included in the billingPreview call.

Type: boolean

Character limit: 5

Version notes: WSDL 61.0+

Values: FALSE (default), TRUE

TargetDate

The target date for the call. The forecast call generates preview invoice item data from the first day of the customer's next billing period to the TargetDate specified in the BillingPreviewtRequest complex type.

The customer's next billing period is the period for which the customer has yet to be invoiced. The date this period begins is particular to each customer, and can start in the past or the future depending on the target date of the customer's last bill run.