Creating an Invoice with Line Items

The following example shows how to create an invoice and add an expense and fee line item to the invoice. When creating an invoice, you must populate a few required properties using the following methods (from the type class, InvoiceCreate): setNumberString, setInvoiceDate, and setVendorUniqueKey.

It is most practical to add one or more line items to an invoice. There are two types of line items you can add: expense or fee line items. For expense line items, you must populate a few required properties using the following methods (from the type class, LineItemCreate): setItemNumber, setServiceDate, setProjectUniqueKey, setOriginalRate, setOriginalQuantity, setOriginalDiscount, setType, and getCategories. For fee line items, you must populate a few required properties using the following methods (from the type class, LineItemCreate): setItemNumber, setServiceDate, setProjectUniqueKey, setOriginalRate, setOriginalQuantity, setOriginalDiscount, setType, getCategories, setTimekeeperUniqueKey, and setActivityUniqueKey.

Before starting, get the following:

• For expense line items, get the corresponding Line Item Expense Category Code(s)
• For fee line items, get the corresponding Line Item Fee Category Code(s) and Task Activity Lookup Table Activity Code(s)

When adding an expense line item to an invoice, use the Category object to specify the corresponding expense category. As described in the category example for contacts, you must already know the target expense category's unique key.

Code Snippet

protected InvoiceRepository invoice = new InvoiceRepository(); 
InvoiceCreate invoice = createInvoice(); 
invoice.insertInvoice(invoice);
private InvoiceCreate createInvoice() throws Exception { 
    Date date = new Date();
    long time = date.getTime();
    InvoiceCreate invoice = new InvoiceCreate();
    //numberString is a required field invoice.setNumberString("invoice Web Service test " + time);
    //vendorUniqueKey is a required field invoice.setVendorUniqueKey("CONT_8094");
    //invoiceDate is a required field invoice.setInvoiceDate(date); 
    invoice.setComment("comment"); 
    invoice.setPeriodStartDate(date); 
    invoice.setPeriodEndDate(new Date(time + 1000000)); 
    invoice.setSubmittedElectronically(true); 
    invoice.setReceivedDate(date); 
    invoice.setTaxRate(new BigDecimal("8")); 
    invoice.setWarnings("invoice warning");
    //Note that it is practical although not required to add one or more line items to an invoice
    invoice.getLineItemCreates().addAll(createLineItems()); 
    return invoice;
}
private List<LineItemCreate> createLineItems() throws Exception { 
    List<LineItemCreate> lineItems = new List<LineItemCreate>();
    //create expense line item
    LineItemCreate lineItem1 = new LineItemCreate();
    //itemNumber is a required field lineItem1.setItemNumber(1);
    //for expense line items, originalQuantity is a required field that corresponds to a 
    quantity of expense items being charged
    lineItem1.setOriginalQuantity(new BigDecimal("2"));
    //for expense line items, originalRate is a required field that corresponds to the per unit cost of expense item
    lineItem1.setOriginalRate(new BigDecimal("50"));
    //for expense line items, type (LineItemType) is a required field and would always be EXPENSE
    lineItem1.setType(LineItemType.EXPENSE); lineItem1.setServiceDate(date);
    //category for each line item is a required field Category cat1 = new Category(); cat1.setUniqueKey("EXPE"); 
    lineItem1.getCategories().add(cat1); lineItems.add(lineItem1);
    //create fee line item
    LineItemCreate lineItem2 = new LineItemCreate(); lineItem2.setItemNumber(2);
    //for Fee line items, the originalQuantity is a required field and will correspond 
    to the hours worked by the timekeeper
    lineItem2.setOriginalQuantity(new BigDecimal("2"));
    //for Fee line items, the originalRate is a required field and will correspond to the associated timekeeper's rate
    lineItem2.setOriginalRate(new BigDecimal("50"));
    //for fee line items, type (LineItemType) is a required field and would always be FEE
    lineItem2.setType(LineItemType.FEE); 
    lineItem2.setServiceDate(date); 
    Category cat2 = new Category(); 
    cat2.setUniqueKey("TASK"); 
    lineItem2.getCategories().add(cat2);
    //for fee line items, the activityUniqueKey is a required field; the ActivityUniqueKey 
    property needs to be constructed by 
    "ACTI_"+<4 character Task Activity Lookup Table Activity Code>; 
    see the example below where the Activity Code is A101
    lineItem2.setActivityUniqueKey("ACTI_A101"); 
    lineItems.add(lineItem2);
    return lineItems;
}

Updating and Adjusting an Invoice

The following example shows how to update an invoice. You can edit the properties of the invoice as well as adjust the invoice summary or adjust the invoice's line items when you perform an invoice update.

