Create a bill run

POST

/v1/bill-runs

POST

/v1/bill-runs

from zuora import ZuoraClient, BillRunFilterRequestType, Condition
import datetime
client = ZuoraClient(
    token="YOUR_TOKEN_HERE",
)
client.bill_run.post_create_bill_run(
    auto_email=False,
    auto_post=True,
    auto_renewal=False,
    bill_run_filters=[
        BillRunFilterRequestType(
            account_id="string",
            filter_type="FilterCondition",
            condition=Condition(
                conditions=[
                    Condition(
                        field="BillCycleDay",
                        operator="neq",
                        value="{{AsRunDay}}",
                    )
                ],
                relation="and",
            ),
            object_type="Account",
        )
    ],
    bill_run_type="Regular",
    charge_type_to_exclude=[],
    invoice_date=datetime.date.fromisoformat("2026-01-01"),
    name="",
    no_email_for_zero_amount_invoice=False,
    target_date=datetime.date.fromisoformat("2026-01-01"),
)

{
  "autoEmail": false,
  "autoPost": false,
  "autoRenewal": false,
  "batches": [
    "AllBatches"
  ],
  "billCycleDay": "AllBillCycleDays",
  "billRunFilters": [
    {
      "filterType": "FilterCondition",
      "condition": {
        "conditions": [
          {
            "conditions": [],
            "field": "billRunEffectiveDate__c",
            "operator": "lte",
            "relation": null,
            "value": "{{InvoiceDate}}"
          }
        ],
        "relation": "and"
      },
      "objectType": "Subscription",
      "invoiceScheduleId": null,
      "invoiceScheduleItemId": null
    }
  ],
  "billRunNumber": "BR-00007954",
  "createdById": "e1187a1f28c8487ca6b40c40ffb10853",
  "createdDate": "2026-01-14 04:31:20",
  "includeSubscriptions": true,
  "includeOrderLineItems": true,
  "id": "8a90ff929bb9d7c0019bbc7d34ec2c5f",
  "invoiceDate": "2025-06-01",
  "name": "Bill subscriptions matched the dynamic invoice date 2025-06-01",
  "noEmailForZeroAmountInvoice": false,
  "status": "Pending",
  "targetDate": "2025-06-01",
  "updatedById": "e1187a1f28c8487ca6b40c40ffb10853",
  "updatedDate": "2026-01-14 04:31:20",
  "success": true
}

Creates an ad-hoc bill run or a scheduled bill run. Support the following:

Create ad-hoc or scheduled bill runs by batch
Create ad-hoc or scheduled bill runs by account
Create a bill run by subscription
Create ad-hoc or scheduled bill runs by custom filter combining the Account, Subscription, and Rate Plan objects.

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

Notes

When using this operation to create bill runs, keep the following notes in mind:

When creating bill runs by batch, you must specify the batches field and do not specify billRunFilters field. When creating bill runs by account, subscription, or custom filter, you must specify the billRunFilters field and do not specify the batches field.
When creating bill runs by account, only one single account is allowed. All subscription under the account are picked up.
When creating a bill run by subscription, 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.
When you use the in operator in an Account, Subscription, or Charge filter in billRunFilters, you can specify a maximum of 500 values in the list. If any in condition contains more than 500 values, the request fails validation, an error is returned, and the Bill Run is not started. This limit applies only to the in operator in Advanced Filters and does not limit the total number of accounts, subscriptions, or charges that the Bill Run can process.

Authentication

AuthorizationBearer

Use Bearer {{token}} in the Authorization header for authentication.

Headers

Content-EncodingstringOptional

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-Org-IdsstringOptional

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. This header is important in Multi-Org (MO) setups because it defines the organization context under which the API should operate—mainly used for read access or data visibility filtering. If the header is not set, the operation is performed in scope of the user’s accessible orgs.

Request

This endpoint expects an object.

autoEmailbooleanOptionalDefaults to 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.

autoPostbooleanOptionalDefaults to 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.

autoRenewalbooleanOptionalDefaults to false

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

batcheslist of stringsOptional

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.

billCycleDaystringOptional

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

billRunFilterslist of objectsOptional

The target account, subscriptions, invoice schedule, or a combination of objects for this bill run. You can only specify either this field or the batches field.

billRunTypestringOptional

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

chargeTypeToExcludelist of enumsOptional

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.

Allowed values:

includeSubscriptionsbooleanOptionalDefaults to true

Indicates whether to bill subscriptions in the bill run.

includeOrderLineItemsbooleanOptionalDefaults to true

