Skip to content
Developerhome
Product homepage
Accounting
API Status:

Checking…

Line Items

  Less than to read

Entities such as invoices are composed of general information such as supplier details, date, terms, tax etc. and then one or more lines that contain the detail of what is being invoiced.

These lines are called line items and can be created, read, updated and deleted. There are various areas that contain line items. This includes:

  • Sales Estimates
  • Sales Quote
  • Sales Invoices
  • Sales Credits
  • Purchase Invoices
  • Purchase Credits
  • Journals

When working with line items it is important to consider what other information you need before you will be able to POST or PUT a transaction.

Examples

Sales Estimate

The API Reference of available endpoints provides examples of posting transactions and artefacts containing line items. For example, the Sales Estimates POST example, documents attributes for estimate_lines and contains descriptions of the attributes along with a label of required, should the attribute be included for a successful POST.

From the documentation we can see that there are a number of different attribute id’s that can be added to build the detail of the estimate line but only the ledger_id is a required attribute value. Other id’s may become required should certain attribute values be set. For example, if there is a value set for the tax_amount, it is then a requirement for the tax_rate_id to be passed.

{
  ...
  "estimate_lines": [
    {
      "product_id": "2facaa7955446248f3a7d2611c634ff7",
      "description": "Line Item A",
      "ledger_account_id": "24491d9822f411e99fa3125ed179890c",
      "quantity": 2,
      "trade_of_asset": false,
      "unit_price": 55,
      "discount_amount": 10,
      "tax_rate_id": "CA_GST",
      "tax_amount": 5
    }
  ],
  ...
}

Here you may pass the ledger_account_id (nominal code), product_id or service_id (for the specific product or service to appear on that line), the tax_rate_id (the id for the specific tax code or rate to be applied to this line) and if applicable the eu_goods_services_type_id (used when trading within the EU). In order to GET the ledger_account_id, you would perform a GET request:

GET /ledger_accounts?visible_in=sales

The response will show you each ledger account like this:

{
  "$total": 10,
  "$page": 1,
  "$next": null,
  "$back": null,
  "$itemsPerPage": 20,
  "$items": [
    {
      "id": "24491d9822f411e99fa3125ed179890c",
      "displayed_as": "Sales - Products (4000)",
      "$path": "/ledger_accounts/24491d9822f411e99fa3125ed179890c"
    },
    {
      "id": "2449207322f411e99fa3125ed179890c",
      "displayed_as": "Sales Discounts (4100)",
      "$path": "/ledger_accounts/2449207322f411e99fa3125ed179890c"
    },
    {
      "id": "2449236622f411e99fa3125ed179890c",
      "displayed_as": "Shipping Revenue (4150)",
      "$path": "/ledger_accounts/2449236622f411e99fa3125ed179890c"
    },
    ...
  ]
}

Ledger Account descriptions and codes are not commonly edited after the initial setup which means that the data is unlikely to change. This provides an opportunity to improve efficiency and reduce the number of API requests made.

Products

It would be the same process to obtain the ids for your products or services using either the /products or /services endpoints.

Below is a consideration when creating an invoice line, you can specify one of the three potential sales price types as shown below:

{
  "$total": 3,
  "$page": 1,
  "$next": null,
  "$back": null,
  "$itemsPerPage": 20,
  "$items": [
    {
      "id": "bf2424844a9111e797950a57719b2edb",
      "displayed_as": "Sales Price",
      "$path": "/product_sales_price_types/bf2424844a9111e797950a57719b2edb"
    },
    {
      "id": "bf26959b4a9111e797950a57719b2edb",
      "displayed_as": "Trade",
      "$path": "/product_sales_price_types/bf26959b4a9111e797950a57719b2edb"
    },
    {
      "id": "bf2718fe4a9111e797950a57719b2edb",
      "displayed_as": "Wholesale",
      "$path": "/product_sales_price_types/bf2718fe4a9111e797950a57719b2edb"
    }
  ]
}

Tax Rates

When processing a line item, it will be a requirement to specify a tax element regardless of whether it is exempt, zero rated or a standard rated.

You do not specify that percentage (0%, 5%, 20% for example) when setting the line item, instead you are required to specify the id of the tax rate that has been setup for this business.

The API can be used to determine the options for tax rates by performing a GET request:

GET /tax_rates

An example response:

{
  "$total": 5,
  "$page": 1,
  "$next": null,
  "$back": null,
  "$itemsPerPage": 20,
  "$items": [
    {
      "id": "GB_STANDARD",
      "displayed_as": "Standard 20.00%",
      "$path": "/tax_rates/GB_STANDARD"
    },
    {
      "id": "GB_LOWER",
      "displayed_as": "Lower Rate 5.00%",
      "$path": "/tax_rates/GB_LOWER"
    },
    {
      "id": "GB_ZERO",
      "displayed_as": "Zero Rated 0.00%",
      "$path": "/tax_rates/GB_ZERO"
    },
    {
      "id": "GB_EXEMPT",
      "displayed_as": "Exempt 0.00%",
      "$path": "/tax_rates/GB_EXEMPT"
    },
    {
      "id": "GB_NO_TAX",
      "displayed_as": "No VAT",
      "$path": "/tax_rates/GB_NO_TAX"
    }
  ]
}

The appropriate id can then be used when a POST request is made for each line item. It is important to note that the VAT is rounded on a per line basis, and then totalled.

