# Invoices Issue, retrieve and list immutable invoices. Issuing an invoice validates its contents, assigns the next series number, resolves taxes and stores the finished document in one operation. An issued invoice cannot be edited. To correct an issued invoice, create an amendment. FiscalRail keeps the original immutable, issues the required full credit note and optional replacement atomically, and links every document through the same amendment object. Both generated documents persist the original as `preceding_invoice`, so each remains self-describing independently of the amendment lookup. A document can be amended once; apply any later change to its replacement. Use `issued_by_mistake` only when the underlying operation never happened; it voids the original without issuing another invoice. Read [Correcting invoices](/en/docs/correcting-invoices) for the reason-selection workflow, generated documents and retry strategy. Supply an optional `Idempotency-Key` header when issuing an invoice if the request might need to be retried. See [Idempotency](/en/docs/api/idempotency). Use `supply_period` when the supply date differs from the issue date or the invoice covers a range. Set `start_date` and `end_date` to the same value for a single day. The top-level `issue_date` belongs to the document being returned; `preceding_invoice.issue_date` identifies the corrected document. `lines[].description` describes the goods or services supplied. For structured regimes such as Spain, FiscalRail resolves each `lines[].taxes[].description` from the selected `tax` and `rule`. Custom taxes under the global regime require the tax description in the request. Under the global regime, a customer snapshot may have a null address. Spanish ordinary invoices require the customer's address; issuance fails with a `customer.address` validation error if the selected customer does not have one. ## The Invoice object ### Properties #### `id` Type: `string` Opaque identifier for the invoice. #### `object` Type: `string` String identifying this as an Invoice object. Always `invoice`. #### `live` Type: `boolean` True when the object belongs to the live environment; false for test data. #### `account` Type: `string` Account that issued the invoice. #### `kind` Type: `enum` Commercial document kind. This is independent from tax-regime rectification codes. Possible values: - `invoice` — - `credit_note` — #### `code` Type: `string` Human-readable invoice number assigned from the selected series. #### `series` Type: `string` Invoicing series used to number the invoice. #### `issue_date` Type: `string` Legal issue date in ISO 8601 format. #### `supply_period` Type: `object or null` Period covered by the invoice, or null when it was not provided. ##### `supply_period.start_date` Type: `string` First calendar date covered by the invoice. ##### `supply_period.end_date` Type: `string` Last calendar date covered by the invoice. #### `preceding_invoice` Type: `object or null` Invoice corrected by this document, or null when this is not a correction. ##### `preceding_invoice.id` Type: `string or null` FiscalRail invoice ID, or null when the original document was issued elsewhere. ##### `preceding_invoice.code` Type: `string` Human-readable invoice number. ##### `preceding_invoice.issue_date` Type: `string` Issue date of the referenced invoice in ISO 8601 format. #### `currency` Type: `string` ISO 4217 currency code used for every monetary amount. Always `EUR`. #### `supplier` Type: `object` Immutable snapshot of the supplier at issuance. ##### `supplier.source` Type: `object` Resource from which this immutable party snapshot was created. ###### `supplier.source.type` Type: `enum` Kind of resource from which the party was snapshotted. Possible values: - `account` — The account that supplied the issuer details. - `customer` — The customer that supplied the recipient details. ###### `supplier.source.id` Type: `string` Account or customer ID, according to `type`. ##### `supplier.name` Type: `string` Legal or trading name at issuance. ##### `supplier.tax_id` Type: `object` Fiscal identifier at issuance. ###### `supplier.tax_id.country` Type: `string` ISO 3166-1 alpha-2 country associated with the tax ID at issuance. ###### `supplier.tax_id.type` Type: `string` FiscalRail's normalized fiscal identifier type at issuance. ###### `supplier.tax_id.value` Type: `string` The normalized fiscal identifier value at issuance. ##### `supplier.email` Type: `string or null` Email address at issuance, or null when absent. ##### `supplier.phone` Type: `string or null` Phone number at issuance, or null when absent. ##### `supplier.address` Type: `object or null` Address at issuance, or null when a global invoice was issued without one. ###### `supplier.address.line_1` Type: `string` Primary street address. ###### `supplier.address.line_2` Type: `string or null` Additional address information, or null when not supplied. ###### `supplier.address.city` Type: `string` City or locality. ###### `supplier.address.postal_code` Type: `string` Postal or ZIP code. ###### `supplier.address.state` Type: `string or null` State, province, or region, or null when not applicable. ###### `supplier.address.country` Type: `string` ISO 3166-1 alpha-2 country code. #### `customer` Type: `object or null` Immutable customer snapshot, or null for a simplified invoice. ##### `customer.source` Type: `object` Resource from which this immutable party snapshot was created. ###### `customer.source.type` Type: `enum` Kind of resource from which the party was snapshotted. Possible values: - `account` — The account that supplied the issuer details. - `customer` — The customer that supplied the recipient details. ###### `customer.source.id` Type: `string` Account or customer ID, according to `type`. ##### `customer.name` Type: `string` Legal or trading name at issuance. ##### `customer.tax_id` Type: `object` Fiscal identifier at issuance. ###### `customer.tax_id.country` Type: `string` ISO 3166-1 alpha-2 country associated with the tax ID at issuance. ###### `customer.tax_id.type` Type: `string` FiscalRail's normalized fiscal identifier type at issuance. ###### `customer.tax_id.value` Type: `string` The normalized fiscal identifier value at issuance. ##### `customer.email` Type: `string or null` Email address at issuance, or null when absent. ##### `customer.phone` Type: `string or null` Phone number at issuance, or null when absent. ##### `customer.address` Type: `object or null` Address at issuance, or null when a global invoice was issued without one. ###### `customer.address.line_1` Type: `string` Primary street address. ###### `customer.address.line_2` Type: `string or null` Additional address information, or null when not supplied. ###### `customer.address.city` Type: `string` City or locality. ###### `customer.address.postal_code` Type: `string` Postal or ZIP code. ###### `customer.address.state` Type: `string or null` State, province, or region, or null when not applicable. ###### `customer.address.country` Type: `string` ISO 3166-1 alpha-2 country code. #### `lines` Type: `array of objects` Immutable invoice line items and their resolved taxes. ##### `lines.index` Type: `integer` One-based position of the line on the invoice. ##### `lines.description` Type: `string` Description of the goods or services captured at issuance. ##### `lines.quantity` Type: `string` Quantity represented as a decimal string. ##### `lines.unit_price` Type: `string` Price per unit before taxes. ##### `lines.subtotal` Type: `string` Line amount before taxes. ##### `lines.taxes` Type: `array of objects` Resolved taxes applied to the line. ###### `lines.taxes.tax` Type: `string` Stable tax identifier from the invoice's tax regime. ###### `lines.taxes.rule` Type: `string` Stable rule identifier within the tax. ###### `lines.taxes.effect` Type: `enum` How this tax affects the invoice total. Possible values: - `added` — The tax amount is added to the invoice total. - `withheld` — The tax amount is withheld from the amount payable to the supplier. ###### `lines.taxes.treatment` Type: `enum` Fiscal treatment applied to the taxable base. Possible values: - `taxable` — Tax applies to the line at the stated rate. - `exempt` — The line is exempt from the tax. - `reverse_charge` — The customer accounts for the tax under reverse charge. - `not_subject` — The line is outside the scope of the tax. ###### `lines.taxes.description` Type: `string` Tax label resolved from the regime catalog or supplied for a custom tax, captured at issuance. ###### `lines.taxes.rate` Type: `string or null` Percentage rate; zero for exempt or reverse-charge taxes, and null for not-subject operations. ###### `lines.taxes.taxable_base` Type: `string` Amount on which this tax is calculated. #### `tax_totals` Type: `array of objects` Taxes aggregated across all line items. ##### `tax_totals.tax` Type: `string` Stable tax identifier from the invoice's tax regime. ##### `tax_totals.rule` Type: `string` Stable rule identifier within the tax. ##### `tax_totals.effect` Type: `enum` How this tax affects the invoice total. Possible values: - `added` — The tax amount is added to the invoice total. - `withheld` — The tax amount is withheld from the amount payable to the supplier. ##### `tax_totals.treatment` Type: `enum` Fiscal treatment applied to the taxable base. Possible values: - `taxable` — Tax applies to the line at the stated rate. - `exempt` — The line is exempt from the tax. - `reverse_charge` — The customer accounts for the tax under reverse charge. - `not_subject` — The line is outside the scope of the tax. ##### `tax_totals.description` Type: `string` Tax label resolved from the regime catalog or supplied for a custom tax, captured at issuance. ##### `tax_totals.rate` Type: `string or null` Percentage rate; zero for exempt or reverse-charge taxes, and null for not-subject operations. ##### `tax_totals.taxable_base` Type: `string` Amount on which this tax is calculated. ##### `tax_totals.amount` Type: `string` Tax amount aggregated across invoice lines. #### `totals` Type: `object` Monetary totals calculated for the invoice. ##### `totals.subtotal` Type: `string` Sum of line subtotals before taxes. ##### `totals.tax` Type: `string` Total tax added to the invoice. ##### `totals.total_with_tax` Type: `string` Subtotal plus taxes added to the invoice. ##### `totals.withheld_tax` Type: `string` Total tax withheld from the supplier. ##### `totals.payable` Type: `string` Final amount payable after added and withheld taxes. #### `created_at` Type: `string` When FiscalRail stored the issued invoice, in ISO 8601 format. #### `tax_regime` Type: `object` Regime-specific compliance state attached to the invoice. ##### Global invoice tax regime ###### `tax_regime.key` Type: `string` Identifies the global tax regime. Always `global`. ##### Spanish invoice tax regime ###### `tax_regime.key` Type: `string` Identifies the Spanish tax regime. Always `es`. ###### `tax_regime.es` Type: `object` Spanish invoice compliance details. ###### `tax_regime.es.qr` Type: `object` AEAT QR data for the invoice. ###### `tax_regime.es.qr.content` Type: `string` Exact content encoded in the invoice's AEAT QR code. ###### `tax_regime.es.qr.image_url` Type: `string` Permanent signed URL for the compliant SVG QR image. ###### `tax_regime.es.verifactu` Type: `object` VERI*FACTU registration state for the invoice. ###### `tax_regime.es.verifactu.registrations` Type: `array of objects` Registration attempts for this invoice, newest first. ###### `tax_regime.es.verifactu.registrations.id` Type: `string` Opaque identifier for the VERI*FACTU registration. ###### `tax_regime.es.verifactu.registrations.object` Type: `string` String identifying this as a VERI*FACTU registration object. Always `verifactu_registration`. ###### `tax_regime.es.verifactu.registrations.live` Type: `boolean` True when the object belongs to the live environment; false for test data. ###### `tax_regime.es.verifactu.registrations.invoice` Type: `string` Invoice submitted by this registration. ###### `tax_regime.es.verifactu.registrations.kind` Type: `enum` Kind of VERI*FACTU record submitted. Possible values: - `alta` — Registers a newly issued invoice. - `anulacion` — Cancels the registration of an invoice issued by mistake. ###### `tax_regime.es.verifactu.registrations.status` Type: `enum` Current submission state reported by FiscalRail or AEAT. Possible values: - `pending` — The registration is queued, being submitted, or awaiting a retry. - `accepted` — AEAT accepted the registration without errors. - `accepted_with_errors` — AEAT accepted the registration but reported issues that may require review. - `rejected` — AEAT rejected the registration. ###### `tax_regime.es.verifactu.registrations.submitted_at` Type: `string or null` When the registration was last submitted to AEAT, or null before submission. ###### `tax_regime.es.verifactu.registrations.csv` Type: `string or null` AEAT secure verification code, or null when AEAT has not supplied one. ###### `tax_regime.es.verifactu.registrations.error` Type: `object or null` Structured rejection or submission error, or null when there is no error. #### `amendments` Type: `array of objects` Amendments that connect this invoice to its original, credit note and replacement. ##### `amendments.id` Type: `string` Opaque identifier for the amendment. ##### `amendments.object` Type: `string` String identifying this as an Invoice Amendment object. Always `invoice_amendment`. ##### `amendments.live` Type: `boolean` True when the object belongs to the live environment; false for test data. ##### `amendments.reason` Type: `enum` Why the original invoice was amended or voided. Possible values: - `refund` — Fully credits the original; provide a lower-value replacement for a partial refund. - `discount` — Fully credits the original; provide a lower-value replacement with unchanged quantities and tax treatment. - `incorrect_customer_details` — Replaces customer details while preserving the customer identity, lines and totals. - `incorrect_lines` — Replaces the lines while preserving the customer and tax treatment. - `incorrect_tax` — Replaces tax treatment or rates while preserving the customer and non-tax line details. - `customer_identification` — Adds or replaces customer tax identity while preserving lines and totals. - `issued_by_mistake` — Voids an invoice for an operation that never happened; no credit note or replacement is issued. ##### `amendments.original` Type: `object` Invoice being reversed or voided. ###### `amendments.original.id` Type: `string or null` FiscalRail invoice ID, or null when the original document was issued elsewhere. ###### `amendments.original.code` Type: `string` Human-readable invoice number. ###### `amendments.original.issue_date` Type: `string` Issue date of the referenced invoice in ISO 8601 format. ##### `amendments.credit_note` Type: `object or null` Full credit note, or null for an invoice issued by mistake. ###### `amendments.credit_note.id` Type: `string or null` FiscalRail invoice ID, or null when the original document was issued elsewhere. ###### `amendments.credit_note.code` Type: `string` Human-readable invoice number. ###### `amendments.credit_note.issue_date` Type: `string` Issue date of the referenced invoice in ISO 8601 format. ##### `amendments.replacement` Type: `object or null` Replacement invoice, or null when the operation is fully refunded, discounted or voided. ###### `amendments.replacement.id` Type: `string or null` FiscalRail invoice ID, or null when the original document was issued elsewhere. ###### `amendments.replacement.code` Type: `string` Human-readable invoice number. ###### `amendments.replacement.issue_date` Type: `string` Issue date of the referenced invoice in ISO 8601 format. ##### `amendments.created_at` Type: `string` When FiscalRail recorded the amendment, in ISO 8601 format. ### Example ```json { "id": "inv_14Vxtqg6oXpAY5WdWoq4wW", "object": "invoice", "live": true, "account": "acct_14Vxtqg2nwvPR75TpsGH8N", "kind": "invoice", "code": "INV-00001", "series": "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ", "issue_date": "2026-07-31", "supply_period": null, "preceding_invoice": null, "currency": "EUR", "supplier": { "source": { "type": "account", "id": "acct_14Vxtqg2nwvPR75TpsGH8N" }, "name": "Example supplier", "tax_id": { "country": "ES", "type": "es_nif", "value": "B02850360" }, "email": null, "phone": null, "address": { "line_1": "Example street 1", "line_2": null, "city": "Madrid", "postal_code": "28001", "state": null, "country": "ES" } }, "customer": { "source": { "type": "customer", "id": "cus_14Vxtqg6oXpAY5WdWoq4wW" }, "name": "Acme SL", "tax_id": { "country": "ES", "type": "es_nif", "value": "B87654323" }, "email": "billing@example.com", "phone": null, "address": { "line_1": "Gran Via 1", "line_2": null, "city": "Madrid", "postal_code": "28013", "state": "Madrid", "country": "ES" } }, "lines": [ { "index": 1, "description": "Consulting", "quantity": "8.0", "unit_price": "75.00", "subtotal": "600.00", "taxes": [ { "tax": "vat", "rule": "general", "effect": "added", "treatment": "taxable", "description": "IVA 21%", "rate": "21%", "taxable_base": "600.00" } ] } ], "tax_totals": [ { "tax": "vat", "rule": "general", "effect": "added", "treatment": "taxable", "description": "IVA 21%", "rate": "21%", "taxable_base": "600.00", "amount": "126.00" } ], "totals": { "subtotal": "600.00", "tax": "126.00", "total_with_tax": "726.00", "withheld_tax": "0.00", "payable": "726.00" }, "created_at": "2026-07-31T09:30:00Z", "amendments": [], "tax_regime": { "key": "es", "es": { "qr": { "content": "https://prewww2.aeat.es/wlpl/TIKE-CONT/ValidarQR?nif=B02850360&numserie=INV-00001&fecha=31-07-2026&importe=726.00", "image_url": "https://api.fiscalrail.com/v1/invoices/inv_14Vxtqg6oXpAY5WdWoq4wW/qr.svg?signature=example" }, "verifactu": { "registrations": [ { "id": "es_inv_reg_14Vxtqg8mKp2Rs7Dc4Hn6Y", "object": "verifactu_registration", "live": true, "invoice": "inv_14Vxtqg6oXpAY5WdWoq4wW", "kind": "alta", "status": "accepted", "submitted_at": "2026-07-31T09:30:03Z", "csv": "ABCD1234", "error": null } ] } } } } ``` ## The Invoice Amendment object ### Properties #### `id` Type: `string` Opaque identifier for the amendment. #### `object` Type: `string` String identifying this as an Invoice Amendment object. Always `invoice_amendment`. #### `live` Type: `boolean` True when the object belongs to the live environment; false for test data. #### `reason` Type: `enum` Why the original invoice was amended or voided. Possible values: - `refund` — Fully credits the original; provide a lower-value replacement for a partial refund. - `discount` — Fully credits the original; provide a lower-value replacement with unchanged quantities and tax treatment. - `incorrect_customer_details` — Replaces customer details while preserving the customer identity, lines and totals. - `incorrect_lines` — Replaces the lines while preserving the customer and tax treatment. - `incorrect_tax` — Replaces tax treatment or rates while preserving the customer and non-tax line details. - `customer_identification` — Adds or replaces customer tax identity while preserving lines and totals. - `issued_by_mistake` — Voids an invoice for an operation that never happened; no credit note or replacement is issued. #### `original` Type: `object` Invoice being reversed or voided. ##### `original.id` Type: `string or null` FiscalRail invoice ID, or null when the original document was issued elsewhere. ##### `original.code` Type: `string` Human-readable invoice number. ##### `original.issue_date` Type: `string` Issue date of the referenced invoice in ISO 8601 format. #### `credit_note` Type: `object or null` Full credit note, or null for an invoice issued by mistake. ##### `credit_note.id` Type: `string or null` FiscalRail invoice ID, or null when the original document was issued elsewhere. ##### `credit_note.code` Type: `string` Human-readable invoice number. ##### `credit_note.issue_date` Type: `string` Issue date of the referenced invoice in ISO 8601 format. #### `replacement` Type: `object or null` Replacement invoice, or null when the operation is fully refunded, discounted or voided. ##### `replacement.id` Type: `string or null` FiscalRail invoice ID, or null when the original document was issued elsewhere. ##### `replacement.code` Type: `string` Human-readable invoice number. ##### `replacement.issue_date` Type: `string` Issue date of the referenced invoice in ISO 8601 format. #### `created_at` Type: `string` When FiscalRail recorded the amendment, in ISO 8601 format. ### Example ```json { "id": null, "object": "invoice_amendment", "live": null, "reason": null, "original": { "id": null, "code": null, "issue_date": null }, "credit_note": { "id": null, "code": null, "issue_date": null }, "replacement": { "id": null, "code": null, "issue_date": null }, "created_at": null } ``` ## Issue an invoice `POST /v1/invoices` Atomically validates, numbers and issues an immutable invoice. Omit `customer` to issue a simplified invoice. For Spanish accounts, its total including VAT cannot exceed 400.00 EUR. Spanish accounts resolve tax references from `tax` and `rule`; supplied resolved tax fields are not authoritative. A Spanish ordinary invoice requires the selected customer to have an address. Global invoices may snapshot a null customer address. Supply an optional `Idempotency-Key` to make retries safe. ### Headers #### `Idempotency-Key` Type: `string` A client-generated key that makes an invoice issuance safe to retry. Keys are scoped to the authenticated account, may contain at most 255 bytes, and must not be reused for another operation or different parameters. ### Request body #### `customer` Type: `object or null` Customer to snapshot on the invoice, or null for a simplified invoice. Spanish simplified invoices cannot exceed 400.00 EUR including VAT. #### `series` Type: `string` Defaults to the account's default invoice series. #### `issue_date` Type: `string` Defaults to the account's current local date. #### `supply_period` Type: `object` Optional period during which the goods or services were supplied. ##### `supply_period.start_date` Type: `string` — required First calendar date covered by the invoice. ##### `supply_period.end_date` Type: `string` — required Must be on or after `start_date`. #### `lines` Type: `array of objects` — required Line items to include on the invoice. ##### `lines.description` Type: `string` — required Description of the goods or services supplied. ##### `lines.quantity` Type: `number or string` A finite decimal with at most 18 digits and 6 decimal places, whose absolute value does not exceed 999999999999.999999. Defaults to `1`. ##### `lines.unit_price` Type: `number or string` — required Price per unit before taxes, as a decimal number or numeric string. ##### `lines.taxes` Type: `array of objects` — required Taxes applied to this line. Use regime-defined `tax` and `rule` values when available. ###### `lines.taxes.tax` Type: `string` — required Tax identifier defined by the account's tax regime, such as `vat`. ###### `lines.taxes.rule` Type: `string` — required Rule identifier defined by the selected tax, such as `general`. ###### `lines.taxes.effect` Type: `enum` Required only for custom taxes under the global regime. Possible values: - `added` — The tax amount is added to the invoice total. - `withheld` — The tax amount is withheld from the amount payable to the supplier. ###### `lines.taxes.treatment` Type: `enum` Used only for custom taxes under the global regime. Possible values: - `taxable` — Tax applies to the line at the supplied rate. - `exempt` — The line is exempt from the tax. - `reverse_charge` — The customer accounts for the tax under reverse charge. - `not_subject` — The line is outside the scope of the tax. ###### `lines.taxes.description` Type: `string` Human-readable tax label. Required only for custom taxes under the global regime. ###### `lines.taxes.rate` Type: `number or string` Required only for custom taxes under the global regime. ###### `lines.taxes.taxable_base` Type: `number or string` Optional taxable base override for this tax, as a decimal number or numeric string. ### Responses - `201` — [An Invoice object.](#the-invoice-object) Formats: JSON. ### Example request ```bash curl --request POST \ 'https://api.fiscalrail.com/v1/invoices' \ --header "Authorization: Bearer ak_test_..." \ --header "Idempotency-Key: 2f294ef2-9a60-4c7e-a573-5e18fa8348e2" \ --json '{ "customer": "cus_14Vxtqg6oXpAY5WdWoq4wW", "lines": [ { "description": "Consulting", "quantity": "8", "unit_price": "75.00", "taxes": [ { "tax": "vat", "rule": "general" } ] } ] }' ``` ### Example response — 201 ```json { "id": "inv_14Vxtqg6oXpAY5WdWoq4wW", "object": "invoice", "live": true, "account": "acct_14Vxtqg2nwvPR75TpsGH8N", "kind": "invoice", "code": "INV-00001", "series": "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ", "issue_date": "2026-07-31", "supply_period": null, "preceding_invoice": null, "currency": "EUR", "supplier": { "source": { "type": "account", "id": "acct_14Vxtqg2nwvPR75TpsGH8N" }, "name": "Example supplier", "tax_id": { "country": "ES", "type": "es_nif", "value": "B02850360" }, "email": null, "phone": null, "address": { "line_1": "Example street 1", "line_2": null, "city": "Madrid", "postal_code": "28001", "state": null, "country": "ES" } }, "customer": { "source": { "type": "customer", "id": "cus_14Vxtqg6oXpAY5WdWoq4wW" }, "name": "Acme SL", "tax_id": { "country": "ES", "type": "es_nif", "value": "B87654323" }, "email": "billing@example.com", "phone": null, "address": { "line_1": "Gran Via 1", "line_2": null, "city": "Madrid", "postal_code": "28013", "state": "Madrid", "country": "ES" } }, "lines": [ { "index": 1, "description": "Consulting", "quantity": "8.0", "unit_price": "75.00", "subtotal": "600.00", "taxes": [ { "tax": "vat", "rule": "general", "effect": "added", "treatment": "taxable", "description": "IVA 21%", "rate": "21%", "taxable_base": "600.00" } ] } ], "tax_totals": [ { "tax": "vat", "rule": "general", "effect": "added", "treatment": "taxable", "description": "IVA 21%", "rate": "21%", "taxable_base": "600.00", "amount": "126.00" } ], "totals": { "subtotal": "600.00", "tax": "126.00", "total_with_tax": "726.00", "withheld_tax": "0.00", "payable": "726.00" }, "created_at": "2026-07-31T09:30:00Z", "amendments": [], "tax_regime": { "key": "es", "es": { "qr": { "content": "https://prewww2.aeat.es/wlpl/TIKE-CONT/ValidarQR?nif=B02850360&numserie=INV-00001&fecha=31-07-2026&importe=726.00", "image_url": "https://api.fiscalrail.com/v1/invoices/inv_14Vxtqg6oXpAY5WdWoq4wW/qr.svg?signature=example" }, "verifactu": { "registrations": [ { "id": "es_inv_reg_14Vxtqg8mKp2Rs7Dc4Hn6Y", "object": "verifactu_registration", "live": true, "invoice": "inv_14Vxtqg6oXpAY5WdWoq4wW", "kind": "alta", "status": "accepted", "submitted_at": "2026-07-31T09:30:03Z", "csv": "ABCD1234", "error": null } ] } } } } ``` ## Amend or void an invoice `POST /v1/invoices/{invoice_id}/amendments` Atomically records an amendment and issues the required immutable documents. Most reasons fully credit the original and optionally issue a replacement. `issued_by_mistake` creates no invoice and, for Spanish accounts, sends a VERI*FACTU cancellation record. Supply an optional `Idempotency-Key` to make retries safe. A document can be amended once; apply any later amendment to its replacement invoice. ### Path parameters #### `invoice_id` Type: `string` — required The opaque ID of the invoice to amend or void. ### Headers #### `Idempotency-Key` Type: `string` A client-generated key that makes an invoice issuance safe to retry. Keys are scoped to the authenticated account, may contain at most 255 bytes, and must not be reused for another operation or different parameters. ### Request body #### `reason` Type: `enum` — required Why the original invoice was amended or voided. Possible values: - `refund` — Fully credits the original; provide a lower-value replacement for a partial refund. - `discount` — Fully credits the original; provide a lower-value replacement with unchanged quantities and tax treatment. - `incorrect_customer_details` — Replaces customer details while preserving the customer identity, lines and totals. - `incorrect_lines` — Replaces the lines while preserving the customer and tax treatment. - `incorrect_tax` — Replaces tax treatment or rates while preserving the customer and non-tax line details. - `customer_identification` — Adds or replaces customer tax identity while preserving lines and totals. - `issued_by_mistake` — Voids an invoice for an operation that never happened; no credit note or replacement is issued. #### `replacement` Type: `object` Final desired invoice after the full reversal. Required for customer and line or tax corrections, optional for refunds and discounts, and forbidden for `issued_by_mistake`. ##### `replacement.customer` Type: `object or null` Customer to snapshot on the invoice, or null for a simplified invoice. Spanish simplified invoices cannot exceed 400.00 EUR including VAT. ##### `replacement.series` Type: `string` Defaults to the account's default invoice series. ##### `replacement.issue_date` Type: `string` Defaults to the account's current local date. ##### `replacement.supply_period` Type: `object` Optional period during which the goods or services were supplied. ###### `replacement.supply_period.start_date` Type: `string` — required First calendar date covered by the invoice. ###### `replacement.supply_period.end_date` Type: `string` — required Must be on or after `start_date`. ##### `replacement.lines` Type: `array of objects` — required Line items to include on the invoice. ###### `replacement.lines.description` Type: `string` — required Description of the goods or services supplied. ###### `replacement.lines.quantity` Type: `number or string` A finite decimal with at most 18 digits and 6 decimal places, whose absolute value does not exceed 999999999999.999999. Defaults to `1`. ###### `replacement.lines.unit_price` Type: `number or string` — required Price per unit before taxes, as a decimal number or numeric string. ###### `replacement.lines.taxes` Type: `array of objects` — required Taxes applied to this line. Use regime-defined `tax` and `rule` values when available. ###### `replacement.lines.taxes.tax` Type: `string` — required Tax identifier defined by the account's tax regime, such as `vat`. ###### `replacement.lines.taxes.rule` Type: `string` — required Rule identifier defined by the selected tax, such as `general`. ###### `replacement.lines.taxes.effect` Type: `enum` Required only for custom taxes under the global regime. Possible values: - `added` — The tax amount is added to the invoice total. - `withheld` — The tax amount is withheld from the amount payable to the supplier. ###### `replacement.lines.taxes.treatment` Type: `enum` Used only for custom taxes under the global regime. Possible values: - `taxable` — Tax applies to the line at the supplied rate. - `exempt` — The line is exempt from the tax. - `reverse_charge` — The customer accounts for the tax under reverse charge. - `not_subject` — The line is outside the scope of the tax. ###### `replacement.lines.taxes.description` Type: `string` Human-readable tax label. Required only for custom taxes under the global regime. ###### `replacement.lines.taxes.rate` Type: `number or string` Required only for custom taxes under the global regime. ###### `replacement.lines.taxes.taxable_base` Type: `number or string` Optional taxable base override for this tax, as a decimal number or numeric string. ### Responses - `201` — [An Invoice Amendment object.](#the-invoice-amendment-object) Formats: JSON. ### Example request ```bash curl --request POST \ 'https://api.fiscalrail.com/v1/invoices/inv_14Vxtqg6oXpAY5WdWoq4wW/amendments' \ --header "Authorization: Bearer ak_test_..." \ --header "Idempotency-Key: 2f294ef2-9a60-4c7e-a573-5e18fa8348e2" \ --json '{ "reason": "discount", "replacement": { "customer": "cus_14Vxtqg6oXpAY5WdWoq4wW", "lines": [ { "description": "Consulting", "quantity": "8", "unit_price": "70.00", "taxes": [ { "tax": "vat", "rule": "general" } ] } ] } }' ``` ### Example response — 201 ```json { "id": null, "object": "invoice_amendment", "live": null, "reason": null, "original": { "id": null, "code": null, "issue_date": null }, "credit_note": { "id": null, "code": null, "issue_date": null }, "replacement": { "id": null, "code": null, "issue_date": null }, "created_at": null } ``` ## Retrieve an invoice `GET /v1/invoices/{id}` Returns an issued invoice by its opaque ID. The returned document is an immutable snapshot. ### Path parameters #### `id` Type: `string` — required The opaque ID of the invoice to retrieve. ### Responses - `200` — [An Invoice object.](#the-invoice-object) Formats: JSON. ### Example request ```bash curl --request GET \ 'https://api.fiscalrail.com/v1/invoices/inv_14Vxtqg6oXpAY5WdWoq4wW' \ --header "Authorization: Bearer ak_test_..." ``` ### Example response — 200 ```json { "id": "inv_14Vxtqg6oXpAY5WdWoq4wW", "object": "invoice", "live": true, "account": "acct_14Vxtqg2nwvPR75TpsGH8N", "kind": "invoice", "code": "INV-00001", "series": "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ", "issue_date": "2026-07-31", "supply_period": null, "preceding_invoice": null, "currency": "EUR", "supplier": { "source": { "type": "account", "id": "acct_14Vxtqg2nwvPR75TpsGH8N" }, "name": "Example supplier", "tax_id": { "country": "ES", "type": "es_nif", "value": "B02850360" }, "email": null, "phone": null, "address": { "line_1": "Example street 1", "line_2": null, "city": "Madrid", "postal_code": "28001", "state": null, "country": "ES" } }, "customer": { "source": { "type": "customer", "id": "cus_14Vxtqg6oXpAY5WdWoq4wW" }, "name": "Acme SL", "tax_id": { "country": "ES", "type": "es_nif", "value": "B87654323" }, "email": "billing@example.com", "phone": null, "address": { "line_1": "Gran Via 1", "line_2": null, "city": "Madrid", "postal_code": "28013", "state": "Madrid", "country": "ES" } }, "lines": [ { "index": 1, "description": "Consulting", "quantity": "8.0", "unit_price": "75.00", "subtotal": "600.00", "taxes": [ { "tax": "vat", "rule": "general", "effect": "added", "treatment": "taxable", "description": "IVA 21%", "rate": "21%", "taxable_base": "600.00" } ] } ], "tax_totals": [ { "tax": "vat", "rule": "general", "effect": "added", "treatment": "taxable", "description": "IVA 21%", "rate": "21%", "taxable_base": "600.00", "amount": "126.00" } ], "totals": { "subtotal": "600.00", "tax": "126.00", "total_with_tax": "726.00", "withheld_tax": "0.00", "payable": "726.00" }, "created_at": "2026-07-31T09:30:00Z", "amendments": [], "tax_regime": { "key": "es", "es": { "qr": { "content": "https://prewww2.aeat.es/wlpl/TIKE-CONT/ValidarQR?nif=B02850360&numserie=INV-00001&fecha=31-07-2026&importe=726.00", "image_url": "https://api.fiscalrail.com/v1/invoices/inv_14Vxtqg6oXpAY5WdWoq4wW/qr.svg?signature=example" }, "verifactu": { "registrations": [ { "id": "es_inv_reg_14Vxtqg8mKp2Rs7Dc4Hn6Y", "object": "verifactu_registration", "live": true, "invoice": "inv_14Vxtqg6oXpAY5WdWoq4wW", "kind": "alta", "status": "accepted", "submitted_at": "2026-07-31T09:30:03Z", "csv": "ABCD1234", "error": null } ] } } } } ``` ## List invoices `GET /v1/invoices` Returns issued invoices in reverse chronological ID order. Use only one cursor parameter at a time. ### Query parameters #### `q` Type: `string` Substring to search for in invoice ID or invoice number. #### `customer` Type: `string` Return only invoices for this customer. #### `issue_date_from` Type: `string` Return invoices issued on or after this date. #### `issue_date_to` Type: `string` Return invoices issued on or before this date. #### `limit` Type: `integer` Maximum number of resources to return. Defaults to `25`. #### `starting_after` Type: `string` Return invoices older than this invoice ID. #### `ending_before` Type: `string` Return invoices newer than this invoice ID. ### Responses - `200` — [A list of Invoice objects.](#the-invoice-object) Formats: JSON. ### Example request ```bash curl --request GET \ 'https://api.fiscalrail.com/v1/invoices?limit=25' \ --header "Authorization: Bearer ak_test_..." ``` ### Example response — 200 ```json { "object": "list", "has_more": null, "data": [ { "id": "inv_14Vxtqg6oXpAY5WdWoq4wW", "object": "invoice", "live": true, "account": "acct_14Vxtqg2nwvPR75TpsGH8N", "kind": "invoice", "code": "INV-00001", "series": "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ", "issue_date": "2026-07-31", "supply_period": null, "preceding_invoice": null, "currency": "EUR", "supplier": { "source": { "type": "account", "id": "acct_14Vxtqg2nwvPR75TpsGH8N" }, "name": "Example supplier", "tax_id": { "country": "ES", "type": "es_nif", "value": "B02850360" }, "email": null, "phone": null, "address": { "line_1": "Example street 1", "line_2": null, "city": "Madrid", "postal_code": "28001", "state": null, "country": "ES" } }, "customer": { "source": { "type": "customer", "id": "cus_14Vxtqg6oXpAY5WdWoq4wW" }, "name": "Acme SL", "tax_id": { "country": "ES", "type": "es_nif", "value": "B87654323" }, "email": "billing@example.com", "phone": null, "address": { "line_1": "Gran Via 1", "line_2": null, "city": "Madrid", "postal_code": "28013", "state": "Madrid", "country": "ES" } }, "lines": [ { "index": 1, "description": "Consulting", "quantity": "8.0", "unit_price": "75.00", "subtotal": "600.00", "taxes": [ { "tax": "vat", "rule": "general", "effect": "added", "treatment": "taxable", "description": "IVA 21%", "rate": "21%", "taxable_base": "600.00" } ] } ], "tax_totals": [ { "tax": "vat", "rule": "general", "effect": "added", "treatment": "taxable", "description": "IVA 21%", "rate": "21%", "taxable_base": "600.00", "amount": "126.00" } ], "totals": { "subtotal": "600.00", "tax": "126.00", "total_with_tax": "726.00", "withheld_tax": "0.00", "payable": "726.00" }, "created_at": "2026-07-31T09:30:00Z", "amendments": [], "tax_regime": { "key": "es", "es": { "qr": { "content": "https://prewww2.aeat.es/wlpl/TIKE-CONT/ValidarQR?nif=B02850360&numserie=INV-00001&fecha=31-07-2026&importe=726.00", "image_url": "https://api.fiscalrail.com/v1/invoices/inv_14Vxtqg6oXpAY5WdWoq4wW/qr.svg?signature=example" }, "verifactu": { "registrations": [ { "id": "es_inv_reg_14Vxtqg8mKp2Rs7Dc4Hn6Y", "object": "verifactu_registration", "live": true, "invoice": "inv_14Vxtqg6oXpAY5WdWoq4wW", "kind": "alta", "status": "accepted", "submitted_at": "2026-07-31T09:30:03Z", "csv": "ABCD1234", "error": null } ] } } } } ] } ```