Knowledge Center

Knowledge Center > API > SOAP API > SOAP API Object Reference > BillRun > BillRun Use Cases

BillRun Use Cases

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 wish 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>
Last modified
09:56, 28 Dec 2015

Tags

Classifications

(not set)