Amendments and locking

You own the values. To change a document, change it in your ERP and send the whole document again with a newer source_updated_at. VAT IT never edits what you send.

Line statuses

Each line has its own status, because the lines of one invoice can fall under different registrations and returns, and lock at different times. The document carries a summary for list screens: its validity is its worst line's, and its status is its least advanced line's.

Status	Meaning	Who acts
received	Stored, waiting for the next processing cycle	Nobody
unrouted	Not yet matched to a VAT registration	VAT IT, or you if the data is wrong. It reprocesses once fixed
processed	Checked. validity is valid, warning or error	You, to clear errors
locked	On a filed return	Only a correction reopens it
voided	Withdrawn before filing	Nobody
out_of_scope	For a registration VAT IT does not serve for this client. No error, no effect on any return	Nobody

Changing a document

• Before filing. Send the whole document again with a newer source_updated_at. The new version replaces the old one in full, so a line you leave out is removed, and the return recalculates. Deltas are not accepted.
• After filing. A new version of a locked document is stored but not applied. It shows as pending_version with locked_filed, until VAT IT opens a correction. The new version is then applied to the correction, and shows correction_open until the correction is filed.
• Voiding. Send client_ref, document_id, source_updated_at and "action": "void". Before filing the document is voided. After filing it waits for a correction, like any other change.

Credit notes, edits and voids: which to send

A credit note is a document in its own right. It never replaces, voids or edits the invoice it credits. The invoice stays as it was, the credit note reduces the return in its own period, and original_invoice_number links the two. A void is only for a document that should never have existed.

What happened in your ERP	What you send	Never
An invoice was raised	A new document, document_type: invoice
An invoice was corrected before it reached the customer	The same document_id again, with a newer source_updated_at	A credit note
A credit note was issued against an invoice	A new document with its own document_id, document_type: credit_note, negative amounts, original_invoice_number and original_invoice_date	A void of the invoice, or a new version of it
A credit note was issued against an invoice on a filed return	The same as above. The credit note lands in the period of its own date, and the filed return is untouched	A change to the invoice
A document was raised in error and never issued	"action": "void" on that document_id	A credit note

Amounts on a credit note are signed as printed, so they are usually negative. A credit note whose lines add up to more than zero is refused with total_sign_invalid. See Sending transactions.

Versions

You send	VAT IT does
The same document, same source_updated_at, same body	Nothing. Returns duplicate with the original result
A newer source_updated_at	Replaces the document and all its lines
An older source_updated_at	Ignores it with stale_version, so out-of-order retries are safe
The same source_updated_at, different body	Refuses it with version_conflict

Keep line_id the same across versions, so your screens and VAT IT's track the same line from one version to the next.

What VAT IT may record

VAT IT never changes amounts, dates, VAT numbers or tax codes. A tax associate may move a line to another reporting period, or change its classification when the tax code mapping was wrong for that document. Each appears in the line's vat_it_adjustments, so your view always reconciles with the return.