E-invoice lifecycle

This page explains what happens to a document from the moment you send it to POST /v1/send until it reaches a final outcome, which parts happen while your request is open, which happen afterwards, and how you find out the result. It applies to every country and every way of getting data in: the API, CSV upload, the dashboard and every accounting or payment integration.

Stored first, then processed

1. Envelope check. Authentication, plan access, rate limit, valid JSON, correct field types and the identifying fields. Only a request that fails here is answered with an error status (400, 401, 403, 413 or 429), and nothing is stored.
2. Store. The document is saved exactly as you sent it, with status RECEIVED. From this point it cannot disappear.
3. Process, in the same request. Clearvo normalises and enriches the data, runs the validation rules, resolves the tax code, works out which mandate applies, checks that your setup is complete, then generates the country's document and checks it against the schema. Each step either moves the document on or stops it in exactly one status.
4. Respond with 200. The body carries the status the document has reached.
5. Finish asynchronously, where a tax authority or network is involved. Submission to the authority, clearance polling and delivery happen after your request has returned. The status changes and you are told through GET /v1/status or a webhook.

Nothing that was accepted is lost, and nothing waits in a state forever without someone being told.

What is synchronous and what is not

These steps always happen before POST /v1/send returns: the envelope check, storing the document, normalisation, enrichment, validation rules, tax code resolution, mandate resolution, setup checks, and generating and schema-checking the document.

What happens after that depends on how the country works:

A 200 never means the authority has accepted the document. Read outcome and clearanceStatus, and keep checking while terminal is false.

HTTP status codes

The key rule for integrations: a 2xx means "stored", not "succeeded". Check outcome before you mark a document as sent in your own system. POST /v1/invoices/{id}/retry follows the same rule: if the authority rejects the retried document, the answer is 200 with ok: false and clearanceStatus: REJECTED.

Response fields

statusClass and nextStep are returned by POST /v1/send (including the bodies for stored rejections and holds), GET /v1/status and GET /v1/invoices/{id}.

nextStep

nextStep is null when nothing is outstanding, for example for ACCEPTED, DELIVERED, CANCELLED, DUPLICATE, NO_MANDATE, EXCLUDED and NOT_SUPPORTED.

Statuses

There is one status model for every country. The class tells you who, if anyone, has to act.

In progress: we are working on it (IN_FLIGHT)

Waiting for you (WAIT_MERCHANT)

A document waiting for you never expires. When enabled for your account, Clearvo reminds the entity's users by email on day 3 and day 7, then in a weekly digest, until it is resolved. Reminders are not on for every account, so watch GET /v1/status or the invoice.status_changed webhook rather than relying on them.

Waiting for us (WAIT_PLATFORM)

Finished (DONE_OK, DONE_REJECTED, DONE_NA)

NO_MANDATE, EXCLUDED, NOT_SUPPORTED and DUPLICATE are in the class DONE_NA: nothing was or will be submitted, and they are finished outcomes, not errors.

No obligation and not supported

A document that needs no e-invoicing is a normal, finished result, shown with outcome: NO_OBLIGATION. It is never held and never needs action.

A document is only submitted when its document date is on or after both the date the obligation started for your entity and the date Clearvo began supporting that country's mandate. A document dated earlier than the date Clearvo supports the mandate is NOT_SUPPORTED: it stays visible in your list and is never submitted later, even if support is added afterwards. This stops old documents being sent to an authority by accident when a country goes live. A document dated on or after the support start date for a country that is not yet enabled for your account is not NOT_SUPPORTED: it is held with HELD_AWAITING_AUTHORIZATION with 200 and nothing needed from you. Clearvo sends it automatically once the country is enabled for your account; you do not need to resend it. This applies to live Portugal sends, Greece, Malaysia, Israel, Egypt and Jordan.

How you find out the final status

1. The response to POST /v1/send

The status as it was when the request ended. For countries where the document is issued in the request, that is already final.

2. Poll GET /v1/status

GET /v1/status (and GET /v1/invoices/{id}) reads the stored status. It does not call the authority, so polling cannot cause extra submissions. Call it until terminal is true, using nextPollAfter to space the calls. It works for any document Clearvo has accepted, including one that is still RECEIVED.

3. Webhooks

Webhooks tell you when the status changes, so you do not have to poll. Register an endpoint with POST /v1/webhooks.

• invoice.status_changed fires on every status change of a document: RECEIVED when it is stored, a hold, a release, a retry, an authority answer. Choose the statuses you care about with the statuses field when you register, for example ["NEEDS_INFO", "SETUP_NEEDED"] to be told when you must act, or ["ACCEPTED", "REJECTED"] for the final answer. Leave statuses out to receive every change. It is not included in "*": list it by name in events. An unknown status, or statuses without invoice.status_changed in events, is a 400. The payload is lean: eventId (the same on every delivery retry, so dedupe on it), seq (increases with every status change of one invoice; deliveries can arrive out of order, so order an invoice's events by seq and ignore one lower than the highest you have applied), id, from (empty for the first status), to, statusClass, terminal, nextStep, a reason with a code, a message, who caused the change (authority, rule, system, merchant or platform) and a fixUrl when you can act, and at. Fetch GET /v1/invoices/{id} for the full detail. Partner webhooks that cover every organisation take the same statuses field.
• The existing events keep working, for example invoice.accepted and invoice.rejected, with their existing payloads. New integrations should use invoice.status_changed. If you subscribe to both, you receive two deliveries for one change, each with its own delivery id.
• Reminders are not webhooks, and there is no separate "needs attention" or "released" event: choose the statuses you care about on invoice.status_changed instead. Where reminders are enabled they arrive by email and in the dashboard.

Webhooks are retried for up to 10 attempts and signed, see Webhooks & events.

Retries and identity

• Clearvo identifies a document by its own key, built from the document type, country, invoice number and, for purchases, the supplier and date. This is the only thing used to detect a duplicate.
• x-idempotency-key is optional. It never blocks a document. If you reuse a key for a different document, Clearvo processes the new document under its own identity and returns the warning IDEMPOTENCY_KEY_REUSED_ACROSS_DOCUMENTS in warnings[]. It no longer returns 409 IDEMPOTENCY_KEY_REUSED.
• A document with no identifying fields (no usable invoice number) is no longer refused. It is stored under your x-idempotency-key if you sent one, otherwise under an identity Clearvo creates, and the response carries the warning NO_IDENTITY_NO_DEDUP: duplicates cannot be detected. A blind retry of such a document creates a second record. The error MISSING_IDENTITY_FIELD no longer exists.
• An identical re-send replays the stored result. A re-send of a document that is waiting for you (NEEDS_INFO, REJECTED or a hold) with changed content re-runs the stored document. A changed re-send of a document that has already been processed is refused with 409 IDEMPOTENT_BODY_MISMATCH and recorded in its history as a refused_resend event.

Sandbox

The sandbox uses the same API and the same lifecycle as live. Sandbox documents are accepted and stored the same way, and the authority step is simulated, see Sandbox & testing. Sandbox and live data are kept apart: a sandbox key never touches a live document.

Tax calculations are different

A tax calculation is an immediate request and response, with nothing pending afterwards, so it has its own, simpler lifecycle. See Tax Calculations.