Skip to main content
GET
/
invoices
List invoices
curl --request GET \
  --url https://api.openfiskal.com/v1/invoices \
  --header 'Authorization: Bearer <token>'
{
  "object": "<string>",
  "data": [
    {
      "organization_id": "<string>",
      "jurisdiction": "<string>",
      "document_type": "invoice",
      "seller": {
        "legal_name": "Acme S.r.l.",
        "tax_id": "IT12345678901",
        "tax_id_type": "partita_iva",
        "address": {
          "line1": "Friedrichstraße 42",
          "line2": "<string>",
          "city": "Berlin",
          "state": "<string>",
          "postal_code": "10117",
          "country": "DE"
        },
        "sdi_code": "ABC1234",
        "pec_address": "recipient@pec.example.it"
      },
      "buyer": {
        "legal_name": "Acme S.r.l.",
        "tax_id": "IT12345678901",
        "tax_id_type": "partita_iva",
        "address": {
          "line1": "Friedrichstraße 42",
          "line2": "<string>",
          "city": "Berlin",
          "state": "<string>",
          "postal_code": "10117",
          "country": "DE"
        },
        "sdi_code": "ABC1234",
        "pec_address": "recipient@pec.example.it"
      },
      "line_items": [
        {
          "description": "Software development services — March 2026",
          "quantity": 8,
          "unit_price_net": 15000,
          "tax": {
            "rate": "0.19",
            "category": "standard",
            "included_in_price": true
          },
          "unit": "hours",
          "discount": {
            "source": "manual",
            "type": "percentage",
            "label": "Happy Hour",
            "rate": "0.10",
            "amount": 200
          },
          "product_ref": "<string>",
          "nature_code": "N4",
          "line_total_net": 123,
          "line_total_tax": 123,
          "line_total_gross": 123
        }
      ],
      "object": "<string>",
      "submit": true,
      "series": "A",
      "issue_date": "2023-12-25",
      "payment_terms": {
        "method": "already_paid",
        "due_date": "2023-12-25",
        "iban": "IT60X0542811101000000123456",
        "installments": [
          {
            "due_date": "2023-12-25",
            "amount": 123
          }
        ]
      },
      "routing": {
        "codice_destinatario": "ABC1234",
        "pec_address": "jsmith@example.com"
      },
      "notes": [
        "<string>"
      ],
      "references": {
        "operation_id": "<string>",
        "original_invoice_id": "<string>",
        "delivery_date": "2023-12-25",
        "purchase_order_ref": "<string>",
        "contract_ref": "<string>"
      },
      "metadata": {},
      "id": "inv_01HXYZ",
      "state": "draft",
      "invoice_number": "A/2026/00042",
      "totals": {
        "subtotal_gross": 123,
        "total_line_discounts": 123,
        "subtotal_after_line_discounts": 123,
        "total_cart_discounts": 123,
        "subtotal_after_all_discounts": 123,
        "rounding_adjustment": 123,
        "total_gross": 123,
        "total_net": 123,
        "total_tax": 123,
        "tax_breakdown": [
          {
            "rate": "<string>",
            "category": "<string>",
            "taxable_amount": 123,
            "tax_amount": 123,
            "total_gross": 123
          }
        ],
        "net_payable": 123
      },
      "fiscal": {
        "jurisdiction": "IT",
        "transmission_status": "pending",
        "delivery_status": "pending",
        "authority_identifier": "TBAI-12345678A-261226-jBsGMnPmXM-3",
        "chain_hash": "aSDinaTvuI8gbWludGxpZnk=",
        "transmitted_at": "2023-11-07T05:31:56Z",
        "delivered_at": "2023-11-07T05:31:56Z",
        "verification": {
          "url": "https://ticketbai.gipuzkoa.eus/tbai/qr?id=TBAI-...",
          "qr_data": "<string>"
        },
        "jurisdiction_data": {},
        "fiscal_errors": [
          {
            "code": "00159",
            "message": "Codice fiscale acquirente non valido"
          }
        ]
      },
      "created_at": "2023-11-07T05:31:56Z",
      "submitted_at": "2023-11-07T05:31:56Z",
      "cancelled_at": "2023-11-07T05:31:56Z"
    }
  ],
  "cursor": "<string>"
}

Authorizations

​
Authorization
string
header
required

Platform API key sent as Authorization: Bearer ofk_platform_.... Platform integrators also pass OpenFiskal-Organization: org_xxx to act on behalf of a merchant.

Headers

​
OpenFiskal-Organization
string

Merchant organization ID. Required for platform integrators acting on behalf of a specific merchant. Omit when using an organization-scoped API key directly.

Query Parameters

​
organization_id
string
required
​
state
enum<string>
  • draft: Created but not yet submitted to the authority.
  • submitted: Submitted to the authority, awaiting acknowledgment.
  • transmitted: Authority confirmed receipt. For TicketBAI/Verifactu, this is the terminal success state. For SDI, delivery to recipient still pending.
  • delivered: SDI only. Invoice delivered to the recipient's inbox. Recipient has 15 days to accept or reject.
  • accepted: SDI only. Recipient explicitly accepted the invoice. Implicit acceptance occurs after 15 days with no rejection.
  • undeliverable: SDI only. SDI could not deliver to the recipient (invalid codice_destinatario or PEC address). Invoice is fiscally valid but the vendor must contact the recipient directly.
  • rejected_by_authority: Authority rejected the document due to format or validation errors. Check fiscal_errors. Must correct and resubmit as a new invoice.
  • cancellation_requested: Full cancellation initiated, awaiting authority acknowledgment.
  • cancelled: Invoice fully cancelled. A corrective document has been issued and accepted.
Available options:
draft,
submitted,
transmitted,
delivered,
accepted,
undeliverable,
rejected_by_authority,
cancellation_requested,
cancelled
​
document_type
enum<string>

OpenFiskal document type, mapped to jurisdiction-specific codes at submission time. See the E-Invoicing tag description for the full mapping table.

Available options:
invoice,
simplified_invoice,
credit_note,
debit_note,
deferred_invoice,
self_invoice
​
jurisdiction
string
Example:

"IT"

​
buyer_tax_id
string

Filter by buyer tax identifier

​
from
string<date-time>

Filter results to those created at or after this timestamp (ISO 8601).

​
to
string<date-time>

Filter results to those created at or before this timestamp (ISO 8601).

​
limit
integer
default:50

Maximum number of results to return per page.

Required range: 1 <= x <= 200
​
cursor
string

Pagination cursor from a previous response's cursor field. Omit to start from the beginning.

Response

Paginated list of invoices

​
object
string
Allowed value: "list"
​
data
object[]
​
cursor
string | null