New France e-invoicing mandate goes live September 2026 — our implementation is ready. See all mandates →
Guides

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.

Guides

What a fix does

The invoice isWhat happensmode
Held because it is missing informationSupply exactly the fields listed in resolution.missingFields. The invoice is updated in place and sent again.updated_in_place
Rejected, and its source allows changesA corrected invoice is created and linked to the original. The response carries both ids.new_invoice
A submitted e-reportThe report is amended. Amending a reported Spain SII registration is allowed from every source.amended
Sent through the API or an ERPIt 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-invoiceIssued e-invoices are never edited. The call answers 409 NOT_FIXABLE.none
Guides

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.

FieldMeaning
fixtrue when the fix call can act on this invoice now.
canSupplytrue 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).
canChangeValuestrue when existing values, not only missing ones, can be changed.
sourceWhere the invoice came from.
lockedReasonIn plain words, why the invoice cannot be edited in Clearvo, when its source is the reason.
fixModeWhat a fix would do: updated_in_place, new_invoice or amended.
editableDocumentThe stored document the dotted paths point into. Set when a fix creates a corrected invoice or amends a report; null otherwise.
editableFieldsThe fields that can be changed. null means free-form: any path in editableDocument.
availableActionsWhat can be done now: retry, fix, issue_credit_note, amend_report or cancel_report.
API reference

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
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" } }'
Response
{
  "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

StatusCodeMeaning
404No such invoice, or it is not yours.
409NOT_FIXABLEThis invoice cannot be fixed, for example an issued e-invoice. The body names its status and reason.
409SOURCE_LOCKEDThe 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.
422INVALID_FIELDSerrors[] lists { field, code, message }, with code one of INVALID_PATH, INVALID_VALUE, NOT_SUPPLIABLE or LOCKED_CHANNEL.
503FIX_UNAVAILABLERetryable. Nothing was changed.

Errors use the standard shape: { ok: false, error: { code, message, retryable }, hint }. See Errors & status codes.

Guides

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-run to check first)
  • MCP: the fix_invoice tool. Call get_invoice first and read its resolution.