Varibill Support Desk

Integrate various external systems with Varibill’s CreateInvoice API to create Once-off Invoices in Varibill.

TABLE OF CONTENTS

• Requirements
• Invoice Data Structure
• Line Item Data Structure
• Data Formatting

Requirements

Varibill Account

A Varibill account is required to pass the login and authorization of the API. These credentials should be used to authorize the API request and allow the request to be completed.

API Application

An API application is required to send the request to Varibill to create a Once-Off Invoice. Any API application can be used, for example [Postman].

CreateInvoice API Call

The CreateInvoice API Call exists under the following path of a Varibill Environment:

{Varibill-Environment URL}/InvoicesAPI/CreateInvoice

The CreateInvoice API call is a POST method that requires the data for the Once-Off Invoice to be in the body of the request, as well as being in JSON format.

You will be required to set the following Header keys for your request to “application/json”:

• Content-Type
• Accept

Authorization

The CreateInvoice API Call makes use of Basic Authentication (Username + Password). The username and password fields need to be populated with your Varibill login credentials.

An error message will be displayed if the incorrect authorization type is used, or invalid login credentials are provided.

Invoice Data Structure

The CreateInvoice API makes use of the following data structures for Invoice Data:

Client Account Code

The ClientAccountCode field is the unique identifier to specify the client for the invoice line item. 

A valid client that exists on the Varibill tenant is required. If the client account code does not exist in Varibill, an error will be provided stating that the product cannot be found.

Invoice Date

The InvoiceDate field is used to indicate the date of the invoice. The default value is the current date when the request is sent if not provided. The following date format is required: yyyy-MM-dd (ex. 2020-04-25).

Description

The Description field is used to populate the description for the invoice. This field can be used as a custom note field, e.g. “ETA 5-10 business days”. The description field is displayed at the bottom of the invoice.  

Payment Terms

The PaymentTerms field is used to calculate the due date for the invoice, in days after the invoice date. If not provided, the due date will be the same date as the Invoice Date.  

Line Item Data Structure

The CreateInvoice API makes use of the following data structures for Line Item Data:

Product Code

The ProductCode field is the unique identifier to specify the product for the invoice line item. A valid product code that exists on the Varibill tenant is required. If the product code does not exist in Varibill, an error will be provided stating that the product cannot be found.

Quantity

The Quantity field is used to indicate the product quantity for the line item. A valid decimal value is required. If no value is provided, then the value of 0 will be used.

Unit Rate

The UnitRate field is used to indicate the product’s unit rate for the invoice line item. A valid decimal value is required. If no value is provided, then the value of 0 will be used.

Salesperson Employee Number

The SalespersonEmployeeNumber field is used to indicate the relevant salesperson to the invoice line item. This field is not displayed on the invoice but can be used for reporting purposes, for example Salesperson Commission).

A valid salesperson employee number that exists on the Varibill tenant is required. If the salesperson does not exist in Varibill, an error will be provided stating that the salesperson cannot be found.

Product Description

The ProductDescription field is used to populate the description for the invoice line item. The description is displayed when expanding the line item. If a description is not provided, then the product name of the line item will be used.

Line Item Grouping

Line Item Grouping will apply if multiple line items with the same product, unit rate and salesperson are provided.  Line item grouping combines these multiple items into a single line item - that can be expanded on the invoice to show them individually.

Data Formatting

The CreateInvoice API Call is a Post method. The required data to create the Once-Off Invoice should be provided in JSON format in the body of the request.

Example of the JSON data format:

It is also important to ensure that no unintended characters are present in the invoice, such as spaces, additional commas, etc. If invalid data is provided, an error will be provided, indicating the line and position of the data containing an error.

Sample Rest Call

{
  "clientAccountCode": "THE004",
  "invoiceDate": "2022-06-12T09:56:42.298Z",
  "paymentTerms": 30,
  "description": "Desc",
  "purchaseOrder": "PO",
  "salesPersonCode": "",
  "LineItems": [
      {
        "productCode": "PTT1",
        "quantity": 123.456,
        "unitRate": 9.87654321,
        "SalesPersonCode": "",
        "productDescription" : "PD"
      }
  ]
}