# Bill Run

Use the Bill Run call to create ad hoc bill runs and Post, Cancel, Query, and Delete bill runs. 

For more information about bill runs, see <a href="https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/G_Bill_Runs" target="_blank">Bill runs</a>.


## Create a bill run

 - [POST /v1/bill-runs](https://developer.zuora.com/v1-api-reference/api/bill-run/post_createbillrun.md): 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.

## Delete a bill run

 - [DELETE /v1/bill-runs/{billRunId}](https://developer.zuora.com/v1-api-reference/api/bill-run/delete_deletebillrun.md): Deletes a bill run. You can only delete bill runs in Canceled or Error status.

## Retrieve a bill run

 - [GET /v1/bill-runs/{billRunId}](https://developer.zuora.com/v1-api-reference/api/bill-run/get_billrun.md): Retrieves the information about a specific bill run.

## Cancel a bill run

 - [PUT /v1/bill-runs/{billRunId}/cancel](https://developer.zuora.com/v1-api-reference/api/bill-run/put_cancelbillrun.md): Cancels a bill run in Draft status.

When cancelling a scheduled bill run, keep the following information in mind:
- If you set cancelOnce to true, only the current bill run is cancelled. The other future scheduled bill runs will be automatically executed based on the schedule.
- If you set cancelOnce to false, all future recurring bill runs are cancelled.

## Post a bill run

 - [PUT /v1/bill-runs/{billRunId}/post](https://developer.zuora.com/v1-api-reference/api/bill-run/put_postbillrun.md): 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.

## Email billing documents generated from a bill run

 - [POST /v1/bill-runs/{billRunKey}/emails](https://developer.zuora.com/v1-api-reference/api/bill-run/post_emailbillingdocumentsfrombillrun.md): Manually emails all the billing documents that are generated from a specified bill run to your customers. 


Bill runs can generate invoices and credit memos based on your invoice and credit memo generation rule. Credit memos are only available if you have the Invoice Settlement feature enabled.


Using this API operation, the billing documents are sent to the email addresses specified in the To Email field of the email templates. The email template used for each billing document is set in the Delivery Options panel of the Edit notification dialog from the Zuora UI. See Edit Email Templates for more information about how to edit the To Email field in the email template.





### Notes
  - Even though no field is required in the Request body, you still need to specify {} in the request. Otherwise, an error will be returned.


  - You can only email posted billing documents.


  - You must activate the following notifications before emailing invoices and credit memos:
    - Manual Email For Invoice | Manual Email For Invoice 
    - Email Credit Memo | Manually email Credit Memo


  - To include the invoice PDF in the email, select the Include Invoice PDF check box in the Edit notification dialog from the Zuora UI. To include the credit memo PDF in the email, select the Include Credit Memo PDF check box in the Edit notification dialog from the Zuora UI. See Create and Edit Notifications for more information.



  - Zuora sends the email messages based on the email template you set. You can set the email template to use in the Delivery Options panel of the Edit notification dialog from the Zuora UI. By default, the following templates are used for billing documents:
    - Invoices: Invoice Posted Default Email Template
    - Credit memos: Manual Email for Credit Memo Default Template  

    See Create and Edit Email Templates for more information.