BillRun Use Cases

Last updated
Save as PDF

The BillRun object allows you to Create ad hoc bill runs and Post, Cancel, Query, and Delete bill runs.

This feature is in Limited Availability. If you want to have access to the feature, submit a request at Zuora Global Support.

You must be on WSDL version 63.0 or higher to use this feature. See The Zuora WSDL for information about downloading the current version.

Create an Ad Hoc Bill Run

An ad hoc bill run is one that you create manually for a specific (and usually one-time) purpose.

Create a Single Account Ad Hoc Bill Run

When creating a single account ad hoc bill run, your request must include AccountId and must not include Batch or BillCycleDay. If this requirement is not met, you will get a ValidateException error message.

Name	Required?	Value
AccountId	required	The account ID for this bill run
InvoiceDate	required	Invoice date for this bill run
TargetDate	required	The target date for this bill run
AutoEmail	optional	Flag to determine whether email is sent or not by this bill run
AutoRenewal	optional	Flag to determine auto renew subscription or not by this bill run
ChargeTypeToExclude	optional	Charge type or types to be excluded, separated with comma
NoEmailForZeroAmountInvoice	optional	Flag to determine suppression of email for invoices with zero total or not for this bill run (Do not email invoices with 0 Invoice Total)

Example Request

<soapenv:Body>
  <ns1:create xmlns:ns1="http://api.zuora.com/">
     <ns2:zObjects xsi:type="ns1:BillRun">
       <ns1:AccountId>8a8ae4b122561fc00122562fbc3d0002</ns1:AccountId>
       <ns1:AutoEmail>false</ns1:AutoEmail>
       <ns1:AutoPost>false</ns1:AutoPost>     
       <ns1:AutoRenewal>false</ns1:AutoRenewal>
       <ns1:ChargeTypeToExclued>OneTime,Usage</ns1:ChargeTypeToExclued>
       <ns1:InvoiceDate>2011-07-07</ns1:InvoiceDate>
       <ns1:TargetDate>2011-07-07</ns1:TargetDate>
       <ns1:NoEmailForZeroAmountInvoice>false</ns1:NoEmailForZeroAmountInvoice>
     </ns2:zObjects>
  </ns1:create>
</soapenv:Body>

Create a Batch (Multiple Customer Accounts) Ad Hoc Bill Run

If your request does not include AccountId, a bill run for multiple accounts will be created.

Name	Required?	Value
Batch	optional	The batch of accounts for this bill run
BillCycleDay	optional	The day of the bill cycle
InvoiceDate	required	Invoice date for this bill run
TargetDate	required	The target date for this bill run
AutoEmail	optional	Flag to determine whether email is sent or not by this bill run
AutoRenewal	optional	Flag to determine auto renew subscription or not by this bill run
ChargeTypeToExclude	optional	Charge type or types to be excluded, separated with comma
NoEmailForZeroAmountInvoice	optional	Flag to determine suppression of email for invoices with zero total or not for this bill run (Do not email invoices with 0 Invoice Total)

Even though many fields are optional and have a default value, Zuora suggests that you include all required and optional fields and specific values for each field when you use the create() call for BillRun. For example, if you don't give a value for Batch, AllBatches will be returned. This is not recommended.

Example Request

<soapenv:Body>
  <ns1:create xmlns:ns1="http://api.zuora.com/">    
     <ns2:zObjects xsi:type="ns1:BillRun">
       <ns1:AutoEmail>false</ns1:AutoEmail>
       <ns1:AutoPost>false</ns1:AutoPost>     
       <ns1:AutoRenewal>false</ns1:AutoRenewal>
       <ns1:Batch>Batch1</ns1:Batch>
       <ns1:BillCycleDay>2</ns1:BillCycleDay>
       <ns1:ChargeTypeToExclued>OneTime,Usage</ns1:ChargeTypeToExclued>
       <ns1:InvoiceDate>2011-07-07</ns1:InvoiceDate>
       <ns1:TargetDate>2011-07-07</ns1:TargetDate>
       <ns1:NoEmailForZeroAmountInvoice>false</ns1:NoEmailForZeroAmountInvoice>
     </ns2:zObjects>
  </ns1:create>
</soapenv:Body>

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. Any other status will cause an INVALID_VALUE exception to be thrown.

Name	Required?	Value
Id	required	Bill run ID
Status	required	the value must be Posted

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.

Example Request

