Skip to main content

Split an Invoice for Flexible Payment Terms

Zuora

Split an Invoice for Flexible Payment Terms

  1. Last updated
  2. Save as PDF

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

Invoices are bills that you send to customers. You generate invoices from a bill run, then email invoices as PDFs to your customers in batches or individually, or print the invoices and send them to customers through postal mail.

Sometimes, you might produce an invoice that's particularly large, and a customer asks if you can spread the balance due on that invoice across multiple billing periods. To accommodate this customer, you can split the invoice.

An invoice split is one of multiple invoices that together formed one original invoice. Splitting a single invoice into multiple invoices lets you offer flexible payment schedules, especially when the original invoice balance is a large sum.

Splitting invoices lets a customer spread out payments for a single invoice over multiple invoices. For example, a customer has an invoice that totals $100,000. You agree to let the customer make four payments spread across multiple billing periods on the invoice. You can split that invoice into four separate invoices, each for a specific percentage of the original amount. These percentages can be any amount that you want to set, as long as the collection of split invoices total 100% of the original invoice. In this example, you can set the first split invoice to 40% ($40,000), then each successive split invoice to 30% ($30,000), 20% ($20,000), and 10% ($10,000).

In this walkthrough, we're going to follow a Zuora API user, Lucia, as she splits a large invoice for a customer who asks for flexible payment terms to pay that invoice. You can use her code samples to customize her actions to fit your own needs.

If you're an advanced API user, then you might want to review only the Implementation section of this walkthrough to get a quick list of the steps for splitting an invoice without the additional details.

Rounding rule implications

In this scenario, values of .005 and above are rounded up to .01, and values of .004 and below are rounded to 0. For example, while 13% of the original invoice of $36,132.68 is $4,697.2484, the fourth invoice is $4,697.25 because rounding rules are set to round at half up. At the final invoice in the series of split invoices, the rounding differences from the percentage splits are accounted for. If your rounding rules are set differently, then your totals with the same numbers as Lucia's numbers might be different.

Problem

Lucia is a Zuora API user who works for Widget Wiki, which is a hosted wiki service that customers use to create business-related wikis, especially for software help systems and related business cases. Her customers represent a range of business sizes, and most of them use her service to create cloud-based, collaborative documentation systems with a substantial social component.

George is one of Widget Wiki's customers, and he uses the product to produce user documentation for a 200-employee software company in the United States. The dates for his subscription are the following:

  • Contract effective date: 10 October 2012
  • Subscription start date: 01 November 2012
  • Charge trigger date: 01 November 2012

The bill cycle day for all Widget Wiki customers is always the first of the month.

George's particular rate plan includes the following charges:

  • Annual recurring charge: $40,000
  • Customer loyalty discount: 10%
  • New writer training package (printed materials): $122 (taxable at 8.75%)

His invoice balance is $36,132.68. For a variety of reasons internal to his company, he asks Lucia for flexible payment arrangements on the invoice for his subscription to her service. He wants to pay the invoice's balance over multiple billing periods.

Solution

After discussing George's specific needs, Lucia decides to address the problem by splitting the original invoice into three new invoices:

  • Invoice #1
    • Date: 01 November 2012
    • Payment term: Due upon receipt
    • Amount: 50% of the original total ($18,066.34)
  • Invoice #2
    • Date: 01 February 2013
    • Payment term: Net 30 days
    • Amount: 25% of the original total ($9,033.17)
  • Invoice #3
    • Date: 01 May 2013
    • Payment term: Net 30 days
    • Amount: 25% of the original total ($9,033.17)

Preparation

Only draft invoices can be split. George's invoice is already posted. Therefore, Lucia prepares to split the invoice by reverting the original invoice to draft state.

Lucia uses an update() call to change the Invoice.Status field from Posted to Draft. She passes the following fields:

  • InvoiceId
  • Status

​Field Descriptions

The example values are the values that Lucia uses in her code sample. If you use her code samples, substitute your own values.

Name Required? Description
InvoiceId required

The ID of the original invoice that Lucia is preparing to split.

Type: zns:ID

Character limit: 32

Values: a valid invoice ID

