# July 3, 2023 

** Invoice APIs are available for Karbon Billing Beta participants. **
---

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. `GET` Invoices
2. `GET` Invoices by `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.

---

### `GET Invoices`
Endpoint: `https://api.karbonhq.com/v3/Invoices`

When used with `GET` method, this endpoint returns a list of Invoices. Optionally, this list can be sorted by `InvoiceDate` using the `$orderby` querystring parameter either newest first with `$orderby=InvoiceDate desc` or oldest first with `$orderby=InvoiceDate`

---

**Example use case**

You want to retrieve a list of the three latest invoices by invoice date:
`https://api.karbonhq.com/v3/Invoices?$orderby=InvoiceDate+desc&$top=4`

This will return a `JSON` payload with the `array` value containing a summary of invoices.

Example response:

```JSON
{
  "@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
        }
      ]
    }
  ]
}
```

### `GET Invoices by InvoiceKey`
Endpoint: `https://api.karbonhq.com/v3/Invoices/{InvoiceKey}`

To make an API call to this endpoint using `GET` method, replace `{InvoiceKey}` parameter in the URL above with a valid `InvoiceKey` (you can retrieve these using the Get Invoices endpoint).

To retrieve the line items for an invoice, use the `$expand` querystring parameter with the value `LineItems`.

---

**Example use case**

You want to retrieve an invoice along with its line items:
`https://api.karbonhq.com/v3/Invoices/{invoiceKey}?$expand=LineItems`

This will return a `JSON` response with a single invoice as the payload. Example response:

```JSON
{
  "@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 `BillableItemType` and `BillableItemEntityKey` properties which provide some indication of the **WorkItem**, **Organisation** or **Contact** the line item relates to.

Possible values of `BillableItemType` are:

* **TimeEntry** - this indicates the line item is for billed time and that `BillableItemEntityKey` could be a **WorkItem**, **Organization** or **Contact**
* **Expense** - this indicates the line item relates to a billed expense and that `BillableItemEntityKey` could be a **WorkItem**, **Organization** or **Contact**
* **Entity** - this signifies that line items is for billed work and that `BillableItemEntityKey` is a **WorkItem**

In future a `BillableItemEntityType` field will be added and will specify one of **WorkItem**, **Organisation** or **Contact** to disambiguate the related `BillableItemEntityKey` entry for `BillableItemType` **TimeEntry**.