Create a bill run

Creates an ad-hoc bill run or a scheduled bill run.

  • Support to create ad-hoc or scheduled bill runs by batch
  • Support to create ad-hoc or scheduled bill runs for a single account (all subscriptions under this account)
  • Support to create a bill run by subscription (50 or less subscriptions under the same account)

To use this operation, you must have the Create Bill Runs billing permission.

Restrictions and limitations

When using this operation to create bill runs, keep the following restrictions and limitations in mind:

  • When creating batch-level bill runs, you must specify batches and cannot specify billRunFilters.
  • When creating account-level bill runs, you must specify billRunFilters and cannot specify batches. Only one single account is allowed.
  • When creating subscription-level bill runs, you must specify billRunFilters and cannot specify batches. All subscriptions must belong to the same account. At most 50 subscriptions are allowed.
  • If more than 500 bill runs created through this operation are in Pending status, you cannot use this operation to create any more bill runs.
Request
header Parameters
Idempotency-Key
string <= 255 characters

Specify a unique idempotency key if you want to perform an idempotent POST or PATCH request. Do not use this header in other request types.

With this header specified, the Zuora server can identify subsequent retries of the same request using this value, which prevents the same operation from being performed multiple times by accident.

Accept-Encoding
string

Include the Accept-Encoding: gzip header to compress responses as a gzipped file. It can significantly reduce the bandwidth required for a response.

If specified, Zuora automatically compresses responses that contain over 1000 bytes of data, and the response contains a Content-Encoding header with the compression algorithm so that your client can decompress it.

Content-Encoding
string

Include the Content-Encoding: gzip header to compress a request. With this header specified, you should upload a gzipped file for the request payload instead of sending the JSON payload.

Authorization
string

The value is in the Bearer {token} format where {token} is a valid OAuth token generated by calling Create an OAuth token.

Zuora-Track-Id
string <= 64 characters

A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

Zuora-Entity-Ids
string

An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.

Zuora-Org-Ids
string

Comma separated IDs. If you have Zuora Multi-Org enabled, you can use this header to specify which orgs to perform the operation in. If you do not have Zuora Multi-Org enabled, you should not set this header.

The IDs must be a sub-set of the user's accessible orgs. If you specify an org that the user does not have access to, the operation fails.

If the header is not set, the operation is performed in scope of the user's accessible orgs.

Request Body schema: application/json
required
autoEmail
boolean
Default: false

Whether to automatically send emails after Auto-Post is complete.

Note: To use this field, you must first set the Support Bill Run Auto-Post? billing rule to Yes through the Zuora UI.

autoPost
boolean
Default: false

Whether to automatically post the bill run after the bill run is created.

Note: To use this field, you must first set the Support Bill Run Auto-Post? billing rule to Yes through the Zuora UI.

autoRenewal
boolean
Default: false

Whether to automatically renew auto-renew subscriptions that are up for renewal.

batches
Array of strings

The batch of accounts for this bill run.

You can only specify either this field or the billRunFilters field.

Values: AllBatches or an array of Batch*n* where n is one of numbers 1 - 50, for example, Batch7.

Note: By default, you have 50 configurable account batches. To increase the limit to 200 batches, you must have the Performance Booster Elite package.

billCycleDay
string

The day of the bill cycle. This field is only valid if the batches field is specified.

Values:

  • AllBillCycleDays or one of numbers 1 - 31 for an ad-hoc bill run
  • AllBillCycleDays, one of numbers 1 - 31, or AsRunDay for a scheduled bill run
Array of objects (billRunFilters)

The target account or subscriptions for this bill run. You can only specify either this field or the batches field.

billRunType
string

The type of the bill run. If you do not specify any value for this field, the default value is Regular.

  • You can use this field only if the "Catch-Up Bill Run" feature is enabled.
  • You must specify this field to create a catch up bill run.

Values:

  • Regular
  • CatchUp
chargeTypeToExclude
Array of strings