Example value: 8a8ae4b122561fc00122562fbc3d0002
Status required

The status of the invoice in the system. This status is not the status of the payment of the invoice, just the status of the invoice itself.

Type: string (enum)

Character limit: 8

Values: Draft, Posted, Canceled

Example value: Draft

Code Sample

<ns1:update xmlns:ns1="http://api.zuora.com/">
    <ns1:zObjects xsi:type="ns2:Invoice" xmlns:ns2="http://object.api.zuora.com/"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <ns2:Id>8a8ae4b122561fc00122562fbc3d0002</ns2:Id>
        <ns2:Status>Draft</ns2:Status>
    </ns1:zObjects>
</ns1:update>

Implementation

To split the original invoice into three invoices, Lucia needs to create an invoice split, create the three new invoices, then execute the invoice split. As you follow along, be sure to take these steps in the correct order, or you can't finish the task:

  1. Create an InvoiceSplit object.
  2. Create an InvoiceSplitItem object for each split invoice that you want to create from the original invoice.
  3. Execute the InvoiceSplit object to split the original invoice into multiple invoices.

Create an InvoiceSplit object

Lucia needs one InvoiceSplit object for the invoice split. As you follow along, be sure that you create the InvoiceSplit object before you try to create the individual InvoiceSplitItem objects: you need the resulting InvoiceSplitId field value to create the individual items.

Field Descriptions

The example values are the values that Lucia uses in her code sample. If you use her code samples, then substitute your own values.

Name Required? Description
InvoiceId required

The ID of the original invoice that the InvoiceSplit object splits.

Type: zns:ID

Character limit: 32

Values: a valid invoice ID

Example value: 8a8ae4b122561fc00122562fbc3d0002

Code Samples

Lucia passes create() call to create the InvoiceSplit object.

<soapenv:Body>
    <ns1:create>
        <ns1:zObjects xsi:type="ns2:InvoiceSplit”>
            <ns2:InvoiceId>2c90803e386cc2bf01386cfe97ab0015</ns2:InvoiceId>
        </ns1:zObjects>
    </ns1:create>
</soapenv:Body>

After successful completion of the call, Lucia receives a response that includes the ID of the new InvoiceSplit object: 402881822a453a87012a4553f6cd01d8. She notes this ID because she needs it for the next step, creating an InvoiceSplitItem object for each new invoice. Your value differs from hers because these IDs are unqiue; be sure to note your own InvoiceSplit object ID.

Create InvoiceSplitItem objects

Lucia needs one InvoiceSplitItem object for every invoice that she wants to create from the original invoice. Therefore, she creates three InvoiceSplitItem objects.

Field Descriptions

The example values are the values that Lucia uses in her code sample. Because she's creating three InvoiceSplitItem objects, there are three example values. If you use her code samples, then substitute your own values.

Name Required? Description
InvoiceDate required

The generation date of the new split invoice.

Type: 

  • date supported as of WSDL version 69+
  • dateTime supported through WSDL version 68

Character limit: 29
InvoiceSplitId required

The ID of the invoice split to associate with this invoice split item. This value is the same for all three InvoiceSplitItem objects that Lucia is creating to split George's original invoice. You get this value from the InvoiceSplit object, which you need to create before you can create an InvoiceSplitItem objects.

Type: zns:ID

Character limit: 32

Values: a valid invoice split ID

Example value: 402881822a453a87012a4553f6cd01d8
PaymentTerm required

Indicates when payment on the invoice balance is due. Your allowed values might differ from Lucia's allowed values because payment terms are configurable. Lucia and George agree that the first split invoice is immediately due upon receipt, and the remaining two split invoices are due within 30 days of receipt.

Type: string

Character limit: 

Values: a valid, active payment term defined in the web-based UI administrative settings

Example values:

  • DueUponReceipt
  • Net30
  • Net30
SplitPercentage required

Specifies the percentage of the original invoice that you want to be the balance of the split invoice. The total of the SplitPercentage field values for all of the InvoiceSplitItem objects in an InvoiceSplit object must equal 100. Lucia and George agree that the first split invoice is 50% of the original invoice, and the remaining two split invoice are each 25% of the original invoice.

