List invoices

GET

/invoices/

const url = 'https://app.commitly.com/api/invoices/?type=receivable&status=OD&page_size=100';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://app.commitly.com/api/invoices/?type=receivable&status=OD&page_size=100' \
  --header 'Authorization: Bearer <token>'

Returns the invoices (open items) of the company, together with the total amount and the total amount due.

Note the response shape: results is an object containing the totals and the invoices array, not an array.

Authorizations

commitlyOAuth

Parameters

Query Parameters

reference

string

Substring match on the invoice number (case-insensitive): RE-1 also matches RE-10. For exact selection use ids or source_ids.

ids

string

Comma-separated internal invoice IDs (exact match).

source_ids

string

Comma-separated source_id values (exact match).

type

string

Allowed values: receivable payable

receivable (type RE) or payable (type PA).

paid

boolean

true returns paid invoices only, false unpaid invoices only.

overdue

boolean

Filter on overdue invoices.

matched

boolean

Filter on invoices matched to bank transactions.

status

Code	Label
`OD`	Overdue
`PL`	Expected
`OR`	Lead/Order
`PD`	Paid
`PP`	Partially Paid
`IN`	Installments
`HD`	On Hold
`PR`	Promised
`DP`	In Dispute
`CA`	Cancelled
`IP`	In Progress

string

Allowed values: OD PL OR PD PP IN HD PR DP CA IP

Invoice status code (see status in Invoice).

status_include

string

Status codes to include (see status in Invoice).

status_exclude

string

Status codes to exclude (see status in Invoice).

ordering

string

Sort order. Allowed fields: amount, date, due_date, status, status_predefined, expected_date, name, reference. Prefix a field with - for descending order; separate several fields with commas. Default: status_predefined,-expected_date.

page

integer

>= 1

Page number, starting at 1. When paging through results, read this value from the next link and send it to the documented base URL.

page_size

integer

default: 100 >= 1 <= 1000

Number of records per page. Default 100, maximum 1000; larger values are reduced to 1000.

Responses

200

Paginated invoice list with totals.

application/json

object

count

required

Total number of matching records.

integer

next

required

URL of the next page, or null on the last page. The host name may differ from the documented base URL; read page from it and call the documented base URL.

string | null format: uri

previous

required

URL of the previous page, or null on the first page.

string | null format: uri

sum

Sum of the amounts of all matching invoices.

number

results

Totals and the invoices of the current page.

object

amount_due

Total amount due of all matching invoices.

number

total

Total amount of all matching invoices.

number

invoices

Array<object>

object

Internal invoice ID. Used in /invoices/{id}/ and as id selector.

integer

transactions

Bank transactions matched to the invoice.

Array<object>

A bank transaction matched to the invoice.

object

integer

account

Bank account of the transaction.

value_date

string

amount

number

purpose

string

counterpart_name

string

reporting_amount

number

paid_amount

number

amount_due

number

date_created

string format: date-time

date_updated

string format: date-time

name

string

notes

string

amount

Decimal with at most 10 digits and 2 decimal places.

number

type

RE receivable, PA payable. Optional on create: if omitted, a positive amount sets RE, any other amount PA.

string

Allowed values: RE PA

reference

Invoice number.

string

date

Invoice date.

string format: date

due_date

string format: date

expected_date

Expected payment date.

string format: date

source

Origin of the invoice, e.g. direct_api or Manually Added.

string

source_id

ID of the invoice in its source.

string

status

Code	Label
`OD`	Overdue
`PL`	Expected
`OR`	Lead/Order
`PD`	Paid
`PP`	Partially Paid
`IN`	Installments
`HD`	On Hold
`PR`	Promised
`DP`	In Dispute
`CA`	Cancelled
`IP`	In Progress

string

Allowed values: OD PL OR PD PP IN HD PR DP CA IP

status_label

Label of status, e.g. Expected.

string

is_archived

boolean

category

Category ID.

integer | null

comment_count

Present in list responses.

integer

Examples

InvoicePage

Invoice list

{
  "count": 2,
  "sum": 8650,
  "next": null,
  "previous": null,
  "results": {
    "amount_due": 7650,
    "total": 8650,
    "invoices": [
      {
        "id": 3101,
        "transactions": [],
        "paid_amount": 1000,
        "amount_due": 200,
        "date_created": "2022-04-16T09:36:37.718400Z",
        "date_updated": "2022-04-16T10:12:17.687693Z",
        "name": "First invoice",
        "notes": "",
        "amount": 1200,
        "type": "RE",
        "reference": "1",
        "date": "2022-04-16",
        "due_date": "2022-04-30",
        "source": "Manually Added",
        "source_id": "00000000-0000-4000-8000-000000000001",
        "status": "PP",
        "status_label": "Partially Paid",
        "is_archived": false,
        "category": 1002,
        "comment_count": 0
      },
      {
        "id": 3102,
        "transactions": [],
        "paid_amount": 0,
        "amount_due": 7450,
        "date_created": "2022-04-16T09:53:03.919398Z",
        "date_updated": "2022-04-16T09:53:03.919422Z",
        "name": "Equipment",
        "notes": "Special equipment",
        "amount": 7450,
        "type": "RE",
        "reference": "AR-007",
        "date": "2022-04-16",
        "due_date": "2022-04-28",
        "source": "direct_api",
        "source_id": "00000000-0000-4000-8000-000000000002",
        "status": "PL",
        "status_label": "Expected",
        "is_archived": false,
        "category": 1002,
        "comment_count": 0
      }
    ]
  }
}

401

The access token is invalid or has expired. Request a new token. The message is localized (see Accept-Language).

application/json

object

detail

required

Error message.

string

code

Present only if the company’s edition does not include the function; value billing_plan_permission_denied.

string

Example

{
  "detail": "Invalid token."
}

Headers

WWW-Authenticate

string

Authentication scheme, Bearer.

Example

Bearer

403

No access token was sent, or the credentials are not allowed to call this endpoint. If the company’s COMMITLY edition does not include the requested function, the body additionally contains "code": "billing_plan_permission_denied".

application/json

object

detail

required

Error message.

string

code

Present only if the company’s edition does not include the function; value billing_plan_permission_denied.

string

Example

{
  "detail": "User must be authenticated to access this resource."
}