# Post a bill run

Posts a bill run asynchronously. To post a bill run, the current bill run must be in `Completed` status.
When a bill run is being posted, its status is changed to `PostInProgress`. After all invoices for this bill run are posted, its status is changed to `Posted`.

Endpoint: PUT /v1/bill-runs/{billRunId}/post
Version: 2026-11-13
Security: bearerAuth

## Security:

  - `bearerAuth` (unknown)
    http bearer

## Path parameters:

  - `billRunId` (string, required)
    The unique ID of a bill run.

## Header parameters:

  - `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](https://docs.zuora.com?resourceId=platform-multi-entity-overview) 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](https://developer.zuora.com/v1-api-reference/api-upgrades/).

## Request fields (application/json):

  - `invoiceDate` (string, required)
    The date that appears on the invoice being created, in `yyyy-mm-dd` format.
The value cannot fall in a closed accounting period.

## Response 200:

  - `200` (unknown)
    OK

## 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 `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` (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.

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

  - `billRunFilters.filterType` (string)
    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 Manage scheduled bill runs.
- `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", "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`)
- 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)
    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 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.

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

  - `chargeTypeToExclude` (array)
    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)
    The invoice date for this bill run, only valid for ad-hoc bill runs.

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

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

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

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

  - `updatedDate` (string)
    The date and time when the bill run was last updated.

## Response 200 headers (application/json):

  - `Content-Encoding` (string)
    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-Limit` (string)
    The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/rate-limits/) for more information.

  - `RateLimit-Remaining` (number)
    The number of requests remaining in the time window closest to quota exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/rate-limits/) for more information.

  - `RateLimit-Reset` (number)
    The number of seconds until the quota resets for the time window closest to quota exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/rate-limits/) for more information.

  - `Zuora-Request-Id` (string)
    The Zuora internal identifier of the API call. You cannot control the value of this header.

  - `Zuora-Track-Id` (string)
    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-Type` (string)
    The type of the concurrency limit, which can be `Default`, `High-volume transactions`, or `Object Query`.
For more information, see [Concurrent request limits](https://developer.zuora.com/docs/guides/rate-limits/#concurrent-request-limits).

  - `Concurrency-Limit-Limit` (integer)
    The total number of the permitted concurrent requests.
For more information, see [Concurrent request limits](https://developer.zuora.com/docs/guides/rate-limits/#concurrent-request-limits).

  - `Concurrency-Limit-Remaining` (integer)
    The remaining number of the permitted concurrent requests.
For more information, see [Concurrent request limits](https://developer.zuora.com/docs/guides/rate-limits/#concurrent-request-limits).

## Response 500:

  - `500` (unknown)
    Internal Server Error

## Response 500 fields (application/json):

  - `reasons` (array)

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

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

## Response 500 headers (application/json):

  - `Content-Encoding` (string)
    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-Limit` (string)
    The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/rate-limits/) for more information.

  - `RateLimit-Remaining` (number)
    The number of requests remaining in the time window closest to quota exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/rate-limits/) for more information.

  - `RateLimit-Reset` (number)
    The number of seconds until the quota resets for the time window closest to quota exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/rate-limits/) for more information.

  - `Zuora-Request-Id` (string)
    The Zuora internal identifier of the API call. 
You cannot control the value of this header.

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

## Response 4XX:

  - `4XX` (unknown)
    Request Errors

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

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

  - `Content-Encoding` (string)
    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-Limit` (string)
    The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/rate-limits/) for more information.

  - `RateLimit-Remaining` (number)
    The number of requests remaining in the time window closest to quota exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/rate-limits/) for more information.

  - `RateLimit-Reset` (number)
    The number of seconds until the quota resets for the time window closest to quota exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/rate-limits/) for more information.

  - `Zuora-Request-Id` (string)
    The Zuora internal identifier of the API call. 
You cannot control the value of this header.

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

## Response 500 examples:

  - `response` (unknown)

## Response 4XX examples:

  - `response` (unknown)

