--- title: "List invoices" method: GET path: "/api/v1/invoices" tags: ["invoices"] --- # List invoices `GET /api/v1/invoices` ## Request - Base URL: `https://demo.invoiceninja.com` - URL: `https://demo.invoiceninja.com/api/v1/invoices` - Auth: none declared. Required headers: `X-API-TOKEN`, `X-Requested-With` - TypeScript: (a function with typed inputs; its response is checked against the schema) ## GET /api/v1/invoices Lists invoices with the option to chain multiple query parameters allowing fine grained filtering of the list. ## Query parameters - `include` string - `index` string - `per_page` integer - `page` integer - `sort` string[] - `status` string - `client_id` string - `created_at` integer - `updated_at` integer - `is_deleted` boolean - `filter_deleted_clients` string - `vendor_id` string - `client_status` string - `number` string - `filter` string - `without_deleted_clients` string - `overdue` string - `payable` string - `private_notes` string - `date` string - `date_range` string - `status_id` integer ## Headers - `X-API-TOKEN` string, required - `X-Requested-With` string, required ## Response `200` A list of invoices - object - `data` Invoice[] - `id` string: The invoice hashed id - `user_id` string: The user hashed id - `assigned_user_id` string: The assigned user hashed id - `client_id` string: The client hashed id - `status_id` string: The invoice status variable - `number` string: The invoice number - is a unique alpha numeric number per invoice per company - `po_number` string: The purchase order associated with this invoice - `terms` string: The invoice terms - `public_notes` string: The public notes of the invoice - `private_notes` string: The private notes of the invoice - `footer` string: The invoice footer notes - `custom_value1` string: A custom field value - `custom_value2` string: A custom field value - `custom_value3` string: A custom field value - `custom_value4` string: A custom field value - `tax_name1` string: The tax name - `tax_name2` string: The tax name - `tax_rate1` number, float: The tax rate - `tax_rate2` number, float: The tax rate - `tax_name3` string: The tax name - `tax_rate3` number, float: The tax rate - `total_taxes` number, float: The total taxes for the invoice - `line_items` InvoiceItem[]: An array of objects which define the line items of the invoice - `quantity` number: The quantity of the product offered for this line item - `cost` number, float: The cost of the product offered for this line item - `product_key` string: The product key of the product offered for this line item (Referred to as Product in the product tab) - `tags` string: A comma-separated snapshot of the product tag names for this line item - `product_cost` number, float: The cost of the product offered for this line item (Referred to as Cost in the product tab) - `notes` string: The notes/description for the product offered for this line item - `discount` number, float: The discount applied to the product offered for this line item - `is_amount_discount` boolean: Indicates whether the discount applied to the product offered for this line item is a fixed amount or a percentage - `tax_name1` string: The name of the first tax applied to the product offered for this line item - `tax_rate1` number, float: The rate of the first tax applied to the product offered for this line item - `tax_name2` string: The name of the second tax applied to the product offered for this line item - `tax_rate2` number, float: The rate of the second tax applied to the product offered for this line item - `tax_name3` string: The name of the third tax applied to the product offered for this line item - `tax_rate3` number, float: The rate of the third tax applied to the product offered for this line item - `sort_id` string: Deprecated - `line_total` number, float: The total amount of the product offered for this line item - `gross_line_total` number, float: The total amount of the product offered for this line item before discounts - `tax_amount` number, float: The total amount of tax applied to the product offered for this line item - `custom_value1` string: The first custom value of the product offered for this line item - `custom_value2` string: The second custom value of the product offered for this line item - `custom_value3` string: The third custom value of the product offered for this line item - `custom_value4` string: The fourth custom value of the product offered for this line item - `type_id` string: 1 = product, 2 = service, 3 unpaid gateway fee, 4 paid gateway fee, 5 late fee, 6 expense - `tax_id` string: The tax ID of the product: 1 product, 2 service, 3 digital, 4 shipping, 5 exempt, 5 reduced tax, 7 override, 8 zero rate, 9 reverse tax - `invitations` InvoiceInvitation[]: An array of objects which define the invitations of the invoice - `id` string: The entity invitation hashed id - `client_contact_id` string: The client contact hashed id - `key` string: The invitation key - `link` string: The invitation link - `sent_date` string, date-time: The invitation sent date - `viewed_date` string, date-time: The invitation viewed date - `opened_date` string, date-time: The invitation opened date - `updated_at` number: Timestamp - `archived_at` number: Timestamp - `email_error` string: The email error - `email_status` string: The email status - `can_sign` boolean: Indicates whether the recipient contact may electronically sign this invitation. Mirrors the can_sign flag on the linked client contact at the time the invitation was issued. - `amount` number, float: The invoice amount - `balance` number, float: The invoice balance - `paid_to_date` number, float: The amount paid on the invoice to date - `discount` number, float: The invoice discount, can be an amount or a percentage - `partial` number, float: The deposit/partial amount - `is_amount_discount` boolean: Flag determining if the discount is an amount or a percentage - `is_deleted` boolean: Defines if the invoice has been deleted - `uses_inclusive_taxes` boolean: Defines the type of taxes used as either inclusive or exclusive - `date` string, date: The Invoice Date - `last_sent_date` string, date: The last date the invoice was sent out - `next_send_date` string, date: The Next date for a reminder to be sent - `partial_due_date` string, date: The due date for the deposit/partial amount - `due_date` string, date: The due date of the invoice - `last_viewed` number: Timestamp - `updated_at` number: Timestamp - `archived_at` number: Timestamp - `custom_surcharge1` number, float: First Custom Surcharge - `custom_surcharge2` number, float: Second Custom Surcharge - `custom_surcharge3` number, float: Third Custom Surcharge - `custom_surcharge4` number, float: Fourth Custom Surcharge - `custom_surcharge_tax1` boolean: Toggles charging taxes on custom surcharge amounts - `custom_surcharge_tax2` boolean: Toggles charging taxes on custom surcharge amounts - `custom_surcharge_tax3` boolean: Toggles charging taxes on custom surcharge amounts - `custom_surcharge_tax4` boolean: Toggles charging taxes on custom surcharge amounts - `project_id` string: The project associated with this invoice - `auto_bill_tries` integer: The number of times the invoice has attempted to be auto billed - `auto_bill_enabled` boolean: Boolean flag determining if the invoice is set to auto bill - `subscription_id` string: The subscription associated with this invoice - `location_id` string: The client location id that this invoice relates to - `design_id` string: The unique identifier of the design template used for this invoice - `e_invoice` object: E-invoice configuration and data - `exchange_rate` number, float: The exchange rate used for currency conversion - `vendor_id` string: The unique identifier of the vendor associated with this invoice - `meta` Meta - `pagination` Pagination - `total` integer: The total number of items - `count` integer: The number of items per page - `per_page` integer: The number of items per page - `current_page` integer: The current page number - `total_pages` integer: The total number of pages - `links` object: The pagination links ## Other responses - `401`: Authentication error - `403`: Authorization error - `422`: Validation error - `429`: Rate Limit Exceeded - `5XX`: Server error - `default`: Unexpected Error ## Changes - **2026-08-21** `a8b7a375e4ed`: 1 info - added the optional property `data/items/line_items/items/tags` to the response with the `200` status - **2026-05-06** `89876e7e51d6`: 1 info - for the `query` request parameter `sort`, the type was generalized from `string` to `array` - **2026-04-20** `69a36036d334`: 1 info - added the optional property `data/items/invitations/items/can_sign` to the response with the `200` status - **2025-11-22** `00ad5cc89fad`: 4 info - added the optional property `data/items/design_id` to the response with the `200` status - added the optional property `data/items/e_invoice` to the response with the `200` status - added the optional property `data/items/exchange_rate` to the response with the `200` status - added the optional property `data/items/vendor_id` to the response with the `200` status - **2025-10-10** `f36c4f94ae7b`: 3 info - added the new optional `query` request parameter `index` - added the new optional `query` request parameter `page` - added the new optional `query` request parameter `per_page` [Operation history](https://skmtc.dev/invoiceninja/apis/invoice-ninja-api-reference/changes/api/v1/invoices/get.md) --- [API](https://skmtc.dev/invoiceninja/apis/invoice-ninja-api-reference.md) - [All operations](https://skmtc.dev/invoiceninja/apis/invoice-ninja-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/invoiceninja/apis/invoice-ninja-api-reference/revisions/bcda1f823746?raw)