POST /v1/bill-runs

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.

Servers

https://rest.test.zuora.com
https://rest.sandbox.na.zuora.com
https://rest.apisandbox.zuora.com
https://rest.na.zuora.com
https://rest.zuora.com
https://rest.test.eu.zuora.com
https://rest.sandbox.eu.zuora.com
https://rest.eu.zuora.com

Request headers

Name	Type	Required	Description
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/json"
`Content-Encoding`	String	No	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.
`Zuora-Track-Id`	String	No	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 (`'`).
`Authorization`	String	No	The value is in the `Bearer {token}` format where {token} is a valid OAuth token generated by calling Create an OAuth token.
`Idempotency-Key`	String	No	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.
`Zuora-Entity-Ids`	String	No	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	No	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.
`Accept-Encoding`	String	No	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.

Request body fields

Name	Type	Required	Description
`batches[]`	Array	No	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 `Batchn` 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.
`billRunFilters[]`	Array	No	The target account or subscriptions for this bill run. You can only specify either this field or the `batches` field.
`billRunFilters[].accountId`	String	Yes	The target account of the bill run. If multiple subscriptions are specified, the account ID must be the same.
`billRunFilters[].filterType`	String	Yes	To create bill runs at account level or subscription level. Possible values: `"Account"` `"Subscription"`
`billRunFilters[].subscriptionId`	String	No	The target subscripiton ID of the account. If you set the `filterType` field to `Subscription`, you must specify the `subscriptionId` field.
`invoiceDate`	String	No	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.
`billCycleDay`	String	No	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
`chargeTypeToExclude[]`	Array	No	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.
`autoRenewal`	Boolean	No	Whether to automatically renew auto-renew subscriptions that are up for renewal. Default value: false
`targetDate`	String	No	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.
`autoEmail`	Boolean	No	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. Default value: false
`name`	String	No	The name of the bill run.
`organizationLabels[]`	Array	No	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.
`organizationLabels[].organizationName`	String	No	The organization name.
`organizationLabels[].organizationId`	String	No	The organization ID.
`billRunType`	String	No	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`
`autoPost`	Boolean	No	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. Default value: false
`noEmailForZeroAmountInvoice`	Boolean	No	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. Default value: false

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.