# Create a bill run

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.

Endpoint: POST /v1/bill-runs
Version: 2026-02-20
Security: bearerAuth

## Header parameters:

  - `Idempotency-Key` (string)
    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.

  - `Zuora-Track-Id` (string)
    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 should not 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. 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.

  - `Zuora-Version` (string)
    The minor API version.

For a list of available minor versions, see API upgrades.

## Request fields (application/json):

  - `autoEmail` (boolean)
    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)
    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)
    Whether to automatically renew auto-renew subscriptions that are up for renewal.

  - `batches` (array)
    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.

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

  - `billRunFilters` (array)
    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.
    Example: [{"accountId":"2c9081a03c63c94c013c66688a2c00bf","filterType":"Subscription","subscriptionId":"402882297e387c51017e38a245c313db"}]

  - `billRunFilters.accountId` (string, required)
    The target account of the bill run. 

If multiple subscriptions are specified, the account ID must be the same.

  - `billRunFilters.filterType` (string, required)
    To create bill runs based on the selected filter type:
  - Account: Create bill runs by account. 
  - Subscription: Create bill runs by subscription, you must specify the subscriptionId field.
  - FilterCondition: Create bill runs by custom filter combining the Account, Subscription, and Rate Plan objects, you must specify the condition and objectType fields. See Bill Run Advanced Filter.
    Enum: "Account", "Subscription", "FilterCondition"

  - `billRunFilters.condition` (object)
    Container for condition information about the Bill Run Advanced Filter.

  - `billRunFilters.condition.conditions` (array)
    Multiple conditions fields are combined by the relation fields. These conditions fields form a custom filter.
Each conditions field is a formula combined by the field, operator, and value fields. See Common use cases of Bill Run Advanced Filter.

  - `billRunFilters.condition.field` (string)
    The field name of a single condition that is indicated by the conditions field.

  - `billRunFilters.condition.operator` (string)
    The operator of a single condition that is indicated by the conditions field.  The operator is added between the field and value fields.
- eq: equal (field = value)
- neq: not equal (field != value) 
- gt: greater than (field > value) 
- lt: less than (field = value)
- lte: less than or equal (field <= value)
- lk: like (field like value) 
- in: in (field in value, the values are separated by comma)
- nl: null (field is null)
- nnl: not null (field is not null)
    Enum: "eq", "neq", "gt", "lt", "gte", "lte", "lk", "in", "nl", "nnl"

  - `billRunFilters.condition.relation` (string)
    The relation among the conditions fields.
    Enum: "and", "or"

  - `billRunFilters.condition.value` (string)
    The value of a single condition that is indicated by the conditions field.

  - `billRunFilters.objectType` (string)
    The target object type of the condition when the filterType field is specified as FilterCondition. See Bill Run Advanced Filter.
    Enum: "Account", "Subscription", "RatePlanCharge"

  - `billRunFilters.subscriptionId` (string)
    The target subscripiton ID of the account. 

If you set the filterType field to Subscription, you must specify the subscriptionId 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)
    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.
    Enum: "OneTime", "Recurring", "Usage"

  - `includeSubscriptions` (boolean)
    Indicates whether to bill subscriptions in the bill run.

  - `includeOrderLineItems` (boolean)
    Indicates whether to bill order line items in the bill run.

  - `invoiceDate` (string)
    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
    Example: "2020-02-01"

  - `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)
    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.
    Example: "test"

  - `noEmailForZeroAmountInvoice` (boolean)
    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.

  - `organizationLabels` (array)
    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.organizationId` (string)
    The organization ID.

  - `organizationLabels.organizationName` (string)
    The organization name.

  - `schedule` (object)
    Container for information about the scheduled bill run.

  - `schedule.repeatFrom` (string, required)
    The start date of the scheduled bill run.

  - `schedule.repeatTo` (string)
    The end date of of the scheduled bill run.

  - `schedule.repeatType` (string, required)
    The repeat type of the bill run.
    Enum: "None", "Daily", "Weekly", "Monthly"

  - `schedule.runTime` (integer, required)
    The scheduled run time (hour) of day.

