Fix a held invoice
When an invoice is waiting for you, or was rejected, one call puts it right: POST /v1/invoices/{id}/fix. You send the values as dotted field paths, and Clearvo tells you what it did. What a fix does depends on the invoice, and GET /v1/invoices/{id} tells you in advance in its resolution block.
What a fix does
| The invoice is | What happens | mode |
|---|---|---|
| Held because it is missing information | Supply exactly the fields listed in resolution.missingFields. The invoice is updated in place and sent again. | updated_in_place |
| Rejected, and its source allows changes | A corrected invoice is created and linked to the original. The response carries both ids. | new_invoice |
| A submitted e-report | The report is amended. Amending a reported Spain SII registration is allowed from every source. | amended |
| Sent through the API or an ERP | It cannot be corrected or have values changed in Clearvo: fix it in the source system and it resubmits (409 SOURCE_LOCKED). Missing values can always be supplied. | none |
| An issued e-invoice | Issued e-invoices are never edited. The call answers 409 NOT_FIXABLE. | none |
Read the resolution first
GET /v1/invoices/{id} returns a resolution block. Use it to decide whether to show a form, and which inputs it needs.
| Field | Meaning |
|---|---|
fix | true when the fix call can act on this invoice now. |
canSupply | true when the invoice is waiting for information you can supply. |
missingFields[] | What is still needed: field (the dotted path to send), label (a name to show), inputType (the kind of input, for example text, country or date) and suppliable (whether Clearvo accepts a value for it). |
canChangeValues | true when existing values, not only missing ones, can be changed. |
source | Where the invoice came from. |
lockedReason | In plain words, why the invoice cannot be edited in Clearvo, when its source is the reason. |
fixMode | What a fix would do: updated_in_place, new_invoice or amended. |
editableDocument | The stored document the dotted paths point into. Set when a fix creates a corrected invoice or amends a report; null otherwise. |
editableFields | The fields that can be changed. null means free-form: any path in editableDocument. |
availableActions | What can be done now: retry, fix, issue_credit_note, amend_report or cancel_report. |
Fix an invoice
POST /v1/invoices/{id}/fix. {id} is the Clearvo invoice id or your reference id. Send x-entity-id when your key covers more than one entity.
curl -X POST https://api.clearvo.io/v1/invoices/inv_123/fix \
-H "x-api-key: $CLEARVO_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "fields": { "customer.address.country": "DE" } }'
{
"ok": true,
"mode": "updated_in_place",
"invoiceId": "inv_123",
"status": "PENDING",
"clearanceStatus": "PENDING",
"changes": [
{ "field": "customer.address.country", "mode": "supply", "newValue": "DE" }
],
"completed": true,
"missingFields": []
}
When mode is new_invoice, invoiceId is the corrected invoice and previousInvoiceId is the original. Each entry in changes has a mode of supply (a missing value was filled in), change (an existing value was replaced) or clear (a value was deleted). completed is true when nothing is missing any more, and missingFields lists what still is. The answer is 200, or 202 while the invoice is still being processed. Field paths accept array indexes, as lines.0.quantity or lines[0].quantity.
Clear a value
To remove a value from the corrected document, list its path in clear: { "fields": {}, "clear": ["customer.address.line2"] }. There is no null meaning. A path cannot be in both fields and clear. A source that is locked refuses clearing an existing value (409 SOURCE_LOCKED).
Check first
Add "dryRun": true to the body to see what a fix would do. Nothing is changed, and the answer is { "id": "inv_123", "wouldSubmit": { "mode": "updated_in_place", "changes": [ ... ] } }. The MCP tool also takes a confirmationToken for its check-first step (operation invoice.fix).
Errors
| Status | Code | Meaning |
|---|---|---|
404 | No such invoice, or it is not yours. | |
409 | NOT_FIXABLE | This invoice cannot be fixed, for example an issued e-invoice. The body names its status and reason. |
409 | SOURCE_LOCKED | The invoice came through the API or an ERP, so it cannot be corrected or have values changed here. Fix it in the source system. errors[] lists the fields. Missing values can always be supplied. |
422 | INVALID_FIELDS | errors[] lists { field, code, message }, with code one of INVALID_PATH, INVALID_VALUE, NOT_SUPPLIABLE or LOCKED_CHANNEL. |
503 | FIX_UNAVAILABLE | Retryable. Nothing was changed. |
Errors use the standard shape: { ok: false, error: { code, message, retryable }, hint }. See Errors & status codes.
From the SDK, CLI or an AI agent
- SDK:
client.fixInvoice({ id, fields }) - CLI:
clearvo invoices fix <id> --field customer.address.country=DE(add--clear <path>to delete a value,--dry-runto check first) - MCP: the
fix_invoicetool. Callget_invoicefirst and read itsresolution.