Endpoint used to retrieve invoices registered in the account.

This operation returns a paginated list of invoices and allows filters to be applied to locate specific records by issue date, customer, financial relationship, external reference, or invoice status.

Unlike retrieving a specific invoice, this endpoint is intended for batch queries, operational monitoring, and report generation.

When to use

This endpoint is recommended for:

• monitoring issued invoices;
• financial reconciliation;
• report generation;
• tracking invoice processing;
• locating invoices associated with specific payments, installments, or customers;
• periodically synchronizing information between systems.

Most important parameters

In addition to the parameters automatically displayed by the API reference, some filters are particularly useful:

• status — allows querying invoices in specific states;
• effectiveDate[ge] and effectiveDate[le] — recommended for date range queries;
• customer — locates invoices associated with a specific customer;
• payment — locates the invoice related to a payment;
• externalReference — facilitates reconciliation with internal system identifiers.

Possible statuses

The status filter accepts the following values:

• SCHEDULED
• AUTHORIZED
• PROCESSING_CANCELLATION
• CANCELED
• CANCELLATION_DENIED
• ERROR

Pagination behavior

Results are paginated using the offset and limit parameters.

As a best practice, incremental pagination is recommended to avoid excessively large queries.

Example:

GET /v3/invoices?offset=0&limit=100

Next page:

GET /v3/invoices?offset=100&limit=100

📘

Best practices

For bulk synchronizations, prefer querying by date range and using pagination instead of retrieving large volumes in a single request.

Filter examples

Filter by issue date:

GET https://api.asaas.com/v3/invoices?effectiveDate%5Bge%5D=2018-06-03&effectiveDate%5Ble%5D=2018-06-10

Filter by status:

GET https://api.asaas.com/v3/invoices?status=SCHEDULED

Filter by customer:

GET https://api.asaas.com/v3/invoices?customer=cus_000005913227

Combine filters:

GET https://api.asaas.com/v3/invoices?status=AUTHORIZED&effectiveDate%5Bge%5D=2026-01-01&effectiveDate%5Ble%5D=2026-01-31

📘

Important

Filters can be combined to perform more specific queries.

This approach is especially useful for financial reconciliation and report generation.

Important behaviors

• If no records are found, the response will return an empty list.
• Filters can be used simultaneously.
• Broad queries may result in multiple pages of results.
• This endpoint is intended for batch queries, while retrieving an individual invoice is more appropriate when the invoice identifier is already known.

Common errors

403 Forbidden

GET requests must be sent without a request body.

If the request contains data in the body, the following error will be returned:

Forbidden. Occurs when the request body is not empty. GET requests must have an empty body.

401 Unauthorized

Indicates authentication failure or the use of an invalid API key.

400 Bad Request

Occurs when one or more parameters are sent with an invalid format.

Operational impacts

For environments with a large volume of invoices, it is recommended to:

• use date range filters;
• paginate results;
• avoid overly broad queries;
• store invoice identifiers locally to reduce the need for frequent requests.

Use cases

This endpoint is useful for:

• monitoring issued invoices;
• financial reconciliation;
• report generation;
• tracking the invoice lifecycle;
• validating invoice processing statuses;
• synchronizing data with external systems.

Related content

• Retrieve an invoice.
• Create an invoice.
• Cancel an invoice.
• List municipal services.
• Invoice issuance settings.