Values: 0 - 23

  - `schedule.weeklyOnDay` (array)
    The repeat day in a week. 

This field is required if you set repeatType field to Weekly.
    Enum: "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"

  - `schedule.monthlyOnEndOfMonth` (boolean)
    Whether to schedule monthly bill run on the end of month or the specific day of month.


Note: This field is available only when the repeatType field is set to Monthly and the repeatFrom field is set to the end of month.
  
For example:
  - When repeatFrom = 2024-04-30 and monthlyOnEndOfMonth = true, next bill run will be scheduled on 2024-05-31.
  - When repeatFrom = 2024-04-30 and monthlyOnEndOfMonth = false, next bill run will be scheduled on 2024-05-30.

  - `targetDate` (string)
    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.
    Example: "2020-02-01"

  - `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)
    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 200 fields (application/json):

  - `autoEmail` (boolean)
    Whether to automatically send emails after Auto-Post is complete.

  - `autoPost` (boolean)
    Whether to automatically post the bill run after the bill run is created.

  - `autoRenewal` (boolean)
    Whether to automatically renew auto-renew subscriptions that are up for renewal.

  - `batches` (array)
    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.

  - `billCycleDay` (string)
    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
    Example: 1

  - `billRunFilters` (array)
    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.
    Example: [{"accountId":"2c9081a03c63c94c013c66688a2c00bf","filterType":"Subscription","subscriptionId":"402882297e387c51017e38a245c313db"}]

  - `billRunFilters.accountId` (string)
    The target account of the bill run.

  - `billRunFilters.filterType` (string)
    The bill runs are created based on the selected filter type:
  - Account: Create a bill run at account level.
  - Subscription: Create a bill run at subscription level, you must specify the subscriptionId field.
  - InvoiceSchedule: Create a scheduled bill run, you must specify the schedule field. See Manage scheduled bill runs.
  - FilterCondition: Create a bill run based on a custom filter, you must specify the condition and objectType fields. See Bill Run Advanced Filter.
    Enum: "Account", "Subscription", "InvoiceSchedule", "FilterCondition"

  - `billRunFilters.condition` (object)
    Container for condition information about the Bill Run Advanced Filter.

  - `billRunFilters.condition.conditions` (array)
    Multiple conditions fields are combined by the relation fields. These conditions fields form a custom filter.
Each conditions field is a formula combined by the field, operator, and value fields. See Common use cases of Bill Run Advanced Filter.

  - `billRunFilters.condition.field` (string)
    The field name of a single condition that is indicated by the conditions field.

  - `billRunFilters.condition.operator` (string)
    The operator of a single condition that is indicated by the conditions field.  The operator is added between the field and value fields.
- eq: equal (field = value)
- neq: not equal (field != value) 
- gt: greater than (field > value) 
- lt: less than (field = value)
- lte: less than or equal (field <= value)
- lk: like (field like value) 
- in: in (field in value, the values are separated by comma)
- nl: null (field is null)
- nnl: not null (field is not null)
    Enum: "eq", "neq", "gt", "lt", "gte", "lte", "lk", "in", "nl", "nnl"

  - `billRunFilters.condition.relation` (string)
    The relation among the conditions fields.
    Enum: "and", "or"

  - `billRunFilters.condition.value` (string)
    The value of a single condition that is indicated by the conditions field.

  - `billRunFilters.objectType` (string)
    The target object type of the condition when the filterType field is specified as FilterCondition. See Bill Run Advanced Filter.
    Enum: "Account", "Subscription", "RatePlanCharge"

  - `billRunFilters.subscriptionId` (string)
    The target subscripiton ID of the account.

  - `billRunNumber` (string)
    The number of the bill run.
    Example: "BR-00000016"

  - `chargeTypeToExclude` (array)
    The types of the charges to be excluded from the generation of billing documents.
    Enum: "OneTime", "Recurring", "Usage"

  - `createdById` (string)
    The ID of the user who created the bill run.
    Example: "ff808081298c6e5401298c7274a40005"

  - `createdDate` (string)
    The date and time when the bill run was created.
    Example: "2022-01-24 19:58:27"

  - `includeSubscriptions` (boolean)
    Indicates whether to bill subscriptions in the bill run.

  - `includeOrderLineItems` (boolean)
    Indicates whether to bill order line items in the bill run.

  - `id` (string)
    The unqie ID of the bill run.
    Example: "2c9890077e8a8490017e8bf3a5171a43"

  - `invoiceDate` (string)
    The invoice date for this bill run, only valid for ad-hoc bill runs.
    Example: "2020-02-01"

  - `invoiceDateOffset` (integer)
    The offset compared to bill run execution date, only valid for scheduled bill runs.

  - `invoiceDateMonthOffset` (integer)
    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.

  - `invoiceDateDayOfMonth` (integer)
    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. 


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.

  - `name` (string)
    The name of the bill run.
    Example: "test"

  - `noEmailForZeroAmountInvoice` (boolean)
    Whether to suppress emails for invoices with zero total amount generated in this bill run after the bill run is complete.

  - `organizationLabels` (array)
    The organization(s) that the run is created for. 

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

  - `organizationLabels.organizationId` (string)
    The organization ID.

  - `organizationLabels.organizationName` (string)
    The organization name.

  - `schedule` (object)
    Container for information about the scheduled bill run.

  - `schedule.repeatFrom` (string)
    The start date of the scheduled bill run.

  - `schedule.repeatTo` (string)
    The end date of of the scheduled bill run.

  - `schedule.repeatType` (string)
    The repeat type of the bill run.
    Enum: "None", "Daily", "Weekly", "Monthly"

  - `schedule.runTime` (integer)
    The scheduled run time (hour) of day.

Values: 0 - 23

  - `schedule.weeklyOnDay` (array)
    The repeat day in a week.
    Enum: "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"

  - `schedule.monthlyOnEndOfMonth` (boolean)
    Whether to schedule monthly bill run on the end of month or the specific day of month.


Note: This field is available only when the repeatType field is set to Monthly and the repeatFrom field is set to the end of month.
  
For example:
- When repeatFrom = 2024-04-30 and monthlyOnEndOfMonth = true, next bill run will be scheduled on 2024-05-31.
- When repeatFrom = 2024-04-30 and monthlyOnEndOfMonth = false, next bill run will be scheduled on 2024-05-30.

  - `scheduledExecutionTime` (string)
    The scheduled execution time for a bill run.

  - `status` (string)
    The status of the bill run.
    Enum: "Pending", "Processing", "Completed", "Error", "Canceled", "Posted", "PostInProgress", "CancelInProgress", "RemoveInProgress", "Paused"

  - `targetDate` (string)
    The target date for this bill run, only valid for ad-hoc bill runs.
    Example: "2020-02-01"

  - `targetDateOffset` (integer)
    The offset compared to bill run execution date, only valid for scheduled bill runs.

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

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

  - `updatedById` (string)
    The ID of the user who last updated the bill run.
    Example: "ff808081298c6e5401298c7274a40005"

  - `updatedDate` (string)
    The date and time when the bill run was last updated.
    Example: "2022-01-24 19:58:27"

## Response 500 fields (application/json):

  - `reasons` (array)
    Example: [{"code":"ObjectNotFound","message":"Notification definition with id 6e569e1e05f040eda51a927b140c0ac1 does not exist"}]

  - `reasons.code` (string)
    The error code of response.

  - `reasons.message` (string)
    The detail information of the error response

## Response 4XX fields (application/json):

  - `processId` (string)
    The ID of the process that handles the operation.

  - `reasons` (array)
    The container of the error code and message. This field is available only if the success field is false.

  - `reasons.code` (string)
    The error code of response.

  - `reasons.message` (string)
    The detail information of the error response

  - `requestId` (string)
    Unique identifier of the request.

  - `success` (boolean)
    Indicates whether the call succeeded.