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": "66bfb4d19ab4e3d6eb735fd2",
    "approved": true,
    "balance": 584228,
    "created": "2024-08-16 20:21:37",
    "credited_invoices": [],
    "due_date": "2024-08-12",
    "exported": true,
    "in_dispute": false,
    "invoice_type": "invoice",
    "issue_date": "2024-07-13",
    "location": "66bfb4bb9ab4e3d6eb734900",
    "location_contact": null,
    "locked": false,
    "modified": "2024-08-16 20:21:37",
    "number": "INV-0001",
    "paid": false,
    "paid_date": null,
    "reason_for_dispute": null,
    "ref": null,
    "sent": true,
    "service_user_contact": "66bfb4c19ab4e3d6eb73591c",
    "service_users": [
        "66bfb4c19ab4e3d6eb735834"
    ],
    "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.

GET
/v1/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": 4,
    "items": [
        {
            "_id": "66bfb4d19ab4e3d6eb735fd2",
            "tax_amount": 0,
            "to_company_name": "",
            "to_contact_name": "Paige Howarth",
            "total": 584228
        },
        {
            "_id": "66bfb4d19ab4e3d6eb735fd6",
            "tax_amount": 0,
            "to_company_name": "",
            "to_contact_name": "Dawn Bell",
            "total": 581610
        },
        {
            "_id": "66bfb4d19ab4e3d6eb735fd9",
            "tax_amount": 0,
            "to_company_name": "",
            "to_contact_name": "Francesca Jones",
            "total": 717900
        },
        {
            "_id": "66bfb4d19ab4e3d6eb735fdc",
            "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.

GET
/v1/invoices/<invoice_id>
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": "66bfb4d19ab4e3d6eb735fd2",
    "approved": true,
    "balance": 584228,
    "created": "2024-08-16 20:21:37",
    "credited_invoices": [],
    "due_date": "2024-08-12",
    "exported": true,
    "in_dispute": false,
    "invoice_type": "invoice",
    "issue_date": "2024-07-13",
    "location": "66bfb4bb9ab4e3d6eb734900",
    "location_contact": null,
    "locked": false,
    "modified": "2024-08-16 20:21:37",
    "number": "INV-0001",
    "paid": false,
    "paid_date": null,
    "reason_for_dispute": null,
    "ref": null,
    "sent": true,
    "service_user_contact": "66bfb4c19ab4e3d6eb73591c",
    "service_users": [
        "66bfb4c19ab4e3d6eb735834"
    ],
    "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
}