Use filters to retrieve only the customer invoices that match your criteria (date range, customer, invoice number, subscription, etc.).

Filtering helps reduce API call volume, improve performance, and retrieve exactly the dataset your integration needs.

This guide shows how to use the filters[] parameter with the /customer_invoices endpoint and lists all supported fields and operators.

📘

Reminder: Filters use a JSON array of objects passed as the filters query parameter.
See Filter API Data for the general filtering syntax.

How Filtering Works

Customer invoice filtering relies on the API’s standard filters[] format:

[
  { "field": "customer_id", "operator": "eq", "value": "cust_123" },
  { "field": "date", "operator": "gteq", "value": "2024-01-01" }
]

You can combine multiple filters at once.

Filters must be URL-encoded when passed as query parameters.

Example request:

GET /customer_invoices?filters=[{"field":"customer_id","operator":"eq","value":"cust_123"}]

Common Use Cases

Here are the most frequent patterns used by integrators:

• Retrieve all invoices for a specific customer
• Get invoices issued after a certain date
• Search invoices matching one or several invoice numbers
• Retrieve invoices associated with a billing subscription
• Filter invoices for BI or reconciliation workflows

Examples

Filter by customer

GET /customer_invoices?filters=[{"field":"customer_id","operator":"eq","value":"cust_987"}]

Filter by date range

GET /customer_invoices?filters=[
  {"field":"date","operator":"gteq","value":"2024-01-01"},
  {"field":"date","operator":"lteq","value":"2024-03-31"}
]

Filter by several invoice numbers

GET /customer_invoices?filters=[
  {"field":"invoice_number","operator":"in","value":["INV-2024-001","INV-2024-002"]}
]

Available Fields and Operators

💡

Tip: date filters must use ISO 8601 format (YYYY-MM-DD).

Tips & Troubleshooting

• URL-encode the filter array to avoid 400 Bad Request errors.
• Combine filters with pagination when retrieving large datasets (using the pagination mechanism supported by the endpoint).
• Use ISO date strings for all date filters.
• Use in and not_in for bulk retrievals (e.g., list of customers or invoice numbers).
• Filtering by invoice_number is exact-match, not a text search.
• To retrieve “recent changes”, prefer filtering by updated_at (if available on the endpoint) or use the Changelog API.