Type:

  • If you're using WSDL 73.0 or earlier: long
  • If you're using WSDL 74.0 or later: decimal

Values:

  • If you're using WSDL 73.0 or earlier: a whole number between 1 and 100
  • If you're using WSDL 74.0 or later: a decimal number with up to nine decimal places between 0.000000001 and 100, for example, 25 or 33.34

Code Samples

Lucia passes three create() calls to create three InvoiceSplitItem objects. Each successful call returns an InvoiceId value for the new invoice created by the InvoiceSplitItem. You can note these IDs so that you have a list of new invoice IDs split from the original invoice, or you can run a query() call later against the individual InvoiceSplitItem objects.

<ns1:create>
    <ns1:zObjects xsi:type="ns2:InvoiceSplitItem”>
         <ns2:InvoiceDate>2012-11-01</ns2:InvoiceDate>
         <ns2:InvoiceSplitId>402881822a453a87012a4553f6cd01d8</ns2:InvoiceSplitId>
         <ns2:PaymentTerm>DueUponReceipt</ns2:PaymentTerm>
         <ns2:SplitPercentage>50</ns2:SplitPercentage>
    </ns1:zObjects>
</ns1:create>
<ns1:create>
    <ns1:zObjects xsi:type="ns2:InvoiceSplitItem”>
         <ns2:InvoiceDate>2013-02-01</ns2:InvoiceDate>
         <ns2:InvoiceSplitId>402881822a453a87012a4553f6cd01d8</ns2:InvoiceSplitId>
         <ns2:PaymentTerm>Net30</ns2:PaymentTerm>
         <ns2:SplitPercentage>25</ns2:SplitPercentage>
    </ns1:zObjects>
</ns1:create>

<ns1:create>
    <ns1:zObjects xsi:type="ns2:InvoiceSplitItem”>
         <ns2:InvoiceDate>2013-05-01</ns2:InvoiceDate>
         <ns2:InvoiceSplitId>402881822a453a87012a4553f6cd01d8</ns2:InvoiceSplitId>
         <ns2:PaymentTerm>Net30</ns2:PaymentTerm>
         <ns2:SplitPercentage>25</ns2:SplitPercentage>
    </ns1:zObjects>
</ns1:create>

Execute an InvoiceSplit object

Lucia has all of the pieces that she needs to create three invoices from George's orignal invoice. She passes an execute() call to execute the invoice split.

Field Descriptions

The example values are the values that Lucia uses in her code sample. If you use her code samples, then use the same values that she uses for the fields, type and synchronous, but substitute your own values for the ids field.

Name Required? Description
type required

Specifies that the type of the executed item is an invoice split. You must enter invoicesplit.

Value: invoicesplit
synchronous required

Indicates that the call is asynchronous. You must enter false.

Value: false
ids required

The ID of the InvoiceSplit object. You must enter your own value.

Type: zns:ID

Character limit: 32

Values: a valid invoice split ID

Example value: 402881822a453a87012a4553f6cd01d8

Code Sample

Lucia passes an execute() call to execute the InvoiceSplit object.

<ns1:execute>
    <ns1:type>invoicesplit</ns1:type>
    <ns1:synchronous>false</ns1:synchronous>
    <ns1:ids>402881822a453a87012a4553f6cd01d8</ns1:ids>
</ns1:execute>

What if I need to change a split invoice?

Lucia can resplit the invoice if she and George decide that they need to change the split invoices. To resplit the invoice, she needs to return any invoices that are in Posted or Canceled status to Draft status, then do an appropriate combination of the following actions to resplit the invoice the way she and George choose:

  • Use the update() call on the individual InvoiceSplitItem objects to change them.
  • Use the create() call to create additional InvoiceSplitItem objects if Lucia and George need more split invoices.
  • Use the delete() call to remove individual InvoiceSplitItem objects if Lucia and George need fewer split invoices.

Problem

George asks to make the following changes to the split invoices:

  • Change the payment term of the first split invoice from due upon receipt to net 30 days.
  • Change the date of the second split invoice to 01 January 2013.
  • Change the percentage of the third invoice from 25% to 12%.
  • Add a fourth invoice for the final 13% of the original invoice, due 01 August 2013.