<api:update>
 <api:zObjects xsi:type="ns2:BillRun">
   <obj:Id>4028920b49307b81014931fbda41008d</obj:Id>
   <obj:Status>Posted</obj:Status>
 </api:zObjects>
</api:update>

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. Any extra parameters will be ignored.

Name	Required?	Value
Id	required	Bill run ID
Status	required	the value must be 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."

Example Request

<api:update>
 <api:zObjects xsi:type="ns2:BillRun">
   <obj:Id>4028920b49307b81014931fbda41008d</obj:Id>
   <obj:Status>Canceled</obj:Status>
 </api:zObjects>
</api:update>

Example Responses

Canceling a bill run with a Completed status:

<ns1:Errors>
   <ns1:Code>INVALID_VALUE</ns1:Code>
   <ns1:Message>The Bill Run cannot be Cancelled,There are Posted invoices.
   </ns1:Message>
</ns1:Errors>

Canceling a bill run with a status that is not Completed:

<ns1:Errors>
  <ns1:Code>INVALID_VALUE</ns1:Code>
  <ns1:Message>Only Bill Runs with the status of Completed or Pending can be cancelled.
  </ns1:Message>
</ns1:Errors>

Delete 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. If the Status is not Canceled, INVALID_VALUE will be returned.

Name	Required?	Value
Id	required	Bill run ID

Example Request

<soapenv:Body>
      <api:delete>
         <api:type>BillingRun</api:type>
         <api:ids>4028920b495f6fcb01495fc94d310033</api:ids>
      </api:delete>
 </soapenv:Body>

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

Example Request

<soapenv:Body>
      <api:query>
         <api:queryString>
                    select
                            Id,
                            AutoEmail,
                            AutoPost,
                            AutoRenewal,
                            Batch,
                            BillCycleDay,
                            BillRunNumber,
                            ChargeTypeToExclude,
                            CreatedById,
                            CreatedDate,
                            NoEmailForZeroAmountInvoice,
                            ErrorMessage,
                            ExecutedDate,
                            InvoiceDate,
                            InvoicesEmailed,
                            LastEmailSentTime,
                            NumberOfAccounts,
                            NumberOfInvoices,
                            AccountId,
                            Status,
                            TargetDate,
                            UpdatedById,
                            UpdatedDate
                            from BillRun
      </api:queryString>
   </api:query>
</soapenv:Body>

Example Response

<soapenv:Body>
      <ns1:queryResponse xmlns:ns1="http://api.zuora.com/">
         <ns1:result>
            <ns1:done>true</ns1:done>
            <ns1:queryLocator xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                   <ns1:records xsi:type="ns2:BillRun" xmlns:ns2="http://object.api.zuora.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                       <ns2:Id>4028902449a718c40149a7ae4f2e023a</ns2:Id>
                       <ns2:AutoEmail>false</ns2:AutoEmail>
                       <ns2:AutoPost>false</ns2:AutoPost>
                       <ns2:AutoRenewal>false</ns2:AutoRenewal>
                       <ns2:Batch>AllBatches</ns2:Batch>
                       <ns2:BillCycleDay>AllBillCycleDays</ns2:BillCycleDay>
                       <ns2:BillRunNumber>BR-00000001</ns2:BillRunNumber>
                       <ns2:CreatedById>402881e522cf4f9b0122cf5d82860002</ns2:CreatedById>
                       <ns2:CreatedDate>2014-11-13T13:44:18.000+08:00</ns2:CreatedDate>
                       <ns2:InvoiceDate>2014-11-13</ns2:InvoiceDate>
                       <ns2:InvoicesEmailed>false</ns2:InvoicesEmailed>
                       <ns2:NoEmailForZeroAmountInvoice>false</ns2:NoEmailForZeroAmountInvoice>
                       <ns2:NumberOfAccounts>0</ns2:NumberOfAccounts>
                       <ns2:NumberOfInvoices>0</ns2:NumberOfInvoices>
                       <ns2:Status>Canceled</ns2:Status>
                       <ns2:TargetDate>2014-11-13</ns2:TargetDate>
                       <ns2:UpdatedById>402881e522cf4f9b0122cf5d82860002</ns2:UpdatedById>
                       <ns2:UpdatedDate>2014-11-13T13:44:31.000+08:00</ns2:UpdatedDate>
                </ns1:records>
           <ns1:size>1</ns1:size>
       </ns1:result>
    </ns1:queryResponse>
</soapenv:Body>