Invoices
Issue, retrieve and list immutable invoices.
View as Markdown
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 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.
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
string
Opaque identifier for the invoice.
object
string
String identifying this as an Invoice object. Always
invoice.live
boolean
True when the object belongs to the live environment; false for test data.
account
string
Account that issued the invoice.
kind
enum
Commercial document kind. This is independent from tax-regime rectification codes.
Possible values
invoice
credit_note
code
string
Human-readable invoice number assigned from the selected series.
series
string
Invoicing series used to number the invoice.
issue_date
string
Legal issue date in ISO 8601 format.
supply_period
object or null
Period covered by the invoice, or null when it was not provided.
Show child propertiesHide child properties
start_date
string
First calendar date covered by the invoice.
end_date
string
Last calendar date covered by the invoice.
preceding_invoice
object or null
Invoice corrected by this document, or null when this is not a correction.
Show child propertiesHide child properties
id
string or null
FiscalRail invoice ID, or null when the original document was issued elsewhere.
code
string
Human-readable invoice number.
issue_date
string
Issue date of the referenced invoice in ISO 8601 format.
currency
string
ISO 4217 currency code used for every monetary amount. Always
EUR.supplier
object
Immutable snapshot of the supplier at issuance.
Show child propertiesHide child properties
source
object
Resource from which this immutable party snapshot was created.
Show child propertiesHide child properties
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.
id
string
Account or customer ID, according to
type.name
string
Legal or trading name at issuance.
tax_id
object
Fiscal identifier at issuance.
Show child propertiesHide child properties
country
string
ISO 3166-1 alpha-2 country associated with the tax ID at issuance.
type
string
FiscalRail's normalized fiscal identifier type at issuance.
value
string
The normalized fiscal identifier value at issuance.
email
string or null
Email address at issuance, or null when absent.
phone
string or null
Phone number at issuance, or null when absent.
address
object or null
Address at issuance, or null when a global invoice was issued without one.
Show child propertiesHide child properties
line_1
string
Primary street address.
line_2
string or null
Additional address information, or null when not supplied.
city
string
City or locality.
postal_code
string
Postal or ZIP code.
state
string or null
State, province, or region, or null when not applicable.
country
string
ISO 3166-1 alpha-2 country code.
customer
object or null
Immutable customer snapshot, or null for a simplified invoice.
Show child propertiesHide child properties
source
object
Resource from which this immutable party snapshot was created.
Show child propertiesHide child properties
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.
id
string
Account or customer ID, according to
type.name
string
Legal or trading name at issuance.
tax_id
object
Fiscal identifier at issuance.
Show child propertiesHide child properties
country
string
ISO 3166-1 alpha-2 country associated with the tax ID at issuance.
type
string
FiscalRail's normalized fiscal identifier type at issuance.
value
string
The normalized fiscal identifier value at issuance.
email
string or null
Email address at issuance, or null when absent.
phone
string or null
Phone number at issuance, or null when absent.
address
object or null
Address at issuance, or null when a global invoice was issued without one.
Show child propertiesHide child properties
line_1
string
Primary street address.
line_2
string or null
Additional address information, or null when not supplied.
city
string
City or locality.
postal_code
string
Postal or ZIP code.
state
string or null
State, province, or region, or null when not applicable.
country
string
ISO 3166-1 alpha-2 country code.
lines
array of objects
Immutable invoice line items and their resolved taxes.
Show child propertiesHide child properties
index
integer
One-based position of the line on the invoice.
description
string
Description of the goods or services captured at issuance.
quantity
string
Quantity represented as a decimal string.
unit_price
string
Price per unit before taxes.
subtotal
string
Line amount before taxes.
taxes
array of objects
Resolved taxes applied to the line.
Show child propertiesHide child properties
tax
string
Stable tax identifier from the invoice's tax regime.
rule
string
Stable rule identifier within the tax.
effect
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.
treatment
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.
description
string
Tax label resolved from the regime catalog or supplied for a custom tax, captured at issuance.
rate
string or null
Percentage rate; zero for exempt or reverse-charge taxes, and null for not-subject operations.
taxable_base
string
Amount on which this tax is calculated.
tax_totals
array of objects
Taxes aggregated across all line items.
Show child propertiesHide child properties
tax
string
Stable tax identifier from the invoice's tax regime.
rule
string
Stable rule identifier within the tax.
effect
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.
treatment
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.
description
string
Tax label resolved from the regime catalog or supplied for a custom tax, captured at issuance.
rate
string or null
Percentage rate; zero for exempt or reverse-charge taxes, and null for not-subject operations.
taxable_base
string
Amount on which this tax is calculated.
amount
string
Tax amount aggregated across invoice lines.
totals
object
Monetary totals calculated for the invoice.
Show child propertiesHide child properties
subtotal
string
Sum of line subtotals before taxes.
tax
string
Total tax added to the invoice.
total_with_tax
string
Subtotal plus taxes added to the invoice.
withheld_tax
string
Total tax withheld from the supplier.
payable
string
Final amount payable after added and withheld taxes.
created_at
string
When FiscalRail stored the issued invoice, in ISO 8601 format.
tax_regime
object
Regime-specific compliance state attached to the invoice.
Show child propertiesHide child properties
Global invoice tax regime
key
string
Identifies the global tax regime. Always
global.Spanish invoice tax regime
key
string
Identifies the Spanish tax regime. Always
es.es
object
Spanish invoice compliance details.
Show child propertiesHide child properties
qr
object
AEAT QR data for the invoice.
Show child propertiesHide child properties
content
string
Exact content encoded in the invoice's AEAT QR code.
image_url
string
Permanent signed URL for the compliant SVG QR image.
verifactu
object
VERI*FACTU registration state for the invoice.
Show child propertiesHide child properties
registrations
array of objects
Registration attempts for this invoice, newest first.
Show child propertiesHide child properties
id
string
Opaque identifier for the VERI*FACTU registration.
object
string
String identifying this as a VERI*FACTU registration object. Always
verifactu_registration.live
boolean
True when the object belongs to the live environment; false for test data.
invoice
string
Invoice submitted by this registration.
kind
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.
status
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.
submitted_at
string or null
When the registration was last submitted to AEAT, or null before submission.
csv
string or null
AEAT secure verification code, or null when AEAT has not supplied one.
error
object or null
Structured rejection or submission error, or null when there is no error.
amendments
array of objects
Amendments that connect this invoice to its original, credit note and replacement.
Show child propertiesHide child properties
id
string
Opaque identifier for the amendment.
object
string
String identifying this as an Invoice Amendment object. Always
invoice_amendment.live
boolean
True when the object belongs to the live environment; false for test data.
reason
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
object
Invoice being reversed or voided.
Show child propertiesHide child properties
id
string or null
FiscalRail invoice ID, or null when the original document was issued elsewhere.
code
string
Human-readable invoice number.
issue_date
string
Issue date of the referenced invoice in ISO 8601 format.
credit_note
object or null
Full credit note, or null for an invoice issued by mistake.
Show child propertiesHide child properties
id
string or null
FiscalRail invoice ID, or null when the original document was issued elsewhere.
code
string
Human-readable invoice number.
issue_date
string
Issue date of the referenced invoice in ISO 8601 format.
replacement
object or null
Replacement invoice, or null when the operation is fully refunded, discounted or voided.
Show child propertiesHide child properties
id
string or null
FiscalRail invoice ID, or null when the original document was issued elsewhere.
code
string
Human-readable invoice number.
issue_date
string
Issue date of the referenced invoice in ISO 8601 format.
created_at
string
When FiscalRail recorded the amendment, in ISO 8601 format.
{
"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
string
Opaque identifier for the amendment.
object
string
String identifying this as an Invoice Amendment object. Always
invoice_amendment.live
boolean
True when the object belongs to the live environment; false for test data.
reason
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
object
Invoice being reversed or voided.
Show child propertiesHide child properties
id
string or null
FiscalRail invoice ID, or null when the original document was issued elsewhere.
code
string
Human-readable invoice number.
issue_date
string
Issue date of the referenced invoice in ISO 8601 format.
credit_note
object or null
Full credit note, or null for an invoice issued by mistake.
Show child propertiesHide child properties
id
string or null
FiscalRail invoice ID, or null when the original document was issued elsewhere.
code
string
Human-readable invoice number.
issue_date
string
Issue date of the referenced invoice in ISO 8601 format.
replacement
object or null
Replacement invoice, or null when the operation is fully refunded, discounted or voided.
Show child propertiesHide child properties
id
string or null
FiscalRail invoice ID, or null when the original document was issued elsewhere.
code
string
Human-readable invoice number.
issue_date
string
Issue date of the referenced invoice in ISO 8601 format.
created_at
string
When FiscalRail recorded the amendment, in ISO 8601 format.
{
"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/invoicesAtomically 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
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
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
string
Defaults to the account's default invoice series.
issue_date
string
Defaults to the account's current local date.
supply_period
object
Optional period during which the goods or services were supplied.
Show child propertiesHide child properties
start_date
string
required
First calendar date covered by the invoice.
end_date
string
required
Must be on or after
start_date.lines
array of objects
required
Line items to include on the invoice.
Show child propertiesHide child properties
description
string
required
Description of the goods or services supplied.
quantity
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.unit_price
number or string
required
Price per unit before taxes, as a decimal number or numeric string.
taxes
array of objects
required
Taxes applied to this line. Use regime-defined
tax and rule values when available.Show child propertiesHide child properties
tax
string
required
Tax identifier defined by the account's tax regime, such as
vat.rule
string
required
Rule identifier defined by the selected tax, such as
general.effect
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.
treatment
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.
description
string
Human-readable tax label. Required only for custom taxes under the global regime.
rate
number or string
Required only for custom taxes under the global regime.
taxable_base
number or string
Optional taxable base override for this tax, as a decimal number or numeric string.
Responses
201
An Invoice object.
JSON
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"
}
]
}
]
}'{
"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}/amendmentsAtomically 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
string
required
The opaque ID of the invoice to amend or void.
Headers
Idempotency-Key
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
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
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.Show child propertiesHide child properties
customer
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
string
Defaults to the account's default invoice series.
issue_date
string
Defaults to the account's current local date.
supply_period
object
Optional period during which the goods or services were supplied.
Show child propertiesHide child properties
start_date
string
required
First calendar date covered by the invoice.
end_date
string
required
Must be on or after
start_date.lines
array of objects
required
Line items to include on the invoice.
Show child propertiesHide child properties
description
string
required
Description of the goods or services supplied.
quantity
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.unit_price
number or string
required
Price per unit before taxes, as a decimal number or numeric string.
taxes
array of objects
required
Taxes applied to this line. Use regime-defined
tax and rule values when available.Show child propertiesHide child properties
tax
string
required
Tax identifier defined by the account's tax regime, such as
vat.rule
string
required
Rule identifier defined by the selected tax, such as
general.effect
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.
treatment
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.
description
string
Human-readable tax label. Required only for custom taxes under the global regime.
rate
number or string
Required only for custom taxes under the global regime.
taxable_base
number or string
Optional taxable base override for this tax, as a decimal number or numeric string.
Responses
201
An Invoice Amendment object.
JSON
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"
}
]
}
]
}
}'{
"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
string
required
The opaque ID of the invoice to retrieve.
Responses
200
An Invoice object.
JSON
curl --request GET \
'https://api.fiscalrail.com/v1/invoices/inv_14Vxtqg6oXpAY5WdWoq4wW' \
--header "Authorization: Bearer ak_test_..."{
"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/invoicesReturns issued invoices in reverse chronological ID order. Use only
one cursor parameter at a time.
Query parameters
q
string
Substring to search for in invoice ID or invoice number.
customer
string
Return only invoices for this customer.
issue_date_from
string
Return invoices issued on or after this date.
issue_date_to
string
Return invoices issued on or before this date.
limit
integer
Maximum number of resources to return. Defaults to
25.starting_after
string
Return invoices older than this invoice ID.
ending_before
string
Return invoices newer than this invoice ID.
Responses
200
A list of Invoice objects.
JSON
curl --request GET \
'https://api.fiscalrail.com/v1/invoices?limit=25' \
--header "Authorization: Bearer ak_test_..."{
"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
}
]
}
}
}
}
]
}