Correcting invoices — FiscalRail documentation

Issued invoices are immutable: changing the customer or deleting a line later cannot alter what was issued. When something needs correcting, create an amendment against the original invoice. FiscalRail records the reason and atomically creates the documents required by that correction.

Choose the correction

The reason determines what FiscalRail creates:

Reason	Use it when	Result
`refund`	Some or all of the operation is refunded.	Full credit note, plus an optional lower-value replacement.
`discount`	A discount is granted after issuance.	Full credit note, plus an optional lower-value replacement preserving quantities and tax treatment.
`incorrect_customer_details`	The customer's non-fiscal details were wrong.	Full credit note and required replacement for the same customer and Tax ID.
`incorrect_lines`	Descriptions, quantities or prices were wrong.	Full credit note and required replacement preserving the tax treatment.
`incorrect_tax`	The tax treatment or rate was wrong.	Full credit note and required replacement preserving the commercial line details.
`customer_identification`	A recipient must be added or its fiscal identity corrected.	Full credit note and required replacement with the correct identified customer.
`issued_by_mistake`	The underlying operation never happened and the invoice should not exist.	Voids the invoice without creating a credit note or replacement.

issued_by_mistake is not a shortcut for refunds or ordinary mistakes. For Spanish accounts it creates a VERI*FACTU cancellation record for the original invoice.

Issue the amendment

This example corrects the lines and issues a replacement. It assumes INVOICE_ID contains the invoice being corrected.

curl "https://api.fiscalrail.com/v1/invoices/$INVOICE_ID/amendments" \
  --request POST \
  --header "Authorization: Bearer ak_test_..." \
  --header "Idempotency-Key: 607943a8-c7a9-48bb-a27a-87995250af0f" \
  --header "Content-Type: application/json" \
  --data '{
    "reason": "incorrect_lines",
    "replacement": {
      "lines": [{
        "description": "Consulting",
        "quantity": "2",
        "unit_price": "70.00",
        "taxes": [{"tax": "vat", "rule": "general"}]
      }]
    }
  }'

The response is an invoice_amendment containing references to the original, the full credit note and the replacement. The credit note reverses the original in full; the replacement expresses the corrected commercial result.

The whole operation is atomic. If any generated document is invalid, none of the amendment documents are issued and no series number is consumed.

Retry safely

Always send an Idempotency-Key. If the connection fails after FiscalRail commits the amendment, retry the exact request with the same key. FiscalRail returns the original result instead of correcting the invoice twice.

Each document can be amended once. If the replacement later needs another correction, create the next amendment against the replacement rather than the first invoice.

Follow the result

The original, credit note and replacement remain independently retrievable invoices. Their preceding_invoice fields preserve the correction relationship, while their shared amendments entry exposes the complete operation.

An invoice.amended event is emitted for the amendment, and each generated invoice emits its own invoice.issued event. Webhook delivery is not ordered, so consumers should use IDs and relationships rather than assuming which event arrives first.

Spanish accounts also generate the corresponding VERI*FACTU registration or cancellation records. Subscribe to the invoice.verifactu_registration.* events to learn their terminal outcomes.

See the Invoice API reference for every reason-specific validation rule and response field.