List all invoices
List your sales invoices with cursor-based pagination. Supports filtering by `status[in]`, `client_id`, `series_id`, `issued_on[gte|lte]`, and `total[gte|lte]`.
In: header
Query Parameters
uuidNumber of objects to return. Integer between 1 and 100. Defaults to 25.
251 <= value <= 100Cursor for forward pagination. Use the uuid of the last object on the previous page.
uuidCursor for backward pagination. Use the uuid of the first object on the current page.
uuidInvoice status. Exact match on status.
Invoice status. Comma-separated list. Any of the values matches.
Client ID (UUID v7). Exact match on client_id.
uuidClient ID (UUID v7). Comma-separated list. Any of the values matches.
Series ID (UUID v7). Exact match on series_id.
uuidSeries ID (UUID v7). Comma-separated list. Any of the values matches.
Creation date (ISO 8601). Greater than or equal to the given value.
date-timeCreation date (ISO 8601). Less than or equal to the given value.
date-timeCreation date (ISO 8601). Strictly greater than the given value.
date-timeCreation date (ISO 8601). Strictly less than the given value.
date-timeDue date. Greater than or equal to the given value.
dateDue date. Less than or equal to the given value.
dateDue date. Strictly greater than the given value.
dateDue date. Strictly less than the given value.
dateTotal amount. Greater than or equal to the given value.
Total amount. Less than or equal to the given value.
Total amount. Strictly greater than the given value.
Total amount. Strictly less than the given value.
ISO 4217 currency code (e.g. EUR). Exact match on currency.
ISO 4217 currency code (e.g. EUR). Comma-separated list. Any of the values matches.
Invoice number. Exact match on number.
Filter by classification tag (lowercase slug). Supports multiple values with tags[in]=a,b (JSON_CONTAINS, OR semantics — matches invoices carrying ANY of the tags). Exact match on tags.
Filter by classification tag (lowercase slug). Supports multiple values with tags[in]=a,b (JSON_CONTAINS, OR semantics — matches invoices carrying ANY of the tags). Comma-separated list. Any of the values matches.
Sort order. Use a field for ascending or a - prefix for descending (e.g. -created). Allowed fields: created, total, number. Combined with the cursor, ordering stays deterministic (a stable secondary sort by the cursor id, Stripe-style). When omitted, results follow the default cursor order (created descending).
"created" | "-created" | "total" | "-total" | "number" | "-number"Response Body
application/json
application/json
application/json
application/json
application/json
application/json
import { Factuarea } from "@factuarea/sdk";const factuarea = new Factuarea({ apiKey: process.env.FACTUAREA_API_KEY! });// List endpoints return an async-iterable Page (cursors handled for you).for await (const item of await factuarea.invoices.list({ limit: 25 })) { console.log(item.id);}{
"data": [
{
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42",
"object": "invoice",
"number": "FAC-2026-00042",
"is_number_assigned": true,
"type": "F1",
"series": {
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02",
"code": "FAC-2026"
},
"client": {
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
"name": "Acme Soluciones SL"
},
"status": "paid",
"issued_on": "2026-03-15",
"due_on": "2026-04-14",
"subtotal": 1000,
"taxes_total": 210,
"total": 1210,
"currency": "EUR",
"notes": "Servicios profesionales marzo 2026.",
"external_id": "ERP-2026-0042",
"lines": [
{
"object": "invoice_line",
"description": "Consultoría técnica (10 h)",
"product": {
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03",
"name": "Consultoría técnica (hora)"
},
"quantity": 10,
"unit_price": 100,
"tax_rate": 21,
"discount_percent": 0,
"subtotal": 1000,
"taxes": 210,
"total": 1210
}
],
"metadata": {
"order_id": "PO-2026-0042"
},
"tags": [
"consultoria",
"cliente-vip"
],
"custom_fields": [
{
"field": "centro_coste",
"value": "CC-2026-001"
},
{
"field": "numero_pedido",
"value": "PO-2026-0042"
}
],
"operation_regime": "general",
"exclude_347": false,
"verifactu_status": "accepted",
"paid_amount": 1210,
"pending_amount": 0,
"payments": {
"detail": [
{
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a90",
"object": "payment",
"invoice_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42",
"amount": 1210,
"payment_date": "2026-03-20",
"payment_method": "bank_transfer",
"payment_method_text": "Transferencia bancaria",
"reference": "TRF-2026-0042",
"notes": null,
"created_at": "2026-03-20T10:30:00Z",
"updated_at": "2026-03-20T10:30:00Z"
}
],
"total": 1210,
"pending": 0
},
"is_corrective": false,
"corrective": null,
"payment": {
"method": "bank_transfer",
"reference": "TRF-2026-0042",
"date": "2026-03-20"
},
"public_link": {
"object": "public_link",
"url": "https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42",
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42",
"enabled": true,
"expires_at": "2026-09-15T23:59:59Z",
"max_days": 120
},
"substituted_by": null,
"recurring": null,
"paid_at": "2026-03-20T10:30:00Z",
"paid_on": "2026-03-20",
"sent_at": "2026-03-15T11:45:00Z",
"voided_at": null,
"void_reason": null,
"created_at": "2026-03-15T11:30:00Z",
"updated_at": "2026-03-20T10:30:00Z"
}
],
"has_more": true,
"next_cursor": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0c"
}{
"error": {
"type": "authentication_error",
"code": "missing_api_key",
"message": "No se ha proporcionado una API key válida en el header Authorization.",
"param": null,
"doc_url": "https://docs.factuarea.com/guides/errors#missing_api_key",
"request_id": "req_01HKQS5N8VR7QXJ9K3T6BWPMZA"
}
}{
"error": {
"type": "authorization_error",
"code": "insufficient_scope",
"message": "Esta API key no tiene el scope requerido para esta operación.",
"param": null,
"doc_url": "https://docs.factuarea.com/guides/errors#insufficient_scope",
"request_id": "req_01HKQS5NBC3P8M1KX4V7SLNHQD"
}
}{
"error": {
"type": "invalid_request_error",
"code": "parameter_invalid",
"message": "El campo `name` es obligatorio y no puede estar vacío.",
"param": "name",
"doc_url": "https://docs.factuarea.com/guides/errors#parameter_invalid",
"request_id": "req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"
}
}{
"error": {
"type": "rate_limit_error",
"code": "rate_limit_exceeded",
"message": "Has excedido el rate limit de 60 peticiones por minuto. Reintenta tras 30 segundos.",
"param": null,
"doc_url": "https://docs.factuarea.com/guides/errors#rate_limit_exceeded",
"request_id": "req_01HKQS5NKW1C6W9T4G5H0JBZVL"
}
}{
"error": {
"type": "api_error",
"code": "internal_error",
"message": "Ha ocurrido un error inesperado. Si persiste, contacta con soporte adjuntando el request_id.",
"param": null,
"doc_url": "https://docs.factuarea.com/guides/errors#internal_error",
"request_id": "req_01HKQS5NLX2D7X0U5H6J1KCAWM"
}
}Find an invoice by number
Looks up a single invoice by its number, with optional `year` to disambiguate across fiscal years. Returns 404 if not found and 422 if the number is ambiguous and no `year` is supplied.
Mark invoice as paid
Mark an invoice as fully paid. Idempotent: if already paid, returns the invoice unchanged. Returns 422 if the invoice is in a status that cannot transition to `paid`.