Discounts

It is possible to set a discount for a line item on an invoice for example. An example of a minimal invoice line:

POST /sales_invoices
Content-Type: application/json

{
  "sales_invoice": {
    ...
    "invoice_lines": [
      {
        "description": "An invoice item with a value discount",
        "ledger_account_id": "4195173e75db11e8990a122c8428e4b2",
        "quantity": "1",
        "unit_price": "110.00",
        "tax_rate_id": "584793ca75db11e8990a122c8428e4b2",
        "discount_amount": "10.00",
        "tax_amount": "9.95"
      }
    ]
  }
}

In the above example you can see the discount_amount of 10.00. If the scope of your app requires the ability to enter a discount percentage, the value must be calculated by your app and passed as a value of the discount_amount attribute.

When selling goods in the EU, it is a requirement to specify whether an invoice line is a sale of either goods or services. This can be stated when making a PUT or POST request on a line as below:

{
  ...
  "invoice_lines": [
    {
      "product_id": "92b7697e4a9211e797950a57719b2edb",
      "description": "Line 1",
      "ledger_account_id": "bf15fce94a9111e797950a57719b2edb",
      "quantity": "2",
      "unit_price": "100",
      "net_amount": "100",
      "tax_rate_id": "GB_STANDARD",
      "tax_amount": "20",
      "discount_amount": "10.00",
      "eu_goods_services_type_id": "GOODS"
    }
  ],
  ...
}

Editing existing lines

Once you have an invoice or estimate posted and need to alter or correct something on a line item, it is possible to make a PUT request, and specify the desired result. This means that you cannot simply make a PUT request using just the lines you wish to change but need to specify everything that is correct also. It can be thought of as making a POST request for the first time correctly but using PUT.

For example:

If a sales invoice is posted:

{
  "sales_invoice": {
    "reference": "SI-123456",
    "date": "24-02-2018",
    "due_date": "24-03-2018",
    "contact_id": "6c865d104a9211e797950a57719b2edb",
    "main_address": {
      "address_line_1": "Line 1",
      "address_line_2": "Line 2",
      "city": "City",
      "region": "Region"
    },
    "delivery_address": {
      "name": "Delivery Office",
      "address_line_1": "A building",
      "address_line_2": "A street",
      "city": "A city",
      "address_type_id": "DELIVERY"
    },
    "invoice_lines": [
      {
        "product_id": "92b7697e4a9211e797950a57719b2edb",
        "description": "Line 1",
        "ledger_account_id": "bf15fce94a9111e797950a57719b2edb",
        "quantity": "2",
        "unit_price": "100",
        "net_amount": "100",
        "tax_rate_id": "GB_STANDARD",
        "tax_amount": "20",
        "discount_amount": "10.00",
        "eu_goods_services_type_id": "GOODS"
      },
      {
        "product_id": "a002176d329f11e8b45c025132dab352",
        "description": "Line 2",
        "ledger_account_id": "bf15fce94a9111e797950a57719b2edb",
        "quantity": "2",
        "unit_price": "100",
        "net_amount": "100",
        "tax_rate_id": "GB_STANDARD",
        "tax_amount": "20",
        "discount_amount": "10.00",
        "eu_goods_services_type_id": "SERVICES"
      }
    ]
  }
}

Once posted you notice that the description on your product line needs to be changed, you must make a PUT with all of the same JSON you used when making the POST but altering the description.

PUT /sales_invoices/{id}
Content-Type: application/json

{
  "sales_invoice": {
    "reference": "SI-123456",
    "date": "24-02-2018",
    "due_date": "24-03-2018",
    "contact_id": "6c865d104a9211e797950a57719b2edb",
    "main_address": {
      "address_line_1": "Line 1",
      "address_line_2": "Line 2",
      "city": "City",
      "region": "Region"
    },
    "delivery_address": {
      "name": "Delivery Office",
      "address_line_1": "A building",
      "address_line_2": "A street",
      "city": "A city",
      "address_type_id": "DELIVERY"
    },
    "invoice_lines": [
      {
        "product_id": "92b7697e4a9211e797950a57719b2edb",
        "description": "Line 1",
        "ledger_account_id": "bf15fce94a9111e797950a57719b2edb",
        "quantity": "2",
        "unit_price": "100",
        "net_amount": "100",
        "tax_rate_id": "GB_STANDARD",
        "tax_amount": "20",
        "discount_amount": "10.00",
        "eu_goods_services_type_id": "GOODS"
      },
      {
        "product_id": "a002176d329f11e8b45c025132dab352",
        "description": "**CORRECTION TO DESCRIPTION**",
        "ledger_account_id": "bf15fce94a9111e797950a57719b2edb",
        "quantity": "2",
        "unit_price": "100",
        "net_amount": "100",
        "tax_rate_id": "GB_STANDARD",
        "tax_amount": "20",
        "discount_amount": "10.00",
        "eu_goods_services_type_id": "SERVICES"
      }
    ]
  }
}

Its is also possible to specify a negative value item lines, for example users in the Spanish region do not have access to credit notes and so must create corrective invoices which use negative item line values.

Deleting an item line

If you wanted to delete a line, the same process applies – simply make a PUT request to the id of the invoice, omitting the line you no longer require.

Analysis Codes

It is currently not possible to add analysis codes such as Cost Centre and Department details on line items, but support for this may be added in the future.