Invoices

An invoice. Invoices are raised against service users and typically cover the cost of .

The invoices object

Attributes

_id
string

A unique Id for the invoice item type code.
approved
boolean

Flag indicating if the invoice is approved (if not approved the invoice is considered draft).
balance
integer

The balance remaining unpaid against the invoice (in pence).
created
string

The date/time the invoice item type was created.
credited_invoices
list of strings

A list of invoices the credit note has been allocated against.
due_date
string

The date at which the invoice is due.
exported
boolean

Flag indicating if the invoice has been exported to the external accounts package.
in_dispute
boolean

Flag indicating the invoice is currently in dispute.
invoice_type
string

The type of invoice; forcredit_note, invoice, overpayment.
issue_date
string

The date at which the invoice was issued.
location
string

The location that raised the invoice.
location_contact
string

The location contact the invoice was issued to.
locked
boolean

Flag indicating if the invoice has been exported to the external accounts package via an integration, once synced in this way the invoice cannot be reverted from the exported state and therefore cannot be updated afterwards.
modified
string

The date/time the invoice item type was modified.
number
string

A unique number for the invoice.
paid
boolean

Flag indicating if the invoice has been paid.
paid_date
string

The date the invoice was paid.
reason_for_dispute
string

A description of why the invoice is currently in dispute.
ref
string

A reference for the invoice.
sent
boolean

Flag indicating if the invoice has been sent (to the client).
service_user_contact
string

The service user contact the invoice was issued to.
service_users
list of strings

A list of service users the invoice relates to.
subtotal
integer

The subtotal (total excluding tax) (in pence).
to_account_code
string

The account code of the billing party the invoice was raised for.
to_address
hash

The address of the billing party invoice was raised for.
- to_address.address_1
  string
  
  Address line 1 (e.g. house name/number).
- to_address.address_2
  string
  
  Address line 2 (e.g. street).
- to_address.town
  string
  
  Town, city or village.
- to_address.county
  string
  
  County.
- to_address.postcode
  string
  
  Postal code.
- to_address.country
  string
  
  Country.
to_company_name
string

The name of the billing party company the invoice was raised for.
to_contact_name
string

The name of the billing party contact the invoice was raised for.
to_email
string

The email address of the billing party the invoice was raised for.
to_payment_method
string

The payment method of the billing party the invoice was raisedfor; card, cash, cheque, standing_order, direct_debit, bac.
total
integer

The total (total including tax) (in pence).
void
boolean

Flag indicating if the invoice has been voided.
with_self
boolean

Flag indicating if the invoice was raised for the service user.

The invoices object

{
    "_id": "6724fbd04f73a2cebf638ee8",
    "approved": true,
    "balance": 584228,
    "created": "2024-11-01 16:03:28",
    "credited_invoices": [],
    "due_date": "2024-10-28",
    "exported": true,
    "in_dispute": false,
    "invoice_type": "invoice",
    "issue_date": "2024-09-28",
    "location": "6724fbc74f73a2cebf6377fa",
    "location_contact": null,
    "locked": false,
    "modified": "2024-11-01 16:03:28",
    "number": "INV-0001",
    "paid": false,
    "paid_date": null,
    "reason_for_dispute": null,
    "ref": null,
    "sent": true,
    "service_user_contact": "6724fbcb4f73a2cebf638816",
    "service_users": [
        "6724fbca4f73a2cebf63872e"
    ],
    "subtotal": 584228,
    "tax_amount": 0,
    "to_account_code": "PH0472",
    "to_address": null,
    "to_company_name": "",
    "to_contact_name": "Paige Howarth",
    "to_email": "paige.howarth@gmail.com",
    "to_payment_method": "",
    "total": 584228,
    "void": false,
    "with_self": false
}

List all invoices

Return a list of invoices.

Parameters

attributes
optional

default ['_id']

A list of attributes to include for fetched objects.
filters-end_date
optional

A filter that accepts a date and filters invoices to those issued before the given date.
filters-ids
optional

A filter that accepts a list of Ids and filters the items returned to those with an Id in the list.
filters-location
optional

A filter that accepts a list of location Ids and filters invoices by the location they relate to.
filters-location_contact
optional

A filter that accepts a list of location contact Ids and filters invoices to those where the billing party is one of the location contacts.
filters-max_amount
optional

A filter that accepts a fee (in pence) and filters invoices to those with a total equal to or less than the given fee.
filters-min_amount
optional

A filter that accepts a fee (in pence) and filters invoices to those with a total equal to or higher than the given fee.
filters-modified_after
optional