The section of the example that shows how to adjust an invoice summary does so by changing the invoice total to a specified amount. It is assumed that there is an existing invoice that will be adjusted. To access an existing invoice, use the InvoiceRepository's updateInvoice method. To create the invoice summary adjustment, use the type class, InvoiceAdjustmentCreate. Note that there are other ways to adjust an invoice summary and you can refer to the User Guide for more general information.

When creating an invoice summary adjustment, you must use the following set methods to populate required fields: setAdjustingUserUniqueKey(String value), setAdjustmentDate(Date value), setAdjustmentTarget(InvoiceAdjustmentTarget value), setAdjustmentValue(BigDecimal value), setAdjustmentMethod(AdjustmentMethod value).

For more information on adjusting line items, see Adjusting Invoice Line Items.

Code Snippet

//for this example, it is assumed that you already know the target invoice record's unique key 
(where uniqueKey is a String variable) protected InvoiceRepository invoice = new InvoiceRepository(); 
InvoiceUpdate invoice = updateInvoice(); invoice.updateInvoice(invoice);
private InvoiceUpdate updateInvoice() throws Exception { 
    Date date = new Date();
    String uniqueKey = "inv5010897"; InvoiceUpdate invoice = new InvoiceUpdate();
    //next line used to ID the invoice to update invoice.setUniqueKey(uniqueKey);
    //these 3 lines update invoice properties invoice.setNumberString("inv100-2053"); 
    invoice.setInvoiceDate(date); 
    invoice.setVendorUniqueKey("ven2345");
    //these lines are used to adjust the invoice header/summary 
    invoice.getAdjustmentUpdates().add(createInvoiceAdjustment()); 
    return invoice;
}
private InvoiceAdjustmentCreate createInvoiceAdjustment() throws Exception { 
    String userUniqueKey = "user101";
    InvoiceAdjustmentCreate invoiceAdjustment = new InvoiceAdjustmentCreate(); 
    invoiceAdjustment.setAdjustingUserUniqueKey(userUniqueKey); 
    invoiceAdjustment.setAdjustmentDate(date); 
    invoiceAdjustment.setAdjustmentTarget(InvoiceAdjustmentTarget.TOTAL_INVOICE); 
    invoiceAdjustment.setAdjustmentValue(2005.17); 
    invoiceAdjustment.setAdjustmentMethod(AdjustmentMethod.NEW_AMOUNT);
    invoiceAdjustment.setInHouseComments("Rejected invoice because the timekeeper rate exceeds our agreement. 
    Adjusting the total per acceptable rates.");
    invoiceAdjustment.setCommentsToVendor("Rejected invoice because the timekeeper rate exceeds our agreement. 
    Adjusting the total per acceptable rates.");
    return invoiceAdjustment;
}

Adjusting Invoice Line Items

The following example shows how to adjust an invoice line item by changing the line item rate by a specified amount. In the example, it is assumed there is an existing invoice with one or more line items. To access an existing invoice, use the InvoiceRepository's updateInvoice method. To perform the line item adjustment, use the type class, LineItemAdjustmentUpdate.

Note: You can also adjust line items at the time you add line items to an invoice. In this case, you can use either the InvoiceRepository's insertInvoice or updateInvoice method. Since you are adjusting the line item and creating it at the same time, use the type class, LineItemAdjustmentCreate.

When performing a line item adjustment, you must use the following set methods to populate required fields: .

Code Snippet for adjusting invoice line items on invoice update

protected InvoiceRepository invoice = new InvoiceRepository(); 
InvoiceUpdate invoice = updateInvoice(); 
invoice.updateInvoice(invoice);
private InvoiceUpdate updateInvoice() throws Exception {
    Date date = new Date();
    InvoiceUpdate invoice = new InvoiceUpdate();
    //these 3 lines are used to ID the invoice to update invoice.setNumberString("inv100-2053"); 
    invoice.setInvoiceDate(date); invoice.setVendorUniqueKey("ven2345");
    //these lines are used to adjust an invoice line item 
    invoice.getLineItemCreates().add(createLineItemAdjustment()); 
    return invoice;
}
private LineItemAdjustmentCreate createLineItemAdjustment() throws Exception { 
    String userUniqueKey = "user_101";
    LineItemAdjustmentCreate lineItemAdjustment = new LineItemAdjustmentCreate(); 
    lineItemAdjustment.setAdjustingUserUniqueKey(userUniqueKey); 
    lineItemAdjustment.setAdjustmentDate(date); 
    lineItemAdjustment.setAdjustmentTarget(LineItemAdjustmentTarget.RATE); 
    lineItemAdjustment.setAdjustmentValue(45.5); 
    lineItemAdjustment.setAdjustmentMethod(AdjustmentMethod.REDUCE_BY_AMOUNT);
    lineItemAdjustment.setInHouseComments("Rejected invoice because the timekeeper rate exceeds our agreement. 
    Adjusting the rate down.");
    lineItemAdjustment.setCommentsToVendor("Rejected invoice because the timekeeper rate exceeds our agreement. 
    Adjusting the line item rate.");
    return lineItemAdjustment;
}

Reading an Invoice

The following sample reads an invoice record. You must get the unique key value for the invoice record to update.

Code Snippet

//for this sample, it is assumed that the unique key of the target Invoice record to read is a String, "INVC_0011"
protected InvoiceRepository invoiceRepository;
Invoice invoice = invoiceRepository.readInvoice("INVC_0011", getPropertiesToRead());
private List<String> getPropertiesToRead() { List<String> properties = new List<String>(); 
    properties.add("version"); 
    properties.add("createdBy"); 
    properties.add("createdOn"); 
    properties.add("modifiedBy"); 
    properties.add("modifiedOn"); 
    properties.add("numberString"); 
    properties.add("invoiceDate"); 
    properties.add("receivedDate");
    properties.add("periodStartDate"); 
    properties.add("periodEndDate"); 
    properties.add("submittedElectronically"); 
    properties.add("postingStatus"); 
    properties.add("vendor"); 
    properties.add("submittedTotal"); 
    properties.add("currency"); 
    properties.add("comment"); 
    properties.add("warnings"); 
    properties.add("taxRate"); 
    properties.add("adjustments"); 
    properties.add("lineItems"); 
    properties.add("originalExpenseTotal"); 
    properties.add("originalFeeTotal"); 
    properties.add("originalInvoiceTotal"); 
    properties.add("expenseDiscountTotal"); 
    properties.add("feeDiscountTotal"); 
    properties.add("invoiceDiscountTotal"); 
    properties.add("expenseAdjustmentTotal"); 
    properties.add("feeAdjustmentTotal"); 
    properties.add("invoiceAdjustmentTotal"); 
    properties.add("expenseTaxTotal"); 
    properties.add("feeTaxTotal"); 
    properties.add("invoiceTaxTotal"); 
    properties.add("netExpenseTotal"); 
    properties.add("netFeeTotal");
    properties.add("netInvoiceTotal"); 
    properties.add("categories"); 
    properties.add("note");
    return properties;
}

protected InvoiceRepository invoiceRepository;
private List<Invoice> test_readInvoicesByCriteria() throws Exception
{
    // Criterion for invoice searching
    StringFieldCriterion fieldCriterion = new StringFieldCriterion(); 
    fieldCriterion.setComparator(UserComparator.CONTAINS);
    LegacySearchFieldPathExpression fieldPathExpression = new LegacySearchFieldPathExpression();
    fieldPathExpression.setSearchKeyPath("vendor"); 
    fieldCriterion.setFieldPath(fieldPathExpression); 
    fieldCriterion.getValue().add("Rubidoux Accounting"); 
    FieldSearchClause searchCriteria = new FieldSearchClause(); 
    searchCriteria.setOperator(LogicOperator.AND); 
    searchCriteria.getCriteria().add(fieldCriterion);
    invoices = invoiceRepository.readInvoicesByCriteria(searchCriteria, 100, 
    getPropertiesToRead());
}
private List<String> getPropertiesToRead() { 
    List<String> properties = new List<String>(); 
    properties.add("version"); properties.add("createdBy"); 
    properties.add("createdOn"); 
    properties.add("modifiedBy"); 
    properties.add("modifiedOn"); 
    properties.add("numberString"); 
    properties.add("invoiceDate"); 
    properties.add("receivedDate"); 
    properties.add("periodStartDate"); 
    properties.add("periodEndDate"); 
    properties.add("submittedElectronically"); 
    properties.add("postingStatus"); 
    properties.add("vendor"); 
    properties.add("submittedTotal"); 
    properties.add("currency"); 
    properties.add("comment"); 
    properties.add("warnings"); 
    properties.add("taxRate"); 
    properties.add("adjustments"); 
    properties.add("lineItems"); 
    properties.add("originalExpenseTotal"); 
    properties.add("originalFeeTotal"); 
    properties.add("originalInvoiceTotal"); 
    properties.add("expenseDiscountTotal"); 
    properties.add("feeDiscountTotal"); 
    properties.add("invoiceDiscountTotal"); 
    properties.add("expenseAdjustmentTotal"); 
    properties.add("feeAdjustmentTotal"); 
    properties.add("invoiceAdjustmentTotal"); 
    properties.add("expenseTaxTotal"); 
    properties.add("feeTaxTotal"); 
    properties.add("invoiceTaxTotal");
    properties.add("netExpenseTotal"); 
    properties.add("netFeeTotal"); 
    properties.add("netInvoiceTotal"); 
    properties.add("categories"); 
    properties.add("note");
    return properties;
}

Posting an Invoice

The following example shows how to post an invoice. Before starting, you must get the unique key of the target invoice record.

Code Snippet

String invoiceUniqueKey = "inv_1001"; 
protected InvoiceRepository invoiceRepository;
invoiceRepository.postInvoice(invoiceUniqueKey);

Voiding an Invoice

The following example shows how to void an invoice. Before starting, you must get the unique key of the target invoice record.

Code Snippet

String invoiceUniqueKey = "inv_1001"; 
protected InvoiceRepository invoiceRepository;
invoiceRepository.voidInvoice(invoiceUniqueKey);

Searching for Line Items

When searching for or filtering line items that are associated with an invoice, use the Invoice Repository's readInvoicesByCriteria method. In the definition of the fieldPathExpression.setSearchKeyPath, use the properties defined in the type class, LineItem, to identify which line item fields to use as search criteria.

The following example filters an invoice's line items based on associated project, fee line items, and a given timekeeper.

Code Snippet

//for this example, it is assumed that at least one invoice line item record that meets the search criterion already exists
protected InvoiceRepository invoiceRepository; public void searchInvoices() throws Exception {
    ObjectFieldCriterion fieldCriterion1 = new ObjectFieldCriterion(); 
    fieldCriterion.setComparator(ObjectComparator.EQUALS);
    LegacySearchFieldPathExpression fieldPathExpression1 = new LegacySearchFieldPathExpression();
    fieldPathExpression1.setSearchKeyPath("lineItemList.project.primaryKey"); 
    fieldCriterion1.setFieldPath(fieldPathExpression1); 
    fieldCriterion.setValue("DISP_1007");
    FieldSearchClause searchCriteria = new FieldSearchClause(); 
    searchCriteria.setOperator(LogicOperator.AND); 
    searchCriteria.getCriteria().add(fieldCriterion1);
    //the following section defines a second fieldCriterion item for filtering fee line items
    StringFieldCriterion fieldCriterion2 = new StringFieldCriterion(); 
    fieldCriterion.setComparator(StringComparator.EQUALS_ENFORCE_CASE);
    LegacySearchFieldPathExpression fieldPathExpression2 = new LegacySearchFieldPathExpression();
    fieldPathExpression2.setSearchKeyPath("lineItem.type"); 
    fieldCriterion2.setFieldPath(fieldPathExpression2); 
    fieldCriterion.setValue("FEE"); searchCriteria.getCriteria().add(fieldCriterion2);
    //the following section defines a third fieldCriterion item for filtering line items associated with a given timekeeper
    StringFieldCriterion fieldCriterion3 = new StringFieldCriterion(); 
    fieldCriterion.setComparator(StringComparator.EQUALS_ENFORCE_CASE);
    LegacySearchFieldPathExpression fieldPathExpression3 = new LegacySearchFieldPathExpression();
    fieldPathExpression3.setSearchKeyPath("lineItem.timekeeper.uniqueKey"); 
    fieldCriterion3.setFieldPath(fieldPathExpression3); 
    fieldCriterion.setValue("CONT_1010"); 
    searchCriteria.getCriteria().add(fieldCriterion3);
    List<Invoice> invoices = invoiceRepository.readInvoicesByCriteria(searchCriteria, 100, 
    getPropertiesToRead());
}
private List<String> getPropertiesToRead() { 
    List<String> properties = new List<String>(); properties.add("numberString"); 
    properties.add("invoiceDate"); 
    properties.add("vendor"); 
    properties.add("lineItems.version"); 
    properties.add("lineItems.itemNumber"); 
    properties.add("lineItems.serviceDate"); 
    properties.add("lineItems.version"); 
    properties.add("lineItems.originalRate"); 
    properties.add("lineItems.originalQuantity"); 
    properties.add("lineItems.originalDiscount"); 
    properties.add("lineItems.originalTotal"); 
    properties.add("lineItems.adjustedTotal"); 
    return properties;
}

Deleting an Invoice

The following sample deletes an invoice record. You must get the unique key value for record to delete.

Code Snippet

//for this sample it is assumed that an invoice record exists with the unique key equal to a String, uniqueKey
protected InvoiceRepository invoiceRepository; 
invoiceRepository.deleteInvoice(uniqueKey);