The types of the charges to be excluded from the generation of billing documents. You can specify at most two charge types in the array.

Items Enum: "OneTime" "Recurring" "Usage"
invoiceDate
string <date>

The invoice date for the bill run.

  • When creating an ad-hoc bill run, if you do not specify any value for this field, the default value is the current date.
  • When creating a scheduled bill run, if you do not specify any value for this field, the invoice date is the value of the repeatFrom field.

Note: You can use one of the following methods to specify the invoice date:

  • Specify invoiceDate
  • Specify invoiceDateMonthOffset and InvoiceDateDayOfMonth
invoiceDateMonthOffset
integer

The month offset of invoice date for this bill run compared to bill run execution date.

Notes:

  • This field is only valid when the repeatType field is set to Monthly.
  • You can use one of the following methods to specify the invoice date:
    • Specify invoiceDate
    • Specify invoiceDateMonthOffset and InvoiceDateDayOfMonth
invoiceDateDayOfMonth
integer [ 1 .. 31 ]

The day of month of invoice date for this bill run. Specify a day of the month. If you specify 31, even though the month doesn't have 31, for example, February or April, the date recurs on the end day of each scheduled month.

Notes:

  • This field is only valid when the repeatType field is set to Monthly.
  • You can use one of the following methods to specify the invoice date:
    • Specify invoiceDate
    • Specify invoiceDateMonthOffset and InvoiceDateDayOfMonth
name
string

The name of the bill run.

noEmailForZeroAmountInvoice
boolean
Default: false

Whether to suppress emails for invoices with zero total amount generated in this bill run after the bill run is complete.

It is best practice to not send emails for invoices with zero amount.

Array of objects

The organization(s) that the bill run is created for.

For each item in the array, either the organizationId or the organizationName field is required.

This field is only required when you have already turned on Multi-Org feature.

object (schedule)

Container for information about the scheduled bill run.

targetDate
string <date>

The target date for this bill run.

  • You must specify this field when creating an ad-hoc bill run.
  • For scheduled bill runs, if you do not specify any value for this field, the target date is the value of the repeatFrom field.
targetDateMonthOffset
integer

The month offset of target date for this bill run compared to bill run execution date.

Note: This field is only valid when the repeatType field is set to Monthly.

targetDateDayOfMonth
integer [ 1 .. 31 ]

The day of month of target date for this bill run. Specify a day of the month. If you specify 31, even though the month doesn't have 31, for example, February or April, the date recurs on the end day of each scheduled month.

Note: This field is only valid when the repeatType field is set to Monthly.

Responses
200
post/v1/bill-runs
Request samples
application/json
{
  • "autoEmail": false,
  • "autoPost": false,
  • "autoRenewal": false,
  • "billRunFilters": [
    ],
  • "chargeTypeToExclude": [
    ],
  • "invoiceDate": "2020-02-01",
  • "name": "test",
  • "noEmailForZeroAmountInvoice": false,
  • "targetDate": "2020-02-01"
}
Response samples
application/json
{
  • "autoEmail": false,
  • "autoPost": false,
  • "autoRenewal": false,
  • "batches": null,
  • "billCycleDay": null,
  • "billRunFilters": [
    ],
  • "billRunNumber": "BR-00000016",
  • "chargeTypeToExclude": [
    ],
  • "createdById": "ff808081298c6e5401298c7274a40005",
  • "createdDate": "2022-01-24 19:58:27",
  • "id": "2c9890077e8a8490017e8bf3a5171a43",
  • "invoiceDate": "2020-02-01",
  • "invoiceDateOffset": null,
  • "name": "test",
  • "noEmailForZeroAmountInvoice": false,
  • "schedule": null,
  • "scheduledExecutionTime": null,
  • "status": "Pending",
  • "success": true,
  • "targetDate": "2020-02-01",
  • "targetDateOffset": null,
  • "updatedById": "ff808081298c6e5401298c7274a40005",
  • "updatedDate": "2022-01-24 19:58:27"
}