A filter that accepts a date/time and filters the items returned to those modified after the date/time.
filters-modified_before
optional

A filter that accepts a date/time and filters the items returned to those modified before the date/time.
filters-q
optional

A case insensitive keyword filter applied to the following fields; number, ref, to_company_name, to_contact_name.
filters-service_user
optional

A filter that accepts a list of service user Ids and filters invoices by the service user they are for.
filters-service_user_contact
optional

A filter that accepts a list of service user contact Ids and filters invoices to those where the billing party is one of the service user contacts.
filters-start_date
optional

A filter that accepts a date and filters invoices to those issued after the given date.
filters-with_self
optional

default unset

A filter that allows invoices to be filtered by whether the invoice is with the associated service users.
- unset
- yes
- no
page
optional

default 1

The page number to fetch.
per_page
optional

default 10

The number of items to return per page.
sort_by
optional

default _id

A list of fields the returned items can be sorted by. Fields prefixed with minus (-) sign are sorted in descending order.
- _id
- created
- due_date
- issue_date
- modified

Response

Returns a page of invoices.

var invoices = apiClient.Request(
    HttpMethod.Get,
    "invoices",
    new MultiValueDict()
        .Add("attributes", "to_company_name", "to_contact_name", "total")
);

<?php

$invoices = $api_client->request(
    'GET',
    'invoices',
    [
        'attributes'=>['to_company_name', 'to_contact_name', 'total']
    ]
);

invoices = api_client(
    'GET',
    'invoices',
    params={
        'attributes': ['to_company_name', 'to_contact_name', 'total']
    }
)

invoices = api_client.request(
    'GET',
    'invoices',
    params: {
        'attributes' => ['to_company_name', 'to_contact_name', 'total']
    }
)

Response

{
    "item_count": 5,
    "items": [
        {
            "_id": "6724fbd04f73a2cebf638ee8",
            "tax_amount": 0,
            "to_company_name": "",
            "to_contact_name": "Paige Howarth",
            "total": 584228
        },
        {
            "_id": "6724fbd04f73a2cebf638eec",
            "tax_amount": 0,
            "to_company_name": "",
            "to_contact_name": "Dawn Bell",
            "total": 581610
        },
        {
            "_id": "6724fbd04f73a2cebf638eef",
            "tax_amount": 0,
            "to_company_name": "Oxfordshire County Council",
            "to_contact_name": "Michael Frey",
            "total": 92588
        },
        {
            "_id": "6724fbd04f73a2cebf638ef2",
            "tax_amount": 0,
            "to_company_name": "",
            "to_contact_name": "Francesca Jones",
            "total": 717900
        },
        {
            "_id": "6724fbd04f73a2cebf638ef5",
            "tax_amount": 0,
            "to_company_name": "",
            "to_contact_name": "Francesca Jones",
            "total": 717900
        }
    ],
    "page": 1,
    "page_count": 1,
    "per_page": 10
}

Retrieve an invoice

Retrieve an invoice object.

Response

Returns a invoice object.

var invoice = apiClient.Request(HttpMethod.Get, $"invoices/{invoiceId}")

<?php

$invoice = $api_client->request('GET', 'invoices/' . $invoice_id);

invoice = api_client(
    'GET',
    f'invoices/{invoice_id}')

invoice = api_client.request('GET', "invoices/#{invoice_id}")

Response

{
    "_id": "6724fbd04f73a2cebf638ee8",
    "approved": true,
    "balance": 584228,
    "created": "2024-11-01 16:03:28",
    "credited_invoices": [],
    "due_date": "2024-10-28",
    "exported": true,
    "in_dispute": false,
    "invoice_type": "invoice",
    "issue_date": "2024-09-28",
    "location": "6724fbc74f73a2cebf6377fa",
    "location_contact": null,
    "locked": false,
    "modified": "2024-11-01 16:03:28",
    "number": "INV-0001",
    "paid": false,
    "paid_date": null,
    "reason_for_dispute": null,
    "ref": null,
    "sent": true,
    "service_user_contact": "6724fbcb4f73a2cebf638816",
    "service_users": [
        "6724fbca4f73a2cebf63872e"
    ],
    "subtotal": 584228,
    "tax_amount": 0,
    "to_account_code": "PH0472",
    "to_address": null,
    "to_company_name": "",
    "to_contact_name": "Paige Howarth",
    "to_email": "paige.howarth@gmail.com",
    "to_payment_method": "",
    "total": 584228,
    "void": false,
    "with_self": false
}