Solution

After discussing George's specific needs, Lucia decides to address the problem by resplitting the original invoice. She changes the existing split invoices and adds a fourth invoice:

  • Invoice #1
    • Date: 01 November 2012
    • Payment term: Net 30 days
    • Amount: 50% of the original total ($18,066.34)
  • Invoice #2
    • Date: 01 January 2013
    • Payment term: Net 30 days
    • Amount: 25% of the original total ($9,033.17)
  • Invoice #3
    • Date: 01 May 2013
    • Payment term: Net 30 days
    • Amount: 12% of the original total ($4,335.92)
  • Invoice #4
    • Date: 01 August 2013
    • Payment term: Net 30 days
    • Amount: 13% of the original total ($4,697.25)

Preparation

Only draft invoices can be split. If any of the invoices are in a status other than Draft status, then Lucia needs to revert them back to Draft. Review the Preparation section if you need help with this task.

​Implementation

Lucia needs to do the following tasks in any order:

  • Change the payment term of the first invoice split.
    • Use an update() call on the first invoice's InvoiceSplitItem object to change the PaymentTerm field value.
  • Change the date of the second invoice.
    • Use an update() call on the first invoice's InvoiceSplitItem object to change the InvoiceDate field value.
  • Change the percentage splits of the third invoice.
    • Use an update() call on the third invoice's InvoiceSplitItem objects to change the PercentageSplit field value.
  • Add a fourth invoice.
    • Use a create() call to create a fourth InvoiceSplitItem object.

When she finishes those tasks, she need to execute the InvoiceSplit object. As you follow along, be sure to take this next step last. You need to make all of your InvoiceSplitItem changes before you can do this next step or the execute() call doesn't do what you need it to do:

  • Execute the InvoiceSplit object to resplit the original invoice into four invoices. The first three invoices are modified rather than recreated, and the fourth invoice is created.

Change the InvoiceSplitItem objects

Click the tabs to read how Lucia implements each step of her task. Use the horizontal scroll bar below the tabs to see all the tabs.

 

Change the payment term of the first invoice split

Lucia needs to change the payment term of the first split invoice from due upon receipt to net 30. She uses an update() call on the first invoice's InvoiceSplitItem object, and changes the PaymentTerm field value. The following fields are required for this use case:

  • Id is the ID of the InvoiceSplitItem object.
    • Lucia's value is 5139f7001712831e12372b6e462d2066.
  • PaymentTerm is the payment term that Lucia is changing.
    • Lucia's value is Net30.
<soapenv:Body>
    <ns1:update>
        <ns1:zObjects xsi:type="ns2:InvoiceSplitItem”>
            <ns2:Id>5139f7001712831e12372b6e462d2066</ns2:Id>
            <ns2:PaymentTerm>Net30</ns2:PaymentTerm>
        </ns1:zObjects>
    </ns1:create>
</soapenv:Body>

After successful completion of the call, Lucia receives a response that repeats the ID of the updated InvoiceSplitItem object, 5139f7001712831e12372b6e462d2066, and a Success indicator of true to confirm success.

 

Change the date of the second invoice

Lucia needs to change the date of the second invoice from 01 February 2013 to 01 January 2013. She uses an update() call on the invoice's InvoiceSplitItem object, and change its InvoiceDate field value. The following fields are required for this use case:

  • Id is the ID of the InvoiceSplitItem objects.
    • Lucia's value is: 5139f7001712831e12372b6e462d2067.
  • InvoiceDate is the generation date of the split invoice.
    • Lucia's value is: 2013-01-01T08:07:55-08:00.
<soapenv:Body>
    <ns1:update>
        <ns1:zObjects xsi:type="ns2:InvoiceSplitItem”>
            <ns2:Id>5139f7001712831e12372b6e462d2067</ns2:Id>
            <ns2:InvoiceDate>2013-01-01</ns2:InvoiceDate>
        </ns1:zObjects>
    </ns1:create>
</soapenv:Body>

After successful completion of the call, Lucia receives a response that repeats the ID of the updated InvoiceSplitItem object, 5139f7001712831e12372b6e462d2067, and a Success indicator of true to confirm success.

 