Indicates whether to bill order line items in the bill run.

invoiceDatedateOptional

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

invoiceDateMonthOffsetintegerOptional

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

invoiceDateDayOfMonthintegerOptional1-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

namestringOptional

The name of the bill run.

noEmailForZeroAmountInvoicebooleanOptionalDefaults to 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.

organizationLabelslist of objectsOptional

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.

scheduleobjectOptional

Container for information about the scheduled bill run.

targetDatedateOptional

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.

targetDateMonthOffsetintegerOptional

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.

targetDateDayOfMonthintegerOptional1-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.

Response headers

Content-EncodingstringOptional

This header is returned if you specify the Accept-Encoding: gzip request header and the response contains over 1000 bytes of data.

Note that only the following MIME types support gzipped responses:

application/json
application/xml
text/html
text/csv
text/plain

RateLimit-LimitstringOptional

The request limit quota for the time window closest to exhaustion. See rate limits for more information.

RateLimit-Remainingdouble

The number of requests remaining in the time window closest to quota exhaustion. See rate limits for more information.

RateLimit-Resetdouble

The number of seconds until the quota resets for the time window closest to quota exhaustion. See rate limits for more information.

Zuora-Request-IdstringOptional

The Zuora internal identifier of the API call. You cannot control the value of this header.

Zuora-Track-IdstringOptional

A custom identifier for tracing the API call. If you specified a tracing identifier in the request headers, Zuora returns the same tracing identifier. Otherwise, Zuora does not set this header.

Concurrency-Limit-TypestringOptional

The type of the concurrency limit, which can be Default, High-volume transactions, or Object Query.

For more information, see Concurrent request limits.

Concurrency-Limit-Limitinteger

The total number of the permitted concurrent requests.

For more information, see Concurrent request limits.

Concurrency-Limit-Remaininginteger

The remaining number of the permitted concurrent requests.

For more information, see Concurrent request limits.

Response

autoEmailbooleanOptional

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

autoPostbooleanOptional

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

autoRenewalbooleanOptional

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

batcheslist of stringsOptional

The batch of accounts for this bill run, this field can not exist with billRunFilters together.

Values: AllBatches or an array of Batchn where n is a number between 1 and 50, for example, Batch7.

billCycleDaystringOptional

The day of the bill cycle, this field is only valid when batches 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

billRunFilterslist of objectsOptional

The target account, subscriptions, invoice schedule, or a combination of objects for this bill run. You can only specify either this field or the batches field.

billRunNumberstringOptional

The number of the bill run.

chargeTypeToExcludelist of enumsOptional

The types of the charges to be excluded from the generation of billing documents.

Allowed values:

createdByIdstringOptional

The ID of the user who created the bill run.

createdDatestringOptional

The date and time when the bill run was created.

includeSubscriptionsbooleanOptionalDefaults to true

Indicates whether to bill subscriptions in the bill run.

includeOrderLineItemsbooleanOptionalDefaults to true

Indicates whether to bill order line items in the bill run.

idstringOptional

The unqie ID of the bill run.

invoiceDatedateOptional

The invoice date for this bill run, only valid for ad-hoc bill runs.

invoiceDateOffsetintegerOptional

The offset compared to bill run execution date, only valid for scheduled bill runs.

invoiceDateMonthOffsetintegerOptional

The month offset of invoice 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. When using the invoiceDateMonthOffset and invoiceDateDayOfMonth fields, do not use the invoiceDateOffset field, and vice versa.

invoiceDateDayOfMonthintegerOptional1-31

namestringOptional

The name of the bill run.

noEmailForZeroAmountInvoicebooleanOptional

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

organizationLabelslist of objectsOptional

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

Note: This field is available only when the Multi-Org feature is enabled.

scheduleobjectOptional

Container for information about the scheduled bill run.

scheduledExecutionTimestringOptional

The scheduled execution time for a bill run.

statusenumOptional

The status of the bill run.

targetDatedateOptional

The target date for this bill run, only valid for ad-hoc bill runs.

targetDateOffsetintegerOptional

The offset compared to bill run execution date, only valid for scheduled bill runs.

targetDateMonthOffsetintegerOptional

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. When using the targetDateMonthOffset and targetDateDayOfMonth fields, do not use the targetDateOffset field, and vice versa.

targetDateDayOfMonthintegerOptional1-31

updatedByIdstringOptional

The ID of the user who last updated the bill run.

updatedDatestringOptional

The date and time when the bill run was last updated.

Errors

4XX

Client Request Error

500

Internal Server Error