# Bill Runs

This section contains the CRUD bill run operations, including: 

  - [CRUD: Create a bill run](https://developer.zuora.com/api-references/older-api/operation/Object_POSTBillRun/)
  - [CRUD: Retrieve a bill run](https://developer.zuora.com/api-references/older-api/operation/Object_GETBillRun/)
  - [CRUD: Post or cancel a bill run](https://developer.zuora.com/api-references/older-api/operation/Object_PUTBillRun/)
  - [CRUD: Delete a bill run](https://developer.zuora.com/api-references/older-api/operation/Object_DELETEBillRun/)


## CRUD: Create a bill run

 - [POST /v1/object/bill-run](https://developer.zuora.com/v1-api-reference/older-api/bill-runs/object_postbillrun.md): Creates an ad hoc bill run or a single account or multiple customer accounts.

When creating a single account ad hoc bill run, your request must include AccountId and must not include Batch or BillCycleDay. 

If more than 500 bill runs created by using this operation are in Pending status, no more bill runs can be created by using this operation.

## CRUD: Retrieve a bill run

 - [GET /v1/object/bill-run/{id}](https://developer.zuora.com/v1-api-reference/older-api/bill-runs/object_getbillrun.md): Retrieves information about a bill run. 


Business operations depending on the completion of the bill run will not be available while the bill run query returns PostInProgress. Upon completion of the bill run, a query will return Posted.

## CRUD: Post or cancel a bill run

 - [PUT /v1/object/bill-run/{id}](https://developer.zuora.com/v1-api-reference/older-api/bill-runs/object_putbillrun.md): Posts or cancels a bill run. 


### Post a Bill Run

Posting a bill run is an asynchronous operation. To post a bill run, the current bill run must have a status of Completed.

When a bill run is posted, its status is changed to PostInProgress. Once all invoices for this bill run are posted then its status is changed to Posted.   

When you post a bill run and query the status of a bill run, you will get one of the following results PostInProgress, Completed, or Posted. If all invoices in the bill run are posted, then the status of the bill run is Posted. If one or more invoices fail to post, the status will change back to Completed and you will need to post the bill run again.

### Cancel a Bill Run

Canceling a bill run is an asynchronous operation. When canceling a bill run, the logic is the same as when using the UI to cancel a bill run. You need to provide the BillRunId, and set the Status to Canceled. 

When canceling a bill run, consider the following:

* Canceling a bill run with a Completed status.
  * Only the current bill run will be canceled.
* Canceling a bill run with a Pending status.
  * When canceling an Ad-hoc bill run, only the current bill run will be canceled.
  * When canceling a scheduled bill, all scheduled bill runs will be canceled.

The Cancel operation may not be successful. Its success depends on its current business validation. Only a bill run that has no posted invoices can be canceled. If any posted invoices belong to the bill run then an invalid value exception will be thrown with the message, "The Bill Run cannot be Cancelled, There are Posted invoices."

## CRUD: Delete a bill run

 - [DELETE /v1/object/bill-run/{id}](https://developer.zuora.com/v1-api-reference/older-api/bill-runs/object_deletebillrun.md): Deletes a bill run. 

When deleting a bill run, the logic is the same as when using the UI to delete a bill run. The only required parameter is BillRunId. The Status for the bill run must be Canceled in order to delete a bill run.