Change the percentage split of the third invoice

Lucia needs to change the percentage splits of the third invoice from 25% to 12%. She uses an update() call on the invoice's InvoiceSplitItem object, and change its PercentageSplit field value. The following fields are required for this use case:

  • Id is the ID of the InvoiceSplitItem objects.
    • Lucia's value is: 5139f7001712831e12372b6e462d2068.
  • PercentageSplit is the percentage of the original invoice that you want to be the balance of the split invoice.
    • Lucia's value is: 12.

As you follow along, remember that the total of the SplitPercentage field values for all of theInvoiceSplitItem objects in an InvoiceSplit object must equal 100. Therefore, when you change this field value in one InvoiceSplitItem object, you need to change the value in another the InvoiceSplitItem object or create a new InvoiceSplitItem object to keep the total at 100.

<soapenv:Body>
    <ns1:update>
        <ns1:zObjects xsi:type="ns2:InvoiceSplitItem”>
            <ns2:Id>5139f7001712831e12372b6e462d2068</ns2:Id>
            <ns2:PercentageSplit>12</ns2:PercentageSplit>
        </ns1:zObjects>
    </ns1:create>
</soapenv:Body>

After successful completion of the call, Lucia receives a response that repeats the ID of the updated InvoiceSplitItem object, 5139f7001712831e12372b6e462d2068, and a Success indicator of true to confirm success.

 

Create a new InvoiceSplitItem object

Lucia needs to create a new InvoiceSplitItem object to accommodate George's request for a fourth invoice split and to meet the API requirement that the total of all of the invoice splits equal 100% of the original balance. She has 10% of the balance unaccounted for in the existing three InvoiceSplitItem objects. The following fields are required for this use case:

  • InvoiceDate is the generation date of the new invoice.
    • Lucia's value is 2013-08-01T08:07:55-08:00.
  • InvoiceSplitId is the ID of of the invoice split that you want to associate with this invoice split item.
    • Lucia's value is 402881822a453a87012a4553f6cd01d8.
  • PaymentTerm is when payment on the invoice balance is due.
    • Lucia's value is Net30.
  • SplitPercentage is the percentage of the original invoice that you want to be the balance of the split invoice.
    • Lucia's value is 10.

As you follow along, remember that the total of the SplitPercentage field values for all of the InvoiceSplitItem objects in an InvoiceSplit object must equal 100.

<ns1:create>
    <ns1:zObjects xsi:type="ns2:InvoiceSplitItem”>
         <ns2:InvoiceDate>2013-08-01</ns2:InvoiceDate>
         <ns2:InvoiceSplitId>402881822a453a87012a4553f6cd01d8</ns2:InvoiceSplitId>
         <ns2:PaymentTerm>Net30</ns2:PaymentTerm>
         <ns2:SplitPercentage>10</ns2:SplitPercentage>
    </ns1:zObjects>
</ns1:create>

After successful completion of the call, Lucia receives a response that repeats the ID of the updated InvoiceSplitItem object, 5139f7001712831e12372b6e462d2069, and a Success indicator of true to confirm success.

Execute the InvoiceSplit object

After Lucia finishes making all the changes to the individual InvoiceSplitItem objects, including creating a new one, she needs to pass an execute() call to resplit the invoice. Because she's running the call on the same InvoiceSplit object as she did when she originally split the invoice, she runs the same call with no changes. All of her changes are encapsulated in the update() calls on the InvoiceSplitItem objects.

<ns1:execute>
    <ns1:type>invoicesplit</ns1:type>
    <ns1:synchronous>false</ns1:synchronous>
    <ns1:ids>402881822a453a87012a4553f6cd01d8</ns1:ids>
</ns1:execute>

After successful completion of the call, Lucia receives a response that repeats the ID of the updated InvoiceSplit object, 402881822a453a87012a4553f6cd01d8, and a Success indicator of true to confirm success.

What next?

Lucia has changed the invoice split according to the terms that she and George agreed. She can make more changes if they become necessary, but barring more changes, she's finished with this invoice split. It's ready to go into scheduled bill runs for generation and payment, or to be generated ad hoc with the generate() call.