Split Invoices
The createSplitInvoices API is used to split a single or multiple invoice(s) into multiple invoices . You have an option to choose between split by amount or split by percentage methods.
The API can handle the splitting of 10 invoices with 12 line items each during a single execution.
|
API |
Signature |
|---|---|
|
createSplitInvoices |
|
The API accepts source invoice ID, split by amount or percentage, number of splits, as the required input parameters. For each SplitInvoiceRequest, a set of split invoices is generated in Draft status. You can auto-approve the split invoices by setting the Auto Approve Split Invoices to True.
Request - SplitInvoiceRequestInput
|
Field |
Type |
Required |
Description |
|---|---|---|---|
|
Source Invoice ID |
|
Yes |
The ID of the approved Invoice to be split. |
|
|
Yes |
The split method to be used for splitting the invoice.
|
|
Number of Splits |
|
Yes |
The number of splits you want for the source invoice. |
|
Auto Approve Split Invoices |
|
No |
If True, the split invoice is transitioned to Approved status otherwise it is created in a Draft status. |
|
Generate Invoice Line Summary |
|
No |
If True, the split invoices have a line summary generated for them; otherwise, they are created without any line summary. |
|
Split Details Info |
|
Yes |
Information pertaining to splitting the invoices. |
|
Field |
Type |
Required |
Description |
|---|---|---|---|
|
Split By Value |
|
Yes |
The fee amount of the split invoice |
|
Date of Split |
|
Yes |
Date of split |
|
Payment Term ID |
|
No |
Payment term ID to be associated with the split invoice |
|
Bill To ID |
|
No |
The bill to ID for the split invoice. |
|
Account Location ID |
|
No |
The account location ID for the split invoice. |
Response
|
Field |
Type |
Description |
|---|---|---|
|
CustomClass.SplitInvoiceResponse |
|
A result parameter is returned for each request parameter. |
When you split an invoice, the status of the source invoice changes to Distributed status. The split invoices are created based on the values provided by the user. Split invoices are created with the same number of invoice line items as that of the source invoice. The amount for the split invoice is distributed based on the split percentage or split amount. Taxes are recalculated based on the split invoices and Destination Related A/R Transactions are created for each split invoice.
The API returns an error message in the following scenarios:
- Common scenarios for all split types:
- The source invoice ID is not valid.
- The source invoice ID is valid but the invoice has a credit memo associated with it.
- The source invoice ID is valid but the invoice is not approved.
- The source invoice ID is valid but the invoice is already split.
- The source invoice ID is valid but the invoice is paid from a wallet.
- Scenarios exclusive for Split by Amount or Split by Percentage:
- The number of splits is an invalid value.
- The "Split by" is null or has an unrecognized value.
- The number of supplied values for "Split by value" does not match the "Number of splits" mentioned.
- The sum of the percent values of all the splits is not equal to 100.
- The sum of the split amounts mentioned in the split lines does not equal the total value on the original invoice.
- "Auto approve the split invoices" or "Generate Invoice Lines Summary" does not have a valid value.
- Details like Bill To, Location, Payment Term, or Invoice Date are supplied for a few of the splits.
- Scenarios exclusive for Split by Line Item Parameter (Parameter Name):
- There is only one line item on the source invoice.
- The split parameter has same value across all lines.
- Parameter is not recognized or there are duplicate parameter fields.
- The parameter value is NULL or has has no corresponding data across all the line items.
//===============================
Apttus_Billing.CustomClass.SplitInvoiceDetails details1 = new Apttus_Billing.CustomClass.SplitInvoiceDetails
(
40, // Split By value
DateTime.now(), // Date Of Split
null, // Payment Term ID
null, // Bill To ID
null // Account Location ID
);
Apttus_Billing.CustomClass.SplitInvoiceDetails details2 = new Apttus_Billing.CustomClass.SplitInvoiceDetails
(40,DateTime.now(),null,null,null);
Apttus_Billing.CustomClass.SplitInvoiceDetails details3 = new Apttus_Billing.CustomClass.SplitInvoiceDetails
(20,DateTime.now(),null,null,null);
List<Apttus_Billing.CustomClass.SplitInvoiceDetails> splitDetails = new List<Apttus_Billing.CustomClass.SplitInvoiceDetails>();
splitDetails.add(details1);
splitDetails.add(details2);
splitDetails.add(details3);
system.debug('---'+splitDetails);
Apttus_Billing.CustomClass.SplitMethod percentage = Apttus_Billing.CustomClass.SplitMethod.SPLIT_BY_PERCENTAGE;
//Apttus_Billing.CustomClass.SplitMethod amount = Apttus_Billing.CustomClass.SplitMethod.SPLIT_BY_AMOUNT;
Apttus_Billing.CustomClass.SplitInvoiceRequest input1 = new Apttus_Billing.CustomClass.SplitInvoiceRequest
(
'a5TDc00000161lG', //Source Invoice ID.
percentage, //Split By. amount or percentage.
3, //No Of Splits.
true, //Auto Approve split invoices.
true, //Generate Invoice Line Summary.
splitDetails //Split Details Info.
);
List<Apttus_Billing.CustomClass.SplitInvoiceRequest> splitInvoice = new List<Apttus_Billing.CustomClass.SplitInvoiceRequest>();
splitInvoice.add(input1);
List<Apttus_Billing.CustomClass.SplitInvoiceResponse> splitResp = new List<Apttus_Billing.CustomClass.SplitInvoiceResponse>();
splitResp = Apttus_Billing.InvoiceService.createSplitInvoices(splitInvoice);
system.debug('Response!!!!'+splitResp);//=================================
Apttus_Billing.CustomClass.SplitInvoiceDetails details1 = new Apttus_Billing.CustomClass.SplitInvoiceDetails(40,DateTime.now(),null,null,null);
Apttus_Billing.CustomClass.SplitInvoiceDetails details2 = new Apttus_Billing.CustomClass.SplitInvoiceDetails(40,DateTime.now(),null,null,null);
Apttus_Billing.CustomClass.SplitInvoiceDetails details3 = new Apttus_Billing.CustomClass.SplitInvoiceDetails(20,DateTime.now(),null,null,null);
List<Apttus_Billing.CustomClass.SplitInvoiceDetails> splitDetails1 = new List<Apttus_Billing.CustomClass.SplitInvoiceDetails>();
splitDetails1.add(details1);
splitDetails1.add(details2);
splitDetails1.add(details3);
//Apttus_Billing.CustomClass.SplitMethod percentage = Apttus_Billing.CustomClass.SplitMethod.SPLIT_BY_PERCENTAGE;
Apttus_Billing.CustomClass.SplitMethod amount = Apttus_Billing.CustomClass.SplitMethod.SPLIT_BY_AMOUNT;
//a5T040000001ANF - invalid id.
Apttus_Billing.CustomClass.SplitInvoiceRequest input1 = new Apttus_Billing.CustomClass.SplitInvoiceRequest('a5TDc00000161lM',amount,3,false,true,splitDetails1);
//a5T040000001ANK - in draft mode.
Apttus_Billing.CustomClass.SplitInvoiceRequest input2 = new Apttus_Billing.CustomClass.SplitInvoiceRequest('a5TDc00000161lN',amount,3,false,true,splitDetails1);
//a5T040000001ANP- with Distributed status
Apttus_Billing.CustomClass.SplitInvoiceRequest input3 = new Apttus_Billing.CustomClass.SplitInvoiceRequest('a5TDc00000161lO',amount,3,false,true,splitDetails1);
//Auto Approve option is set to null.
Apttus_Billing.CustomClass.SplitInvoiceRequest input4 = new Apttus_Billing.CustomClass.SplitInvoiceRequest('a5TDc00000161lP',amount,3,null,true,splitDetails1);
//Number of split details =12, but provided value=10.
Apttus_Billing.CustomClass.SplitInvoiceRequest input5 = new Apttus_Billing.CustomClass.SplitInvoiceRequest('a5TDc00000161lQ',amount,3,false,true,splitDetails1);
//split by is not valid
Apttus_Billing.CustomClass.SplitInvoiceRequest input6 = new Apttus_Billing.CustomClass.SplitInvoiceRequest('a5TDc00000161lR',amount,3,false,true,splitDetails1);
Apttus_Billing.CustomClass.SplitInvoiceRequest input7 = new Apttus_Billing.CustomClass.SplitInvoiceRequest('a5TDc00000161lG',amount,2,false,true,splitDetails1);
List<Apttus_Billing.CustomClass.SplitInvoiceRequest> splitInvoice = new List<Apttus_Billing.CustomClass.SplitInvoiceRequest>();
splitInvoice.add(input1);
splitInvoice.add(input2);
splitInvoice.add(input3);
splitInvoice.add(input4);
splitInvoice.add(input5);
splitInvoice.add(input6);
splitInvoice.add(input7);
//=======================================================================
List<Apttus_Billing.CustomClass.SplitInvoiceResponse> splitResp = new List<Apttus_Billing.CustomClass.SplitInvoiceResponse>();
splitResp = Apttus_Billing.InvoiceService.createSplitInvoices(splitInvoice);
system.debug('Response!!!!'+splitResp);
Code sample to Split by Line Item Parameter
Apttus_Billing.CustomClass.SplitMethod splitByCriteria = Apttus_Billing.CustomClass.SplitMethod.SPLIT_BY_CRITERIA;
String criteria = 'LocationId__c';
Boolean autoApproveSplitInvoice = false;
Boolean generateInvoiceLinesSummary = false;
Apttus_Billing.CustomClass.SplitInvoiceRequest input1 = new Apttus_Billing.CustomClass.SplitInvoiceRequest('a2Vg80000038Y4PEAU', splitByCriteria, criteria, autoApproveSplitInvoice , generateInvoiceLinesSummary );
List<Apttus_Billing.CustomClass.SplitInvoiceRequest> splitInvoice = new List<Apttus_Billing.CustomClass.SplitInvoiceRequest>();
splitInvoice.add(input1);
// Users can add multiple splitInvoice.add(input2); splitInvoice.add(input3);
List<Apttus_Billing.CustomClass.SplitInvoiceResponse> response = new List<Apttus_Billing.CustomClass.SplitInvoiceResponse>();
response = InvoiceService.createSplitInvoices(splitInvoice);
System.debug('Response!!'+response);For example, you have the following invoice (Invoice - 002300) and you want to split it based on service location.
| Invoice Line Item ID | Product Name | Quantity | Period Start Date | Period End Date | Fee Amount | Price Type | Charge Type | Service Location |
| ILI-001 | Machine Usage | 1.00 | 1-Jun-26 | 31-Aug-26 | $25,000.00 | Usage | Usage | San Mateo, CA |
| ILI-002 | Machine Usage | 1.00 | 1-Jun-26 | 31-Aug-26 | $25,000.00 | Usage | Usage | Pleasanton, CA |
| ILI-003 | Installation | 1.00 | 1-Jun-26 | 30-Jun-26 | $10,000.00 | One-Time | Service | |
| ILI-005 | Maintenance | 2.00 | 1-Jun-26 | 30-Jun-26 | $100,000.00 | Recurring | Service | Pleasanton, CA |
You called the Split invoices API and set the Spit by Criteria as LocationId; CustomClass.SplitMethod splitByCriteria = CustomClass.SplitMethod.SPLIT_BY_CRITERIA;
String criteria = 'LocationId__c';.
The invoice is split into three child invoices (Invoices - 002302, 002303, and 002304) based on the service locations (San Mateo, CA, Pleasanton, CA, and blank field - service location not specified) as follows:
Invoice - 002302
| Invoice Line Item ID | Product Name | Quantity | Period Start Date | Period End Date | Fee Amount | Price Type | Charge Type | Service Location |
| ILI-001 | Machine Usage | 1.00 | 1-Jun-26 | 31-Aug-26 | $25,000.00 | Usage | Usage | San Mateo, CA |
Invoice - 002303
| Invoice Line Item ID | Product Name | Quantity | Period Start Date | Period End Date | Fee Amount | Price Type | Charge Type | Service Location |
| ILI-002 | Machine Usage | 1.00 | 1-Jun-26 | 31-Aug-26 | $25,000.00 | Usage | Usage | Pleasanton, CA |
| ILI-005 | Maintenance | 2.00 | 1-Jun-26 | 30-Jun-26 | $100,000.00 | Recurring | Service | Pleasanton, CA |
Invoice - 002304
| Invoice Line Item ID | Product Name | Quantity | Period Start Date | Period End Date | Fee Amount | Price Type | Charge Type | Service Location |
| ILI-003 | Installation | 1.00 | 1-Jun-26 | 30-Jun-26 | $10,000.00 | One-Time | Service |