July 3, 2023

This document provides an overview of the July 3, 2023 Karbon API release

We have created API endpoints that make it possible to list and retrieve invoices and their associated line items.

1. JSONCopyCopied!

   GET
   Invoices
2. JSONCopyCopied!

   GET
   Invoices by
   JSONCopyCopied!

   InvoiceKey

Note that draft invoices will not be returned by these APIs, i.e. an invoice must have been approved before it will be returned.

---

JSONCopyCopied!

GET Invoices

Endpoint:

When used with

method, this endpoint returns a list of Invoices. Optionally, this list can be sorted by using the querystring parameter either newest first with or oldest first with

---

Example use case

You want to retrieve a list of the three latest invoices by invoice date:

This will return a

payload with the value containing a summary of invoices.

Example response:

JSONCopyCopied!
{
  "@odata.context": "https://api.karbonhq.com/v3/$metadata#Invoices",
  "@odata.count": 2,
  "value": [
    {
      "InvoiceKey": "4cRZ9SZfcVd1",
      "InvoiceNumber": "KIN-1007",
      "TotalAmountDue": 204.1300,
      "InvoiceTotal": 204.1300,
      "InvoiceSubTotal": 177.5000,
      "InvoiceTaxTotal": 26.6300,
      "InvoiceDate": "2023-06-21T00:00:00Z",
      "PaymentDueDate": "2023-06-28T00:00:00Z",
      "UpdatedAt": "2023-06-20T21:47:08Z",
      "CurrencyCode": "USD",
      "PaymentInstructions": "Please pay within 7 days of invoice",
      "InvoiceStatus": "Approved",
      "Client": {
        "ClientKey": "2Vpt3MBbhWf2",
        "ClientType": "Contact",
        "Name": "John Smith",
        "AddressLine": "13 Example Street",
        "City": "Exampletown",
        "StateProvinceCounty": null,
        "ZipCode": "10001",
        "Country": "USA",
        "EmailAddress": "john@example.com"
      },
      "TaxLineItems": [
        {
          "TaxName": "Example Tax",
          "TaxValue": 26.6300
        }
      ]
    },
    {
      "InvoiceKey": "kGsxczWThdz",
      "InvoiceNumber": "KIN-1006",
      "TotalAmountDue": 904.4800,
      "InvoiceTotal": 904.4800,
      "InvoiceSubTotal": 786.5000,
      "InvoiceTaxTotal": 117.9800,
      "InvoiceDate": "2023-06-13T00:00:00Z",
      "PaymentDueDate": "2023-06-20T00:00:00Z",
      "UpdatedAt": "2023-06-12T20:54:17Z",
      "CurrencyCode": "USD",
      "PaymentInstructions": "Payment due 7 days from invoice date",
      "InvoiceStatus": "Approved",
      "Client": {
        "ClientKey": "2xxnBLyCP4Ts",
        "ClientType": "Organization",
        "Name": "Pickle Jar",
        "AddressLine": "13 Sample St",
        "City": "New York",
        "StateProvinceCounty": "NY",
        "ZipCode": "10121",
        "Country": "USA",
        "EmailAddress": "pickle@example.com"
      },
      "TaxLineItems": [
        {
          "TaxName": "Example Tax",
          "TaxValue": 117.9800
        }
      ]
    }
  ]
}

JSONCopyCopied!

GET Invoices by InvoiceKey

Endpoint:

To make an API call to this endpoint using

method, replace parameter in the URL above with a valid (you can retrieve these using the Get Invoices endpoint).

To retrieve the line items for an invoice, use the

querystring parameter with the value .

---

Example use case

You want to retrieve an invoice along with its line items:

This will return a

response with a single invoice as the payload. Example response:

JSONCopyCopied!
{
  "@odata.context": "https://api.karbonhq.com/v3/$metadata#Invoices(LineItems())/$entity",
  "InvoiceKey": "kGsxczWThdz",
  "InvoiceNumber": "KIN-1006",
  "TotalAmountDue": 904.4800,
  "InvoiceTotal": 904.4800,
  "InvoiceSubTotal": 786.5000,
  "InvoiceTaxTotal": 117.9800,
  "InvoiceDate": "2023-06-13T00:00:00Z",
  "PaymentDueDate": "2023-06-20T00:00:00Z",
  "UpdatedAt": "2023-06-12T20:54:17Z",
  "CurrencyCode": "USD",
  "PaymentInstructions": "Payment due within 7 days of invoice date",
  "InvoiceStatus": "Approved",
  "Client": {
    "ClientKey": "2xxnBLyCP4Ts",
    "ClientType": "Organization",
    "Name": "Pickle Jar",
    "AddressLine": "13 Sample St",
    "City": "New York",
    "StateProvinceCounty": "NY",
    "ZipCode": "10121",
    "Country": "USA",
    "EmailAddress": "pickle@example.com"
  },
  "TaxLineItems": [
    {
      "TaxName": "Example Tax",
      "TaxValue": 117.9800
    }
  ],
  "LineItems": [
    {
      "LineItemKey": "c0519b34efe04deeaf0f0d27e35f45b8",
      "BillableItemEntityKey": "xcPnwGBQDjz",
      "BillableItemType": "Expense",
      "Description": "Filing Fees",
      "Quantity": 1,
      "UnitPrice": 124.0000,
      "Amount": 124.00,
      "TaxRate": 15.000000,
      "TaxRateName": "Example Tax",
      "TaxTotal": 0.0000
    },
    {
      "LineItemKey": "8c98b28fdbe84010b91f6fec837a2770",
      "BillableItemEntityKey": "LL8dRNhN1nz",
      "BillableItemType": "TimeEntry",
      "Description": "Time and materials work",
      "Quantity": 1,
      "UnitPrice": 502.5000,
      "Amount": 502.50,
      "TaxRate": 15.000000,
      "TaxRateName": "Example Tax",
      "TaxTotal": 0.0000
    },
    {
      "LineItemKey": "4a147edf9af54228881a80eb411a1320",
      "BillableItemEntityKey": "LL8dRNhN1nz",
      "BillableItemType": "Expense",
      "Description": "Scanning, printing and copying",
      "Quantity": 1,
      "UnitPrice": 160.0000,
      "Amount": 160.00,
      "TaxRate": 15.000000,
      "TaxRateName": "Example Tax",
      "TaxTotal": 0.0000
    }
  ]
}

---

Note on invoice line items

Each line item contains a set of properties that describe where it came from and its value. Notable are the

and properties which provide some indication of the WorkItem, Organisation or Contact the line item relates to.

Possible values of

are:

• TimeEntry - this indicates the line item is for billed time and that
  JSONCopyCopied!

  BillableItemEntityKey
  could be a WorkItem, Organization or Contact
• Expense - this indicates the line item relates to a billed expense and that
  JSONCopyCopied!

  BillableItemEntityKey
  could be a WorkItem, Organization or Contact
• Entity - this signifies that line items is for billed work and that
  JSONCopyCopied!

  BillableItemEntityKey
  is a WorkItem

In future a

field will be added and will specify one of WorkItem, Organisation or Contact to disambiguate the related entry for TimeEntry.