INinvoiceninja
invoices

List invoices

Changed on

GET /api/v1/invoices

Lists invoices with the option to chain multiple query parameters allowing fine grained filtering of the list.

get/api/v1/invoices

Request

Query parameters

includestring
Example:first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

indexstring
Example:user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
per_pageinteger
Example:20

The number of records to return for each request, default is 20

pageinteger
Example:1

The page number to return for this request (when performing pagination), default is 1

sortstring[]

Order the list by choosing a column and direction. Each value uses the form column|asc or column|desc.

Single sort — for example sort=balance|desc.

Multiple sorts — use sort[] for each level in priority order, for example
sort[]=id|desc&sort[]=number|asc.

Invoices accept columns on the invoices table, relationship-style keys such as client.name, client_id, documents, project_id, and prefixed client.* / contact.* sorts where the filter supports them. number and status_id have special handling. Unsupported keys are ignored.

[
  "number|asc",
  "balance|desc"
]
statusstring

Filter the entity based on their status. ie active / archived / deleted. Format is a comma separated string with any of the following options:

  • active
  • archived
  • deleted
GET /api/v1/invoices?status=archived,deleted
Returns only archived and deleted invoices
client_idstring

Filters the entity list by client_id. Suitable when you only want the entities of a specific client.

GET /api/v1/invoices?client_id=AxB7Hjk9
Returns only invoices for the specified client
created_atinteger

Filters the entity list by the created at timestamp. Parameter value can be a datetime string or unix timestamp

GET /api/v1/invoices?created_at=2022-01-10
Returns entities created on January 10th, 2022
updated_atinteger

Filters the entity list by the updated at timestamp. Parameter value can be a datetime string or unix timestamp

GET /api/v1/invoices?updated_at=2022-01-10
Returns entities last updated on January 10th, 2022
is_deletedboolean

Filters the entity list by entities that have been deleted.

GET /api/v1/invoices?is_deleted=true
Returns only soft-deleted entities
filter_deleted_clientsstring

Filters the entity list and only returns entities for clients that have not been deleted

GET /api/v1/invoices?filter_deleted_clients=true
Returns only invoices for active (non-deleted) clients
vendor_idstring

Filters the entity list by an associated vendor

GET /api/v1/purchases?vendor_id=AxB7Hjk9
Returns only purchases for the specified vendor
client_statusstring

A comma separated list of invoice status strings. Valid options include:

  • all
  • paid
  • unpaid
  • overdue
numberstring

Search invoices by invoice number

filterstring

Searches across a range of columns including:

  • number
  • po_number
  • date
  • amount
  • balance
  • custom_value1
  • custom_value2
  • custom_value3
  • custom_value4
  • client.name
  • client.contacts.[first_name, last_name, email]
  • line_items.[product_key, notes]
without_deleted_clientsstring

Returns the invoice list without the invoices of deleted clients.

overduestring

Returns the list of invoices that are overdue

payablestring

Returns the invoice list that are payable for a defined client. Please note, you must pass the client_id as the value for this query parameter

private_notesstring

Searches on the private_notes field of the invoices

datestring

Filters the invoices by invoice date returns a list of invoices after (and including) the date

date_rangestring

Filters the invoices by invoice date returns a list of invoices between two dates

status_idinteger

Filters the invoices by status id

  STATUS_DRAFT = 1;
  STATUS_SENT = 2;
  STATUS_PARTIAL = 3;
  STATUS_PAID = 4;
  STATUS_CANCELLED = 5;
  STATUS_REVERSED = 6;

Headers

X-API-TOKENstring required
Example:TOKEN

The API token to be used for authentication

X-Requested-Withstring required
Example:XMLHttpRequest

Used to send the XMLHttpRequest header

Response

A list of invoices

Example response

{
  "data": [
    {
      "id": "Opnel5aKBz",
      "user_id": "Opnel5aKBz",
      "assigned_user_id": "Opnel5aKBz",
      "client_id": "Opnel5aKBz",
      "status_id": "4",
      "number": "INV_101",
      "po_number": "PO-1234",
      "terms": "These are invoice terms",
      "public_notes": "These are some public notes",
      "private_notes": "These are some private notes",
      "custom_value1": "2022-10-01",
      "custom_value2": "Something custom",
      "tax_rate1": 10,
      "tax_rate2": 10,
      "tax_rate3": 10,
      "total_taxes": 10,
      "line_items": [
        {
          "quantity": 1,
          "cost": 10,
          "product_key": "Product key",
          "tags": "Retail,Priority Customer",
          "product_cost": 10,
          "notes": "Item notes",
          "discount": 5,
          "tax_name1": "GST",
          "tax_rate1": 10,
          "tax_name2": "VAT",
          "tax_rate2": 5,
          "tax_name3": "CA Sales Tax",
          "tax_rate3": 3,
          "sort_id": "0",
          "line_total": 10,
          "gross_line_total": 15,
          "tax_amount": 1,
          "custom_value1": "Custom value 1",
          "custom_value2": "Custom value 2",
          "custom_value3": "Custom value 3",
          "custom_value4": "Custom value 4",
          "type_id": "1",
          "tax_id": "1"
        }
      ],
      "invitations": [
        {
          "id": "Opnel5aKBz",
          "client_contact_id": "Opnel5aKBz",
          "key": "Opnel5aKBz4343343566236gvbb",
          "link": "https://www.example.com/invitations/Opnel5aKBz4343343566236gvbb",
          "updated_at": 1434342123,
          "archived_at": 1434342123,
          "email_error": "The email error"
        }
      ],
      "amount": 10,
      "balance": 10,
      "paid_to_date": 10,
      "discount": 10,
      "partial": 10,
      "is_amount_discount": true,
      "is_deleted": true,
      "uses_inclusive_taxes": true,
      "date": "1994-07-30",
      "last_sent_date": "1994-07-30",
      "next_send_date": "1994-07-30",
      "partial_due_date": "1994-07-30",
      "due_date": "1994-07-30",
      "last_viewed": 1434342123,
      "updated_at": 1434342123,
      "archived_at": 1434342123,
      "custom_surcharge1": 10,
      "custom_surcharge2": 10,
      "custom_surcharge3": 10,
      "custom_surcharge4": 10,
      "custom_surcharge_tax1": true,
      "custom_surcharge_tax2": true,
      "custom_surcharge_tax3": true,
      "custom_surcharge_tax4": true,
      "project_id": "Opnel5aKBz",
      "auto_bill_tries": 1,
      "auto_bill_enabled": true,
      "subscription_id": "Opnel5aKBz",
      "location_id": "Opnel5aKBz",
      "design_id": "Opnel5aKBz",
      "exchange_rate": 1,
      "vendor_id": "Opnel5aKBz"
    }
  ],
  "meta": {
    "pagination": {
      "total": 1,
      "count": 1,
      "per_page": 1,
      "current_page": 1,
      "total_pages": 1
    }
  }
}

Changes