---
title: "Create a bill run"
method: POST
path: "/v1/bill-runs"
tags: ["Bill Run"]
---

# Create a bill run

`POST /v1/bill-runs`

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 <a href="https://docs.zuora.com?resourceId=platform-billing-roles" target="_blank">Create Bill Runs billing permission</a>.

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

## Headers

- `Idempotency-Key` string
- `Accept-Encoding` string
- `Content-Encoding` string
- `Zuora-Track-Id` string
- `Zuora-Entity-Ids` string
- `Zuora-Org-Ids` string
- `Zuora-Version` string

## Request body

- POSTCreateBillRunRequestType
  - `autoEmail` boolean — Whether to automatically send emails after Auto-Post is complete. **Note:** To use this field, you must first set the <a href="https://docs.zuora.com/en/zuora-billing/set-up-zuora-billing/billing-settings-configuration/general-billing-settings/define-billing-rules" target="_blank">Support Bill Run Auto-Post?</a> 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 <a href="https://docs.zuora.com/en/zuora-billing/set-up-zuora-billing/billing-settings-configuration/general-billing-settings/define-billing-rules" target="_blank">Support Bill Run Auto-Post?</a> billing rule to **Yes** through the Zuora UI.
  - `autoRenewal` boolean — Whether to automatically renew auto-renew subscriptions that are up for renewal.
  - `batches` string[] — 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 <a href="https://docs.zuora.com/en/entitlements/current-entitlements/performance-booster-elite" target="_blank">Performance Booster Elite</a> 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` BillRunFilterRequestType[] — 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.
    - `accountId` string, required — The target account of the bill run. If multiple subscriptions are specified, the account ID must be the same.
    - `filterType` 'Account' | 'Subscription' | 'FilterCondition', 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 <a href="https://docs.zuora.com/en/zuora-billing/bill-your-customer/bill-runs/automate-billing-document-generation/bill-run-advanced-filter" target="_blank">Bill Run Advanced Filter</a>.
    - `condition` Condition — Container for condition information about the <a href="https://docs.zuora.com?resourceId=billing-bill-run-advanced-filter" target="_blank">Bill Run Advanced Filter</a>.
      - `conditions` Condition[] — 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 <a href="https://docs.zuora.com?resourceId=billing-bill-run-advanced-filter-common-use-cases" target="_blank">Common use cases of Bill Run Advanced Filter</a>.
      - `field` string, nullable — The field name of a single condition that is indicated by the `conditions` field.
      - `operator` 'eq' | 'neq' | 'gt' | 'lt' | 'gte' | 'lte' | 'lk' | 'in' | 'nl' | 'nnl', nullable — 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`) - gte: greater than or equal (`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)
      - `relation` 'and' | 'or', nullable — The relation among the `conditions` fields.
      - `value` string, nullable — The value or list of values to compare against, depending on the operator. For most operators (for example, `eq`, `lt`, `gt`), `value` contains a single literal value or a supported built-in variable. When you use the `in` operator in an Advanced Filter, `value` must be a comma-separated list with no more than 500 values. If more than 500 values are provided, the API returns a validation error and the Bill Run is not started. This limit applies only to the `in` operator and does not affect the total number of accounts or subscriptions a Bill Run can process. When `filterType` is set to `FilterCondition`, you can provide either: - A literal value (for example, `"15"`), or - A built-in variable in the format `{{VariableName}}`. Built-in variables are supported only in the `value` field of date-type conditions and are resolved at runtime: - `{{Today}}`: Current date in `yyyy-MM-dd` format. - `{{BillRunDate}}`: Bill run execution date in `yyyy-MM-dd` format. - `{{TargetDate}}`: Bill run target date in `yyyy-MM-dd` format. - `{{InvoiceDate}}`: Bill run invoice date in `yyyy-MM-dd` format. Example: `"value": "{{BillRunDate}}"` Built‑in variable for Bill Cycle Day: - `{{AsRunDay}}`: - The day of the month from the bill run execution date, formatted for Bill Cycle Day (BCD) matching. - You must use this variable only with the `BillCycleDay` field of the `Account` object.
    - `objectType` 'Account' | 'Subscription' | 'RatePlanCharge' — The target object type of the condition when the `filterType` field is specified as `FilterCondition`. See <a href="https://docs.zuora.com/en/zuora-billing/bill-your-customer/bill-runs/automate-billing-document-generation/bill-run-advanced-filter" target="_blank">Bill Run Advanced Filter</a>.
    - `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` string[] — 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.
  - `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, 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 — 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 — 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` object[] — 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.
    - `organizationId` string — The organization ID.
    - `organizationName` string — The organization name.
  - `schedule` BillRunScheduleRequestType — Container for information about the scheduled bill run.
    - `repeatFrom` string, date, required — The start date of the scheduled bill run.
    - `repeatTo` string, date — The end date of of the scheduled bill run.
    - `repeatType` 'None' | 'Daily' | 'Weekly' | 'Monthly', required — The repeat type of the bill run.
    - `runTime` integer, required — The scheduled run time (hour) of day. **Values:** 0 - 23
    - `weeklyOnDay` string[] — The repeat day in a week. This field is required if you set `repeatType` field to `Weekly`.
    - `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, 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 — 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`

OK

- GetBillRunResponseType
  - `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` string[] — The batch of accounts for this bill run, this field can not exist with `billRunFilters` together. **Values:** `AllBatches` or an array of `Batch`*n* 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
  - `billRunFilters` BillRunFilterResponseType[] — 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.
    - `accountId` string, nullable — The target account of the bill run.
    - `filterType` 'Account' | 'Subscription' | 'InvoiceSchedule' | 'FilterCondition' — 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. - `InvoiceSchedule`: Create a scheduled bill run, you must specify the schedule field. See <a href="https://docs.zuora.com/en/zuora-billing/bill-your-customer/bill-runs/automate-billing-document-generation/manage-scheduled-bill-runs" target="_blank">Manage scheduled bill runs</a>. - `FilterCondition`: Create bill runs by custom filter combining the Account, Subscription, and Rate Plan objects, you must specify the `condition` and `objectType` fields. See <a href="https://docs.zuora.com/en/zuora-billing/bill-your-customer/bill-runs/automate-billing-document-generation/bill-run-advanced-filter" target="_blank">Bill Run Advanced Filter</a>.
    - `condition` Condition — Container for condition information about the <a href="https://docs.zuora.com?resourceId=billing-bill-run-advanced-filter" target="_blank">Bill Run Advanced Filter</a>.
      - `conditions` Condition[] — 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 <a href="https://docs.zuora.com?resourceId=billing-bill-run-advanced-filter-common-use-cases" target="_blank">Common use cases of Bill Run Advanced Filter</a>.
      - `field` string, nullable — The field name of a single condition that is indicated by the `conditions` field.
      - `operator` 'eq' | 'neq' | 'gt' | 'lt' | 'gte' | 'lte' | 'lk' | 'in' | 'nl' | 'nnl', nullable — 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`) - gte: greater than or equal (`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)
      - `relation` 'and' | 'or', nullable — The relation among the `conditions` fields.
      - `value` string, nullable — The value or list of values to compare against, depending on the operator. For most operators (for example, `eq`, `lt`, `gt`), `value` contains a single literal value or a supported built-in variable. When you use the `in` operator in an Advanced Filter, `value` must be a comma-separated list with no more than 500 values. If more than 500 values are provided, the API returns a validation error and the Bill Run is not started. This limit applies only to the `in` operator and does not affect the total number of accounts or subscriptions a Bill Run can process. When `filterType` is set to `FilterCondition`, you can provide either: - A literal value (for example, `"15"`), or - A built-in variable in the format `{{VariableName}}`. Built-in variables are supported only in the `value` field of date-type conditions and are resolved at runtime: - `{{Today}}`: Current date in `yyyy-MM-dd` format. - `{{BillRunDate}}`: Bill run execution date in `yyyy-MM-dd` format. - `{{TargetDate}}`: Bill run target date in `yyyy-MM-dd` format. - `{{InvoiceDate}}`: Bill run invoice date in `yyyy-MM-dd` format. Example: `"value": "{{BillRunDate}}"` Built‑in variable for Bill Cycle Day: - `{{AsRunDay}}`: - The day of the month from the bill run execution date, formatted for Bill Cycle Day (BCD) matching. - You must use this variable only with the `BillCycleDay` field of the `Account` object.
    - `objectType` 'Account' | 'Subscription' | 'RatePlanCharge' — The target object type of the condition when the `filterType` field is specified as `FilterCondition`. See <a href="https://docs.zuora.com/en/zuora-billing/bill-your-customer/bill-runs/automate-billing-document-generation/bill-run-advanced-filter" target="_blank">Bill Run Advanced Filter</a>.
    - `subscriptionId` string, nullable — The target subscripiton ID of the account.
  - `billRunNumber` string — The number of the bill run.
  - `chargeTypeToExclude` string[], nullable — The types of the charges to be excluded from the generation of billing documents.
  - `createdById` string — The ID of the user who created the bill run.
  - `createdDate` string — The date and time when the bill run was created.
  - `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.
  - `invoiceDate` string, date — The invoice date for this bill run, only valid for ad-hoc bill runs.
  - `invoiceDateOffset` integer, nullable — The offset compared to bill run execution date, only valid for scheduled bill runs.
  - `invoiceDateMonthOffset` integer, nullable — 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, nullable — 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.
  - `noEmailForZeroAmountInvoice` boolean — Whether to suppress emails for invoices with zero total amount generated in this bill run after the bill run is complete.
  - `organizationLabels` object[] — The organization(s) that the run is created for. Note: This field is available only when the Multi-Org feature is enabled.
    - `organizationId` string — The organization ID.
    - `organizationName` string — The organization name.
  - `schedule` BillRunScheduleResponseType — Container for information about the scheduled bill run.
    - `repeatFrom` string, date — The start date of the scheduled bill run.
    - `repeatTo` string, date — The end date of of the scheduled bill run.
    - `repeatType` 'None' | 'Daily' | 'Weekly' | 'Monthly' — The repeat type of the bill run.
    - `runTime` integer — The scheduled run time (hour) of day. **Values:** 0 - 23
    - `weeklyOnDay` string[] — The repeat day in a week.
    - `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, nullable — The scheduled execution time for a bill run.
  - `status` 'Pending' | 'Processing' | 'Completed' | 'Error' | 'Canceled' | 'Posted' | 'PostInProgress' | 'CancelInProgress' | 'RemoveInProgress' | 'Paused' — The status of the bill run.
  - `targetDate` string, date — The target date for this bill run, only valid for ad-hoc bill runs.
  - `targetDateOffset` integer, nullable — The offset compared to bill run execution date, only valid for scheduled bill runs.
  - `targetDateMonthOffset` integer, nullable — 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, nullable — 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.
  - `updatedDate` string — The date and time when the bill run was last updated.

## Other responses

- `500` — Internal Server Error
- `4XX` — Request Errors

---

[API](https://skmtc.dev/zuora/apis/api-reference.md) · [All operations](https://skmtc.dev/zuora/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/zuora/api-reference/revisions/d11e237f3e54/schema)