E-Invoicing
The E-Invoicing API submits, clears, and tracks B2B invoices across 37 countries, directly with tax authorities or over the Peppol network (two are receive-only) — SDI, KSeF, ANAF, myDATA, XRechnung, Peppol, and more. One JSON payload in; the correct country format, authority submission, and clearance tracking handled for you.
https://api.clearvo.io/v1) and the same csk_live_* / csk_test_* key system as every other Clearvo product — see Authentication. No separate credentials needed. Plain HTTP requests are automatically redirected to HTTPS (307 Temporary Redirect).New to Clearvo? See the docs home for Tax Calculations, Tax Number Validation and Compliance Radar.
How it works
You send one JSON payload to POST /send. Clearvo transforms it into the correct country format (FatturaPA, FA(3), XRechnung, etc.), submits it to the relevant authority, and returns a referenceId. You then poll GET /status or receive a webhook when the clearance status changes.
Send a POST /send request with your invoice data. Receive a referenceId and initial status.
Call GET /status on a schedule, or configure a webhook to receive push notifications on every status transition.
A terminal status ends the lifecycle. A status that is not terminal is either in progress (keep polling or wait for the webhook) or waiting for you or for us. A 200 response means the document is stored, not that it succeeded: read status. See the e-invoice lifecycle for every status and what to do.
Quickstart
Submit your first invoice in under two minutes. This example sends an Italian B2B invoice to the SDI.
curl https://api.clearvo.io/v1/send \
-X POST \
-H "x-api-key: csk_live_••••••••••••" \
-H "x-idempotency-key: a3f9c2d1-e847-4b6a-9c12-d3f0e1a2b7c8" \
-H "Content-Type: application/json" \
-d '{
"documentType": "invoice",
"invoiceNumber": "INV-2024-001",
"issueDate": "2024-01-15",
"currency": "EUR",
"country": "IT",
"customer": {
"name": "Cliente SpA",
"taxId": "09876543210",
"establishmentCountry": "IT",
"address": { "street": "Via Veneto 10", "city": "Roma", "postalCode": "00187", "country": "IT" }
},
"lines": [
{ "description": "Software licence Q1", "quantity": 1, "unitPrice": 1000.00, "taxRate": 22 },
{ "description": "Support hours", "quantity": 8, "unitPrice": 125.00, "taxRate": 22 }
]
}'
A successful response returns:
{
"ok": true,
"country": "IT",
"referenceId": "IT-20240115-INV-001",
"status": "PENDING",
"stage": "awaiting_authority",
"reason": "PENDING",
"terminal": false,
"submittedAt": "2024-01-15T10:30:00Z",
"nextPollAfter": "2024-01-15T10:35:00Z"
}
Store the referenceId — you'll use it to poll for the final clearance decision.
POST /send
Submit a new invoice for clearance. Clearvo validates the payload, generates the country-specific XML format, and forwards it to the relevant tax authority.
POST https://api.clearvo.io/v1/send200 means stored, not accepted. A well-formed document is stored before it is processed, so a failed validation, a rejection or a hold comes back as 200 with a status such as REJECTED, WAITING_FOR_YOU or WAITING_FOR_PLATFORM (and a reason that says exactly why), the stored record id, and errors[] where something has to be fixed. Read status, reason and nextStep, never the HTTP code alone. ok is false when the document needs action, but it is not the outcome: branch on status. When enabled for your account, a temporary problem after the document is stored gives 200 with status: RECEIVED and a PROCESSING_DELAYED warning: do not resend, Clearvo finishes it. Otherwise a temporary failure is a 503 with Retry-After: retry the same request with the same x-idempotency-key. A dryRun answers the same 200 body and stores nothing. Only an unreadable request (400), authentication or plan (401/403), size (413), rate limit (429) and a changed re-send of a processed document (409) are errors. A 503 means nothing could be stored (INGEST_UNAVAILABLE): retry with the same body. See the e-invoice lifecycle.Node.js example
const response = await fetch('https://api.clearvo.io/v1/send', {
method: 'POST',
headers: {
'x-api-key': process.env.CLEARVO_API_KEY,
'x-idempotency-key': crypto.randomUUID(),
'Content-Type': 'application/json',
},
body: JSON.stringify({
documentType: 'invoice',
invoiceNumber: 'INV-2024-001',
issueDate: '2024-01-15',
currency: 'EUR',
country: 'IT',
customer: {
name: 'Cliente SpA',
taxId: '09876543210',
establishmentCountry: 'IT',
address: { street: 'Via Veneto 10', city: 'Roma', postalCode: '00187', country: 'IT' },
},
lines: [
{ description: 'Software licence Q1', quantity: 1, unitPrice: 1000.00, taxRate: 22 },
{ description: 'Support hours', quantity: 8, unitPrice: 125.00, taxRate: 22 },
],
}),
});
const invoice = await response.json();
console.log(invoice.referenceId); // "IT-20240115-INV-001"
Response fields
| Field | Type | Description |
|---|---|---|
| ok | boolean | Comes from the reason alone: false for REJECTED, NEEDS_INFO, SETUP_NEEDED and HELD_PLATFORM_FAULT, true otherwise, and the same on every replay. Not the outcome: branch on status. |
| country | string | ISO country code the invoice was routed to. |
| referenceId | string | Clearvo-assigned identifier for this invoice submission. Use with GET /status. |
| status | string | Initial status — PENDING for async countries; COMPLETED immediately for synchronous flows (DE B2B). |
| stage | string? | Where in the journey: queued, awaiting_authority (PENDING), or generated, reported, cleared, delivered, received (COMPLETED). Null otherwise. |
| reason | string | The specific cause behind the status. |
| issues | array | Warnings and errors attached to the document. |
| customerResponse | object? | The customer's decision, when there is one. |
| terminal | boolean | true when the status will not change again. Stop polling when true. |
| submittedAt | string (ISO 8601) | UTC timestamp of submission. |
| nextPollAfter | string (ISO 8601) | Earliest time to poll for an update. Respect this to avoid rate limiting. |
GET /status
Retrieve the current clearance status and full event history for a submitted invoice. It reads the stored status and never calls the authority. It works for any document Clearvo has accepted, whatever its status, including one that is waiting for you to fix something. The statuses, who acts on each and what to do are listed in the e-invoice lifecycle.
GET https://api.clearvo.io/v1/status?country=IT&id=<referenceId>Query parameters
| Parameter | Type | Description |
|---|---|---|
| country | string | ISO 3166-1 alpha-2 country code. Required |
| id | string | The referenceId returned by POST /send. Required |
Polling loop (JavaScript)
async function waitForClearance(referenceId, country) {
const MAX_POLLS = 48; // 4 hours at 5-min cadence
let polls = 0;
while (polls++ < MAX_POLLS) {
const res = await fetch(
`https://api.clearvo.io/v1/status?country=${country}&id=${referenceId}`,
{ headers: { 'x-api-key': process.env.CLEARVO_API_KEY } }
);
const data = await res.json();
if (data.terminal) {
return data; // ACCEPTED | REJECTED | DUPLICATE
}
// Honour nextPollAfter — don't hammer the API
const wait = new Date(data.nextPollAfter) - Date.now();
if (wait > 0) await new Promise(r => setTimeout(r, wait));
}
throw new Error('Max polls reached — check Italy mcDeadline');
}
Status response fields
| Field | Type | Description |
|---|---|---|
| status | string | Current status. See status values below. |
| stage | string? | Where in the journey, for PENDING and COMPLETED. |
| reason | string | The specific cause behind the status. |
| issues | array | Warnings and errors attached to the document. |
| customerResponse | object? | The customer's decision, when there is one. |
| terminal | boolean | Stop polling when true. |
| events | array | Ordered array of status transitions. Each entry has at (ISO 8601), event (the status or step name) and detail (free-text description). |
| clearedAt | string? | Timestamp of clearance. Present when status is COMPLETED with stage cleared or delivered. |
| rejectedAt | string? | Timestamp of rejection. Present only when REJECTED. |
| error | object? | Authority rejection detail. Present only when REJECTED. Shape: { code, message, retryable, upstreamCode, upstreamMessage } — code is a Clearvo error code (or CLEARANCE_REJECTED), message is the suggested action or a plain-language summary, retryable is always false for an authority rejection, and upstreamCode / upstreamMessage carry the authority's own code and text (or null). |
| errorCode | string? | Structured error code, present whenever the invoice failed with a mapped reason (pre-submission validation failures as well as authority rejections). |
| suggestedAction | string? | What to do next, in plain language. Present with errorCode. |
| isMerchantResolvable | boolean? | true when you can fix the cause yourself (for example, missing data); false when it needs Clearvo or the authority. Present with errorCode. |
| fixUrl | string? | Link to the dashboard page where the problem can be fixed, when there is one. |
| mcDeadline | string? | Italy only. The SDI 10-day delivery deadline in ISO 8601. Present only when reason is UNDELIVERED. |
| nextPollAfter | string? | Earliest recommended next poll time. Absent when terminal. |
Status values
Every document has one of ten statuses, the same for every country. stage and reason refine it, and issues[] and customerResponse add warnings and the customer's decision. See Invoice statuses for each reason and worked examples.
| Status | Terminal? | Description |
|---|---|---|
RECEIVED | No | Stored, processing not finished. |
PENDING | No | In progress. stage is queued or awaiting_authority. Continue polling. |
WAITING_FOR_YOU | No | Only you can move it. For a Peppol customer that cannot be found (reason: UNROUTABLE), the UBL XML is stored: retry delivery via POST /v1/invoices/{id}/deliver once the customer registers, or supply an explicit customer.electronicAddress. |
WAITING_FOR_PLATFORM | No | Only Clearvo can move it. For Italy (SDI) when it cannot reach the recipient's inbox (reason: UNDELIVERED), SDI retries for 10 days. After that deadline the invoice may still be legally valid — see the Italy guide. |
ACCUMULATED | No | Included in a periodic report not yet filed. |
COMPLETED | Yes | Finished successfully. stage is generated, reported, cleared (cleared by the tax authority: IT/SDI, PL/KSeF, AR/AFIP, RO/ANAF), delivered (Peppol: delivered to the customer's Access Point via AS4) or received. clearedAt is set where the authority clears. |
REJECTED | Yes | The authority or a validation rule refused the invoice. Check the error block for reason codes. |
CANCELLED | Yes | Reported, then withdrawn. |
SKIPPED | Yes | You discarded it, so it is not submitted. You can reverse this. |
NOT_APPLICABLE | Yes | Nothing is required by law (including when a rule finds nothing is owed), the country is not supported, or the invoice number is already stored (reason: DUPLICATE). No action needed if intentional. |
GET /participants/lookup
Check whether a customer is registered on the Peppol network and retrieve their AS4 endpoint. Results are served from cache when available. Pass forceRefresh=true to re-query the SML live.
GET https://api.clearvo.io/v1/participants/lookup?country=BE&vatNumber=BE0420429272Query parameters
| Parameter | Type | Description |
|---|---|---|
| country | string | ISO country code. Required when using vatNumber. Optional with electronicAddress |
| vatNumber | string | Customer VAT number. Clearvo derives the Peppol participant ID automatically. Optional if electronicAddress provided |
| electronicAddress | string | Explicit Peppol identifier (e.g. 0420429272). Requires electronicAddressSchemeId or country. Optional if vatNumber provided |
| electronicAddressSchemeId | string | EAS code (e.g. 0208). Used with explicit electronicAddress. Optional |
| documentType | string | invoice or credit_note. Determines which document type ID to look up in SMP. Default: invoice. Optional |
| forceRefresh | boolean | Set to true to bypass cache and re-query the SML live. Optional |
Response
| Field | Type | Description |
|---|---|---|
| registered | boolean | true if the customer is registered on Peppol and has a reachable endpoint. |
| participantId | string? | Canonical Peppol participant ID, e.g. iso6523-actorid-upis::0208:0420429272. |
| endpointUrl | string? | The customer's AS4 endpoint URL. Present when registered: true. |
| derivedFrom | string? | "vatNumber" or "electronicAddress" — how the participant ID was resolved. |
| cached | boolean? | true if the result was served from cache; false if a live SML lookup was performed. |
| checkedAt | string? | ISO 8601 timestamp of the last SML lookup. |
POST /invoices/{id}/deliver
Retry Peppol AS4 delivery for an invoice that is WAITING_FOR_YOU with reason: UNROUTABLE. Clearvo re-queries the SML (bypassing cache), and re-attempts delivery. On success the invoice moves to COMPLETED (stage: delivered). On continued failure it stays WAITING_FOR_YOU with reason: UNROUTABLE and can be retried again.
POST https://api.clearvo.io/v1/invoices/{id}/deliverPath parameter
| Parameter | Type | Description |
|---|---|---|
| id | string | Invoice id or referenceId returned by POST /send. Required |
Request body (optional)
| Field | Type | Description |
|---|---|---|
| electronicAddress.value | string | Override the customer's Peppol endpoint identifier. Use this once the customer has registered, or to correct a wrong value. Optional |
| electronicAddress.schemeId | string | EAS code for the override electronicAddress.value. Optional |
Response
| Field | Type | Description |
|---|---|---|
| ok | boolean | true on delivery success, false if still unroutable. |
| status | string | COMPLETED on success; WAITING_FOR_YOU on failure. |
| reason | string | DELIVERED on success; UNROUTABLE on failure. |
| nrr | boolean? | Present on success. true if the receiver's AP returned a Non-Repudiation Receipt. |
| deliveryError | object? | Present on failure. { code, message, retryable }. |
Error responses
| HTTP | Meaning |
|---|---|
| 404 | No record found for the given id. |
| 409 | Invoice is not waiting on an unroutable customer (reason is not UNROUTABLE; for example already COMPLETED). |
| 422 | No stored XML or customer endpoint cannot be determined; provide electronicAddress in the body. |
Supported Countries
Pass the two-letter ISO code in the country field. Clearvo generates the correct country format, then submits it, reports it or delivers it over the Peppol network, depending on the model below. Mandate dates are the legal dates for the country, not Clearvo availability, and can change. Check the authority before relying on a date for a compliance decision. Call GET /v1/requirements?country=XX for the exact fields a country needs.
| Country | Authority / network | Format | Model | Mandate |
|---|---|---|---|---|
| Clearance — the authority validates the invoice before it is issued | ||||
| IT | SDI (Agenzia delle Entrate) | FatturaPA 1.2 | Clearance | Mandatory since Jan 2019 |
| PL | KSeF (Ministry of Finance) | FA(3) XML | Clearance | Large taxpayers from 1 Feb 2026; all other VAT payers from 1 Apr 2026; penalties from 1 Jan 2027 |
| RO | ANAF e-Factura | CIUS-RO (UBL) | Clearance | B2B mandatory since 1 Jan 2024 |
| AR | AFIP | Factura Electrónica (CAE) | Clearance | Mandatory |
| SA | ZATCA (Fatoora) | UBL 2.1 | Clearance (B2B/B2G); reporting within 24h (B2C) | Mandatory, phased by taxpayer wave |
| EG | ETA | ETA e-invoice | Clearance | Mandatory |
| JO | ISTD JoFotara | UBL 2.1 | Clearance | Mandatory |
| Real-time and periodic reporting — the invoice is issued directly, data is reported to the authority | ||||
| HU | NAV Online Számla | Online Számla v3.0 XML | Real-time reporting | Since Jul 2018; all invoices (including zero VAT) since Jan 2021 |
| GR | AADE myDATA | myDATA XML | Real-time reporting | Mandatory since Nov 2021 |
| ES (SII) | AEAT — Suministro Inmediato de Información | SII XML | Real-time reporting (VAT ledger) | Mandatory for large taxpayers, VAT groups and REDEME since Jul 2017; voluntary for others |
| ES (VeriFactu) | AEAT | VeriFactu XML (hash-chained records) | Certified billing records | Postponed (announced Oct 2026) to October 2028, aligned with Spain's B2B e-invoicing mandate (businesses over €8m turnover from 6 Oct 2027, everyone else from 6 Oct 2028). Confirm exact dates against the BOE |
| PT | AT (Autoridade Tributária) | SAF-T (PT) + ATCUD + QR code | Certified invoicing + invoice-data communication | Certified software required today |
| FR | DGFiP — via an accredited platform (PA) | Factur-X (EN16931) | Network delivery + e-reporting | Receiving: all businesses from 1 Sep 2026. Issuing: large and mid-size from 1 Sep 2026; small and micro from 1 Sep 2027 |
| Structured invoice generation and download (optionally delivered over Peppol) | ||||
| DE | No central authority | XRechnung 3.0 (UBL), ZUGFeRD (CII, EN16931 profile) or Peppol BIS 3.0 | Generate, or deliver over Peppol | Receiving: all businesses since 1 Jan 2025. Issuing: turnover above €800k from 1 Jan 2027; all others from 1 Jan 2028 |
| Peppol BIS Billing 3.0 — Europe | ||||
| BE | OpenPeppol | Peppol BIS 3.0 UBL | Network delivery | B2B mandatory from 1 Jan 2026 (penalties from 1 Apr 2026) |
| NL | OpenPeppol / Digipoort | Peppol BIS 3.0 UBL | Network delivery | B2G mandatory |
| AT | OpenPeppol / eRechnung.gv.at | Peppol BIS 3.0 UBL | Network delivery | B2G mandatory |
| HR | OpenPeppol / FINA | Peppol BIS 3.0 UBL | Network delivery | Mandatory from 2026 |
| SK | OpenPeppol / Financial Administration | Peppol BIS 3.0 UBL (+ Tax Data Document) | Network delivery + tax data reporting | B2B mandatory from 1 Jan 2027 |
| IE | OpenPeppol / OGP | Peppol BIS 3.0 UBL | Network delivery | B2G mandatory |
| NO | OpenPeppol / DFØ | Peppol BIS 3.0 UBL | Network delivery | B2G mandatory |
| SE | OpenPeppol / Skatteverket | Peppol BIS 3.0 UBL | Network delivery | B2G mandatory |
| DK | OpenPeppol / NemHandel | Peppol BIS 3.0 UBL | Network delivery | B2G mandatory |
| FI | OpenPeppol / Vero | Peppol BIS 3.0 UBL | Network delivery | B2G mandatory |
| LT | OpenPeppol / VMI | Peppol BIS 3.0 UBL | Network delivery | B2G mandatory |
| LV | OpenPeppol / VID | Peppol BIS 3.0 UBL | Network delivery | B2G mandatory |
| EE | OpenPeppol / MTA | Peppol BIS 3.0 UBL | Network delivery | B2G mandatory |
| LU | OpenPeppol | Peppol BIS 3.0 UBL | Network delivery | B2G mandatory |
| SI | OpenPeppol / FURS | Peppol BIS 3.0 UBL | Network delivery | B2G mandatory |
| IS | OpenPeppol / RSK | Peppol BIS 3.0 UBL | Network delivery | B2G mandatory |
| CH | OpenPeppol / SIX | Peppol BIS 3.0 UBL | Network delivery | No mandate; B2B via Peppol network |
| Peppol PINT — Asia-Pacific & Gulf | ||||
| AU | ATO / OpenPeppol | Peppol PINT A-NZ | Network delivery | B2G mandatory |
| NZ | NZ Peppol Authority | Peppol PINT A-NZ | Network delivery | B2G mandatory |
| JP | Digital Agency / OpenPeppol | Peppol JP PINT | Network delivery | Voluntary; B2G adoption |
| SG | IMDA / IRAS (InvoiceNow) | Peppol SG PINT | Network delivery | GST InvoiceNow phased in from 2025 to 2031 by registrant type |
| AE | Ministry of Finance / FTA | Peppol UAE PINT | Network delivery | Pilot from 1 Jul 2026; large businesses from 1 Jan 2027 |
| Receive-only — Clearvo ingests, validates and stores invoices your suppliers issue | ||||
| MX | SAT | CFDI 4.0 | Receiving | Mandatory (issued by suppliers through their PAC) |
| BR | SEFAZ | NF-e / NFS-e | Receiving | Mandatory (issued by suppliers) |
Authority credentials. Clearvo handles authority sessions, signing and polling. For Poland (KSeF token), Hungary (NAV technical user), Romania (ANAF token), Greece (myDATA user and key), Argentina (AFIP certificate), Portugal (AT series) and Saudi Arabia (ZATCA onboarding), you connect your own credentials once per entity, in the dashboard or through the credentials endpoints. Spain, Germany, France and the Peppol countries need no authority credentials from you. See the country guides below.
country and the buyer's Peppol endpoint differ. Delivery uses Clearvo's certified Peppol Access Point (PIE001162). For Netherlands (KvK), Austria, Slovakia (IČO), Iceland, Switzerland, New Zealand and the UAE you must supply the buyer's endpointId; for the other countries it is derived from the tax number.Request body
Send a JSON object to POST /v1/send. This table is generated from the API contract (openapi.json) and lists every accepted field.
| Field | Type | Description |
|---|---|---|
| companyCode | string | Optional company code (a division of the entity; Enterprise plans only). Trimmed, max 50, matched without regard to case against the entity's active codes (GET /company-codes). Omitted: the entity's default company code, else none. A requested code that is unknown or archived is a stored REJECTED COMPANY_CODE_UNKNOWN rule outcome, and one outside its validFrom/validTo window on the invoice's tax point date (else issue date) is COMPANY_CODE_NOT_VALID_ON_DATE, both stored as a rejection in the InvoiceRejectedResponse envelope (HTTP 200); an entity default outside its window is simply not applied (companyCodeSource 'none' plus a warning); a plan without company codes is HTTP 403 company_codes_not_included. Company-code-scoped rules fire only for the resolved code. Stored on the invoice record. Optional |
| documentType | enum | Credit and debit notes need originalInvoiceRef (the original invoice's own invoiceNumber and issueDate). Over Peppol, credit notes and debit notes are supported in Belgium, the Netherlands, Austria, Croatia, Slovakia, Ireland, Norway, Sweden, Denmark, Finland, Lithuania, Latvia, Estonia, Luxembourg, Slovenia, Iceland, Switzerland, Germany (when the Peppol format is used), Australia and New Zealand. A credit note reverses a previously accepted invoice in full; partial credit notes over Peppol are not supported yet (only France and Spain support partial credit notes). A debit note is sent as an invoice marked as a debit note (UNTDID 1001 type code 383), because Peppol has no separate debit-note document. Singapore, Japan and the UAE do not yet support credit or debit notes over Peppol: the document is stored as REJECTED with CREDIT_NOTE_PEPPOL_UNSUPPORTED; send a corrected invoice instead or contact support. One of: invoice, credit_note, debit_note. Required |
| invoiceNumber | string | Seller-assigned invoice number, unique per seller. The invoice number (with documentType and country, and for a purchase the supplier tax ID and issue date) is what identifies the document: it builds the system identity key that deduplicates, so a changed re-send of the same number is refused 409 IDEMPOTENT_BODY_MISMATCH. A document missing one of those fields is stored under an identity Clearvo mints (your x-idempotency-key is used instead when you send one), and the response carries the warning NO_IDENTITY_NO_DEDUP. Required |
| issueDate | string | The invoice date as YYYY-MM-DD. Dates in any other format (19/06/2026, a date with a time, an epoch) are refused with INVALID_ISSUE_DATE_FORMAT unless a PARSE_DATE rule for this field brings them to YYYY-MM-DD first; the same applies to taxPointDate, dueDate and originalInvoiceRef.issueDate. Required |
| taxPointDate | string | VAT point / tax point date (EN16931 BT-7), when it differs from issueDate. The tax point drives all reporting-side date logic: Compliance Mandate effective-date matching and reporting-period membership both use taxPointDate first, falling back to issueDate. Omit when the two are the same. Optional |
| dueDate | string | Optional |
| currency | string | Required |
| taxReportingCurrency | string | ISO 4217 currency this invoice must be VAT-reported in, when it differs from currency (EN16931 BT-6 — e.g. a EUR invoice for a transaction whose jurisdiction reports in RON). Omit to let it resolve automatically from the transaction's own tax jurisdiction; only set it to override that. When the resolved reporting currency differs from currency, supply exchangeRate or taxReporting so the amounts can be shown in it — Clearvo never fetches or computes an exchange rate itself. Without one the invoice is still accepted and a MISSING_EXCHANGE_RATE warning is returned (only when some line carries tax); for a country whose tax authority needs the conversion (Hungary) it is held for more information with MISSING_EXCHANGE_RATE_REQUIRED. For such a country the reporting currency is that country's own, whatever taxReportingCurrency or the first line's jurisdiction says. Optional |
| exchangeRate | number | The one exchange rate field for every country: how many units of taxReportingCurrency one unit of currency buys (for example the central bank rate for the issue date). Applied uniformly to every total (subtotal, tax-exclusive amount, tax total, grand total), so the converted amounts are calculated for you. Must be a positive number (INVALID_EXCHANGE_RATE otherwise); null counts as not sent. Mutually exclusive with taxReporting — rejected with EXCHANGE_RATE_AND_TAX_REPORTING_BOTH_SUPPLIED if both are sent. countrySpecific.hu.exchangeRate is a deprecated alias for this field. Optional |
| taxReporting | object | Authoritative tax-exclusive amount, tax total and total in taxReportingCurrency, taken as-is rather than back-derived from a single collapsed figure or exchange rate — your own rounding of net+tax often isn't identical to rounding the gross directly, and the tax amount specifically usually needs to reconcile exactly with your own books. Mutually exclusive with exchangeRate. Optional |
| country | string | Target clearance country — ISO 3166-1 alpha-2 (determines the authority and XML format). This is also the tax jurisdiction the line resolution reports against; for an outgoing invoice the supplier tax ID is taken from the entity's registration in this country. When omitted it is derived from the entity's registrations; send it when the entity is registered in more than one country and the document does not say which (otherwise stored REJECTED with JURISDICTION_AMBIGUOUS). Required |
| taxIncluded | boolean | When true, all line unitPrices are gross (VAT-inclusive) by default. Can be overridden per line. Optional |
| supplier | object | The seller of a PURCHASE invoice (transactionDirection: 'purchase', the vendor) or of a SELF-BILLED invoice (countrySpecific.peppol.selfBilling: true, the real third-party seller; required, supplierRef resolves a saved one, omitting both is rejected with MISSING_SELF_BILLING_SUPPLIER; its electronicAddress is read from this object). Never send supplier on a sale: the supplier of a sale is always the entity's own master data (name, address) and tax registrations, and a sale carrying supplier is refused with 422 UNKNOWN_FIELD_SUPPLIER_ON_SALE (nothing is processed). Select the entity with the x-entity-id header or an entity-scoped API key. If the entity's profile is missing a name, country or city the document is stored NEEDS_INFO with MISSING_SUPPLIER_DATA; for Spain SII / VeriFactu a missing or lapsed Spanish registration as of the document date holds it NEEDS_INFO with MISSING_SUPPLIER_REGISTRATION (fixUrl to the Registrations page): add or renew it, then resubmit with correctsInvoiceId set to the held invoice's id. Optional |
| customer | object | Counterparty details. On the default transactionDirection: 'sale' this is the customer, and required. On transactionDirection: 'purchase' customer is the entity's OWN identity, not the vendor (the vendor is supplier) — optional, and when omitted it's auto-derived from the entity's master data (the way supplier is on a sale), resolving the entity's registration for the document's own reporting country (not necessarily its home country). On a purchase customer must be this entity, for every country: a supplied customer.taxId (or, with no tax number, customer.name) that does not match the entity's registered tax numbers or name holds the document as RECEIVED_NEEDS_REVIEW with PURCHASE_CUSTOMER_NOT_ENTITY (it appears to belong to a different entity or may have been misrouted; nothing to correct, check the routing); omit customer to have the entity's own details applied. On a self-billed invoice a differing customer.taxId is still rejected with CUSTOMER_TAX_ID_MISMATCH. An incomplete entity profile (missing name/country/city) no longer rejects immediately when customer is omitted on a purchase or self-billed invoice — the request proceeds through mandate resolution, and is rejected only afterward (rejected with MISSING_CUSTOMER_NAME / MISSING_CUSTOMER_ADDRESS_CITY) if the resolved regime actually requires customer identity; a regime that doesn't (e.g. France's e-reporting) accepts it as submitted. On a transactionDirection: 'purchase' Spain SII received-book document, a missing or lapsed Spanish registration for this entity (as of the document date) holds the submission as NEEDS_INFO with errorCode MISSING_CUSTOMER_REGISTRATION (the purchase-direction counterpart of supplier's MISSING_SUPPLIER_REGISTRATION) rather than rejecting it — add or renew the ES registration, then resubmit with correctsInvoiceId set to the held invoice's id. A request that still carries the old buyer field name is stored as REJECTED with UNKNOWN_FIELD_BUYER_RENAMED in errors[], naming customer — there is no silent alias. A self-billed invoice (countrySpecific.peppol.selfBilling: true) shares this same purchase-direction shape even on the default transactionDirection: 'sale': customer is still the entity's OWN identity (the buyer being self-billed for), auto-derived and tax-ID-compared/derived exactly as described above for purchase, and its electronicAddress (BT-49) is backfilled from the entity's own confirmed Peppol Participant ID when omitted. Required |
| customerType | enum | Optional customer classification, business (B2B) vs. consumer (B2C), for the whole invoice. Additive: omit it entirely and nothing changes. When provided, it feeds a single WARNING-only cross-check (CUSTOMER_TYPE_TAX_ID_MISMATCH) against customer.taxId's presence/format — never blocks submission. Can be overridden per line via lines[].customerType. One of: B2B, B2C. Optional |
| lines | LineItem[] | Required |
| allowances | AllowanceCharge[] | Document-level allowances (discounts applied to the invoice total): BG-20. Optional |
| charges | AllowanceCharge[] | Document-level charges (surcharges applied to the invoice total): BG-21. Optional |
| shipping | Shipping | Optional |
| payment | Payment | Optional |
| clientTaxCode | string | RECOMMENDED. Your own ERP tax code (e.g. a SAP two-digit code), configured in advance via POST /tax/client-codes, applied for the WHOLE invoice — the header-level counterpart to lines[].clientTaxCode. Resolved onto every line that supplies neither its own taxRate/taxTreatment nor its own lines[].clientTaxCode; a line's own value always wins over this header one. Real ERPs typically assign one tax code per invoice/document rather than per line, so this field lets an integrator send that single code once instead of repeating it on every line. An unrecognised code for this entity does not reject the invoice — it is accepted and held (status: WAITING_FOR_YOU, reason: SETUP_NEEDED, errorCode: TAX_CODE_UNMAPPED) with a machine-readable reason, same as an unrecognised lines[].clientTaxCode. Optional |
| dryRun | boolean | Preview the resolved per-line tax decision without creating a record, generating XML, or enqueueing anything to an authority. The response echoes dryRun: true plus lines[] (see InvoiceResponse) showing exactly how each line would resolve — including a would-be SETUP_NEEDED outcome (errorCode TAX_CODE_UNMAPPED) — so an integrator can validate a client tax code / taxTreatment setup before really submitting. Never persists an einvoicing_records row. For a German invoice that resolves to the PEPPOL format, dryRun: true also runs the real enrichment, the German Peppol content rules (MISSING_DE_PEPPOL_*), the generated-document validation and the customer reachability check, and returns the same errors[] / warnings[] (or PEPPOL_CUSTOMER_UNREACHABLE) a real send would, plus the delivery block — still without storing a record or queueing anything. Optional |
| sandboxSimulateOutcome | enum | Sandbox only (csk_test_* keys) — ignored for a live key. Forces the submission through the same rejection-handling path a genuine authority rejection would take, using a country-representative rejection code so the shape (fieldPath, message, suggestedAction) matches what a real merchant would see: IT '00404' (customer.taxId not registered with SDI), PL 'NIP_MISMATCH' (seller NIP mismatch), RO 'INVALID_COUNTY_CODE' (missing ISO 3166-2:RO county code), HU 'INVALID_TAX_NUMBER' (customer tax number rejected by NAV), or 'SANDBOX_SIMULATED_REJECTION' for every other country (ES/PT/GR/AR/Peppol and any generate-only country, none of which reject synchronously in real life either). Lets an integration test its own rejection-handling code path without waiting for or provoking a real authority rejection. One of: REJECTED. Optional |
| prepaidAmount | number | Amount already paid (deposit, down-payment, advance invoice, BT-113). Without statedPayableAmount, payableAmount = total − prepaidAmount. Defaults to 0. Optional |
| statedPayableAmount | number | Optional: the amount due for payment your own system (ERP/POS) computed. It is authoritative: it is stored as the invoice's payable amount (BT-115) exactly as stated, and the difference from the total of the lines less prepaidAmount is stored as the rounding amount (BT-114), whatever its size. A difference of more than one minor unit of currency raises the warning ROUNDING_RESIDUAL_OVER_TOLERANCE and no longer rejects or blocks the invoice. A format that cannot carry the stated figure consistently (EN 16931 BR-CO-16) holds the invoice at generation with PAYABLE_AMOUNT_BR_CO_16 instead of changing it. Omit the field and the payable amount is the total less prepaidAmount. The v1 invoice view always carries totals.payableAmount; credit and debit notes use positive magnitudes. Optional |
| originalInvoiceRef | object | Required for documentType credit_note/debit_note: the invoice being corrected, named by its own number and issue date, nested in this object (the credit or debit note keeps its own new top-level invoiceNumber and issueDate). Clearvo matches the original by that number and date, so there is nothing of Clearvo's to store or send back. Without invoiceNumber and issueDate the document is held as NEEDS_INFO (MISSING_ORIGINAL_INVOICE_NUMBER / MISSING_ORIGINAL_ISSUE_DATE). If the stored original is not yet submittable, the credit note is held as HELD_AWAITING_ORIGINAL and sent automatically once the original is accepted, delivered or accumulated. If the original is not stored in Clearvo (for example it was issued before you started sending), a credit note is not refused: it is processed on its own, with its own lines and tax, and the response carries the warning CREDIT_NOTE_ORIGINAL_NOT_FOUND. If an invoice with that number exists but with a different issue date, it is treated as a different invoice and the response carries the warning CREDIT_NOTE_ORIGINAL_DATE_MISMATCH. In a bulk upload the columns are original_invoice_number and original_invoice_date. Optional |
| correctsInvoiceId | string | Only for resubmitting a rejected invoice: Clearvo's own id (the id returned by the prior /v1/send call) of the invoice this submission re-attempts. Must belong to the same entity and country. Not used for credit or debit notes: name their original with originalInvoiceRef. Optional |
| customerReference | string | Internal back-office reference (e.g. SAP BELNR). Stored but never sent to the authority. Optional |
| countrySpecific | object | Optional country-level extensions. Fields vary by country. peppol.selfBilling (boolean, default false) marks this as a self-billing document (customer issues on the seller's behalf), switching to a self-billing CustomizationID/ProfileID and UNTDID 1001 type codes (389 for invoices, 261 for credit notes) instead of the regular billing ones. AU and NZ use their own PINT-AUNZ self-billing profile; every Peppol country except SG and JP uses the generic EU BIS Self-Billing 3.0 profile. Silently ignored for SG and JP, whose self-billing document-type registration is not yet supported. Company-law disclosure facts (DE Handelsregister details and managing directors, FR Code de commerce Art. R123-237 capital/RCS city, IT Codice Civile Art. 2250 Registro Imprese/REA/capital/sole-shareholder notice, PT Código das Sociedades Comerciais Art. 171 registry office/capital, ES Código de Comercio Art. 16/19-21 Registro Mercantil tomo/folio/hoja/capital/liquidation notice) are entity-level facts, normally set once — legalForm via PATCH /entities/{id}'s entityFacts (see GET /entities/fact-definitions), the country-specific ones on the entity's registration extraFields — and rendered automatically (BT-30 legalRegistrationId, BT-33 additionalLegalInfo) on every invoice the entity issues, keyed on the entity's own established country rather than which country's clearance rules a given invoice itself resolves to. A value sent for the same field in the matching countrySpecific.<cc> block overrides the stored one for that invoice only (this includes de.legalForm; for IT, ES, PT and FR the legal form comes from entityFacts only). es.duaNumber (Spain SII block 3): NumeroDUA (Documento Único Administrativo) — required, and only meaningful, when a transactionDirection: 'purchase' line's tipoFactura resolves to F5 (import). Missing on an import produces NEEDS_INFO naming countrySpecific.es.duaNumber. Spain VeriFactu and SII (es): es.tipoFactura (explicit F1/F2/R1-R5 override; under VeriFactu an invoice with no buyer identification, an original document and a total up to EUR 400 is issued as F2 automatically, a credit note against an F2 as R5), es.claveRegimen (optional override, derived per line by default; must be valid for the line's own tax), es.customerNif, es.verifactuMode, es.calificacionOperacion (S1/S2/N1/N2), es.tipoRectificativa ('S'/'I'), es.facturasRectificadas, es.importeRectificacion, es.issuedByThirdParty, and the VeriFactu buyer and simplified-invoice fields: es.customerIdType ('passport', 'residence_document', 'residence_certificate', 'other' or 'not_registered' - what kind of document customer.taxId is when it is not a Spanish NIF or EU VAT number; send the buyer's country in customer.establishmentCountry; an unrecognised identifier without it holds the invoice as NEEDS_INFO with errorCode MANDATE_INCOMPLETE_DATA, and missingFields names customerIdType), es.noRecipientIdentification (boolean - your declaration that the invoice is lawfully issued without identifying the recipient, RD 1619/2012 art. 6.1.d; simplified invoices only, never inferred, AEAT 1185), and es.numRegistroAcuerdoFacturacion (billing agreement number, at most 15 characters). A simplified invoice above EUR 3,000 needs one of the last two or it is held as NEEDS_INFO (AEAT 1150). customer.name is optional on an F2/R5 invoice. Canary Islands: Clearvo registers your Canary Islands invoices with the AEAT VeriFactu system under the same Spanish tax number, reporting IGIC as Impuesto 03 in the same record chain as VAT. Set the es_tax_territory field (mainland, canary_islands or both) on your Spanish registration (PATCH /v1/tax/registrations/{id} extraFields; see GET /v1/tax/registrations/field-definitions) - an IGIC line without it returns VERIFACTU_TAX_TERRITORY_REQUIRED. Clearvo does not file your IGIC returns or the Canary SII with the Agencia Tributaria Canaria, and does not support IPSI (VERIFACTU_IPSI_UNSUPPORTED); sales between the Canary Islands and the mainland return VERIFACTU_CROSS_TERRITORY_UNSUPPORTED, and so does a credit note whose tax (IVA or IGIC) differs from the invoice it rectifies. An exempt line reports the exemption cause stated on its client tax code (E1 to E6; E1 to E8 for IGIC), defaulting to E1 on a mainland exempt line when none is stated; an IGIC exempt line with no stated cause is held. A credit note is sent with positive amounts and reported to AEAT with negative ones (rectificativa por diferencias). VeriFactu applies from 2027-01-01 for corporate-tax payers and 2027-07-01 for everyone else; Clearvo registers every Spanish invoice dated on or after 2027-01-01, and sandbox invoices must carry such a date (the sandbox never contacts the AEAT). Codes: VERIFACTU_CUSTOMER_ID_UNRESOLVED, VERIFACTU_CUSTOMER_NAME_MISSING, VERIFACTU_TAX_TERRITORY_REQUIRED, VERIFACTU_CROSS_TERRITORY_UNSUPPORTED, VERIFACTU_IPSI_UNSUPPORTED, VERIFACTU_DESGLOSE_UNMAPPED_DECISION, VERIFACTU_EXEMPTION_CODE_INVALID, VERIFACTU_CLAVE_REGIMEN_INVALID, VERIFACTU_DESGLOSE_TOO_MANY_LINES, VERIFACTU_NUM_SERIE_INVALID, VERIFACTU_TIPO_FACTURA_MISMATCH (rejected: countrySpecific.es.tipoFactura must be R1-R5 on a credit note and F1-F3 on an invoice), VERIFACTU_CURRENCY_UNSUPPORTED (rejected: a Spanish VeriFactu invoice must be in EUR; AEAT records amounts in euros with no currency field), rejected with UNKNOWN_ES_CUSTOMER_ID_TYPE, INVALID_ES_NO_RECIPIENT_IDENTIFICATION, INVALID_ES_NUM_REGISTRO_ACUERDO_FACTURACION, and the mandate validation rules ES_VERIFACTU_S1_CUOTA, ES_VERIFACTU_S2_NOT_SIMPLIFIED, ES_VERIFACTU_CLAVE_01_NO_E2_E3, ES_VERIFACTU_ART61D_ONLY_SIMPLIFIED, ES_VERIFACTU_IDOTRO_CODIGO_PAIS, ES_VERIFACTU_IVA_RATE_SET and the warning ES_VERIFACTU_IGIC_RATE_REFERENCE (an IGIC rate outside the usual set; the invoice is still sent as provided). de.invoiceFormat ('ZUGFERD', 'XRECHNUNG' or 'PEPPOL', highest-precedence override — see the top-level documentFormat/formatResolvedFrom response fields and PATCH /customers/{id}'s own countrySpecific.de.invoiceFormat for the per-customer default) and de.leitwegId (BT-10 — XRECHNUNG only, falls back to the request's own top-level buyerReference, then to the LEITWEG_ID reference stored on the customer) let a single POST /send choose Germany's invoice format explicitly. 'PEPPOL' sends the invoice to the customer over the Peppol network as a Peppol BIS Billing 3.0 invoice (documentFormat UBL_PEPPOL_BIS): it needs the entity's confirmed Peppol Participant ID (rejected with MISSING_SELLER_PEPPOL_ID otherwise) and an explicit Peppol ID for the customer (customer.electronicAddress with schemeId + value, or the stored customer's human-confirmed PEPPOL_PARTICIPANT_ID reference) — a German customer's Peppol ID is never derived from a VAT number. For a German XRECHNUNG or PEPPOL document the customer's electronic address (BT-49) is the first available of: the explicit customer.electronicAddress (value + schemeId), the stored confirmed Peppol participant ID, the Leitweg-ID (scheme 0204; it must pass the Leitweg-ID check-digit validation, so a free-text buyerReference or purchase-order number is ignored), the customer's contact email (scheme EM), the customer's German VAT ID (scheme 9930, DE plus 9 digits). The supplier's electronic address (BT-34) is the first of: the entity's confirmed Peppol participant ID, its contact email (EM), its German VAT ID (9930). When none exists the send is blocked before any XML is generated with ERROR MISSING_CUSTOMER_ELECTRONIC_ADDRESS or MISSING_SUPPLIER_ELECTRONIC_ADDRESS. A customer that cannot be reached is stored as NEEDS_INFO with PEPPOL_CUSTOMER_UNREACHABLE (see PeppolCustomerUnreachableResponse), never a silent fallback to another format. Credit and debit notes cannot be sent over Peppol for Germany yet (rejected with CREDIT_NOTE_PEPPOL_UNSUPPORTED), and neither can a self-billed document (peppol.selfBilling): requesting PEPPOL on one is a 400 DE_SELF_BILLED_PEPPOL_NOT_SUPPORTED, and a stored customer/entity default of PEPPOL on a self-billed document is rejected with DE_SELF_BILLED_FORMAT_CHOICE_REQUIRED (pick ZUGFERD or XRECHNUNG). Use dryRun: true to check all of this without storing anything. ar.condicionIVAReceptorId (ARCA's real FEParamGetCondicionIvaReceptor code, RG (ARCA) 5616/2024 — see the Customer schema's own countrySpecific.ar.condicionIVAReceptorId for the full code list; default 5, Consumidor Final) and ar.cbteTipo (override for the computed comprobante type, normally derived from condicionIVAReceptorId) — a foreign-customer condicionIVAReceptorId (8 Proveedor del Exterior / 9 Cliente del Exterior) with no explicit ar.cbteTipo override is rejected with AR_FOREIGN_CUSTOMER_UNSUPPORTED naming countrySpecific.ar.condicionIVAReceptorId (Factura E, comprobante 19, isn't generated automatically yet). it.esigibilitaIva ('I' default / 'D' / 'S' — DatiRiepilogo/EsigibilitaIVA), it.withholding (boolean) + it.withholdingDetails ({ type: 'RT01'..'RT06', rate, amount, paymentReason }, required once withholding is true or a rejection with IT_WITHHOLDING_DETAILS_MISSING; a supplied-but-malformed type/rate/amount/paymentReason is rejected with IT_WITHHOLDING_DETAILS_INVALID naming the specific offending sub-field), it.stampDuty (boolean, emits DatiBollo), it.cigCode/it.cupCode (DatiOrdineAcquisto CIG/CUP, require the request's own orderReference or a rejection with IT_CIG_CUP_MISSING_ORDER_REFERENCE). hu.invoiceCategory ('NORMAL' — the only supported value today) and hu.cashAccountingIndicator (boolean, pénzforgalmi cash-basis VAT flag). pl.gtuCodes (invoice-level GTU fallback — prefer lines[].gtuCode), pl.cashAccountingIndicator (boolean, Adnotacje P_16 metoda kasowa), pl.exemptionLegalBasisType ('national_act' | 'eu_directive' | 'other', required whenever any line is exempt or a rejection with PL_EXEMPTION_LEGAL_BASIS_MISSING). pt.stampDutyAmount (Imposto do Selo, caller-supplied, emits AT QR field M and folds into field N, and into the monthly SAF-T file's TaxPayable/GrossTotal too). ro.supplierTaxRegistered/ro.customerTaxRegistered (boolean; whether that party genuinely holds an active VAT registration (a CUI, "RO" prefix) rather than a bare fiscal identifier (CIF) — omit to default to whether the party's taxId carried the "RO" prefix; an unresolved supplier is rejected with RO_SUPPLIER_TAX_REGISTRATION_STATUS_UNKNOWN, an unresolved B2B (or untyped) customer a rejection with RO_CUSTOMER_TAX_REGISTRATION_STATUS_UNKNOWN, and a customerType: 'B2C' customer defaults to unregistered). ro.customerSector/ro.supplierSector ('SECTOR1'..'SECTOR6', required whenever the corresponding party's address.countyCode resolves to 'RO-B' Bucharest, or a rejection with RO_BUCHAREST_SECTOR_REQUIRED); a Romanian documentType: 'debit_note' with no originalInvoiceRef is rejected with RO_DEBIT_NOTE_MISSING_ORIGINAL_REF. A Jordanian documentType: 'credit_note' with no originalInvoiceRef.invoiceNumber is rejected with MISSING_JO_CREDIT_NOTE_INVOICE_NUMBER. Malaysia requires supplier.taxId (rejected with MY_SUPPLIER_TIN_REQUIRED if absent) and, for a B2B customer.taxId (rejected with MY_CUSTOMER_TIN_REQUIRED if absent and not self-billing/B2C) — see MyInvois's general-TIN placeholder codes for the B2C/self-billed exceptions. An Egyptian line whose taxCategory can't resolve to a known ETA VAT subtype is rejected with EG_TAX_SUBTYPE_UNRESOLVED naming lines[].taxCategory. Greece additionally holds when a line's optional lineType ('product', 'service', 'digital_service', 'transport' or 'other') is explicitly set and genuinely disagrees with the tax code's own resolved goods/service classification (rejected with GR_LINE_TYPE_SUPPLY_TYPE_MISMATCH naming lines[{i}].lineType — an OMITTED lineType never triggers this, only one you explicitly set and that conflicts), when a mixed-kind invoice has no single header-level invoiceType to describe it (rejected with GR_MIXED_LINE_TYPE), or when an exempt/zero-rated/reverse-charge line has no resolvable vatExemptionCategory (rejected with GR_EXEMPTION_CATEGORY_MISSING naming lines[{i}].taxCategory, with a /tax-codes fixUrl). Across every EN16931-shaped country generator (IT/PL/RO/GR/Peppol), an internally inconsistent (tax category, rate) pair on a line or VAT-breakdown entry — never reachable via the documented /v1/send request/response fields alone, since resolveInvoiceTaxCodes already holds this upstream — is the shared defense-in-depth rejection TAX_LINE_INCONSISTENT. Optional |
| notifyCustomer | boolean | Only meaningful for countries where no authority network delivers the invoice to the customer (DE always; ES only when this entity's Spanish invoices report under VeriFactu rather than SII — SII is a background report to AEAT decoupled from customer delivery, so this is silently ignored while SII is the active regime; IT only when the customer has no Italian SDI routing code; PL only when the customer has no Polish NIP — KSeF is pull-only and pull access requires the customer's own registered NIP). When the customer's email is set via customer.contact.email, Clearvo emails them a link to a hosted page to view/download the invoice. Omit to defer to the entity's own default (see PATCH /v1/entities/{id} notifyCustomerByDefault); true/false here overrides that default for this invoice only. Silently ignored (see customerNotification in the response) for countries Clearvo already delivers electronically (Peppol, IT B2B/B2G, PL when the customer has a NIP, RO, HU, GR, AR, FR — France delivers through an accredited third-party platform), or that are a pure background report to the tax authority with no customer-delivery role of their own (PT, and ES while its SII regime is active). Optional |
| rejectInsteadOfAutoCorrect | boolean | Per-request opt-out from silent auto-correction. Defaults to false — an ADJUSTMENT rule match (see GET /v1/validations for the live catalogue of autoCorrectable checks) is silently applied and reported in the response's adjustments[]. Set to true and a would-be correction is never applied — it surfaces instead as a blocking entry in the rejection response's errors[], so an integrator who wants to see and fix raw values themselves (rather than have Clearvo silently normalize them) can require that. Optional |
| ossDeclared | boolean | Explicit declaration that this transaction is (true) or is not (false) reported through the seller's OSS (One Stop Shop) return — an input to Compliance Mandate resolution, not a tax treatment. Omit it and the platform derives OSS-ness itself: an active OSS registration (Union or non-Union scheme) whose window covers the transaction's tax point date, combined with a qualifying intra-EU B2C distance sale (a client tax code that resolves to a distance-sale scheme also counts as an explicit signal). Supply it and the explicit value always wins over derivation. A non-boolean value is rejected with INVALID_OSS_DECLARED. Optional |
| transactionDirection | enum | Spain SII block 3 (received book / LFR). 'sale' (default) — this entity's own outbound/issued document. 'purchase' — a vendor's document the entity is recording on its own received side — Spain SII (received book) and France e-reporting (a purchase from a vendor not established in France is declared by you as the receiving party, at invoice level, in its own Received batch) only; every other live country's purchase-direction submission currently resolves to no reporting mandate at all (mandate: NONE). supplier is still the VENDOR/counterparty on a purchase (required — the entity's own Spanish registration for customer/Titular purposes is applied automatically, same derivation as the sale-side supplier.taxId rule). One of: sale, purchase. Optional |
| shipFrom | object | Where the goods leave from (optional). Used to decide the reporting country when you send no country (a ship-from in one of your registered countries is used) and the movement for sales of goods (local, intra-community or export). Still required for a France e-reporting own-goods stock transfer (a client tax code with movement own_goods_movement): for an outbound transfer (sale) the French origin, for an inbound transfer (purchase) the origin member state, used to find your own VAT registration in the other member state; an own-goods transfer without it parks NEEDS_INFO naming shipFrom.country (fixable with the needs-info PATCH). Optional |
| shipTo | object | Where the goods arrive (optional). Still required for an outbound France e-reporting own-goods stock transfer (shipFrom in France) to name the destination member state. Optional |
| accountingDate | string | PURCHASE documents only (transactionDirection='purchase'), Spain SII. The accounting-entry date (FechaRegContable, art. 69 bis.1.b) RIVA) — anchors both the Compliance Mandate effective-date gate and the received-book (LFR) submission deadline. Optional even for a purchase (falls back to taxPointDate ?? issueDate when omitted) — but the vendor's own issueDate is legally the wrong date for this gate, so a caller that books on receipt should always supply it. Optional |
| deductibleTaxAmount | number | CuotaDeducible — PURCHASE documents only, Spain SII. The deductible portion of input VAT on this purchase, always taken as given and never derived from the lines' own charged amounts (prorrata and non-deductible purchases exist; the platform must not invent this figure). An explicit 0 is a valid, distinct declaration (an exempt/non-deductible purchase) — NOT the same as omitting the field, which instead produces NEEDS_INFO naming this field. Optional |
| deductionPeriod | object | Received book only, Spain SII. The VAT declaration period this deduction is actually taken in, when it differs from accountingDate's own month (AEAT FAQ 4.9 Example 2: one invoice, two valid deadlines depending on the period the deduction is claimed in). Optional — omitted, the liquidation period defaults to accountingDate's own month. Optional |
| attachments | object[] | Supporting files to deliver with the invoice, such as a timesheet or a purchase order. They are never embedded in the e-invoice XML or PDF and are never sent to a tax authority or over the Peppol network; Clearvo stores them securely, checks each file for known malware test signatures and validates it against its declared file type (not a full antivirus scan), and offers them as downloads to the customer on the hosted invoice page and to you in the dashboard and through GET /invoices/{id}/attachments. Send a file as base64 contentBase64 with fileName and mimeType, or send only an externalUrl for a link-only attachment (kept as a link, not downloadable from Clearvo). Accepted types: pdf, csv, xlsx, xls, ods, xml, png, jpg or jpeg, txt; the file name extension and mimeType must agree. Limits: 10 MB per file, 25 MB in total, 20 per invoice. A breach is a 422 naming the attachment and nothing is stored: TOO_MANY_ATTACHMENTS, ATTACHMENT_INVALID, ATTACHMENT_METADATA_MISSING, ATTACHMENT_CONTENT_INVALID, ATTACHMENT_TYPE_NOT_ALLOWED, ATTACHMENT_TYPE_MISMATCH (the mimeType does not match the file name extension, or the file content does not match the declared type), ATTACHMENT_TOO_LARGE, ATTACHMENTS_TOTAL_TOO_LARGE, ATTACHMENT_URL_INVALID or ATTACHMENT_MALWARE_DETECTED. A 503 ATTACHMENT_STORAGE_UNAVAILABLE is retryable: send the same request again. Optional |
Invoices in a different currency
Tax authorities report in the currency of their own country. When the invoice currency differs from the currency the tax is reported in (for example a USD invoice for Germany, reported in EUR), send the exchangeRate you used: how many units of the reporting currency one unit of the invoice currency buys, such as the central bank rate for the issue date. Clearvo converts every total for you and never looks up a rate itself. If you already hold the converted amounts, send taxReporting (taxExclusiveAmount, taxTotal, optional total) instead. Send one of the two, not both.
Without a rate the invoice is still accepted and the response carries the warning MISSING_EXCHANGE_RATE. The warning appears only when the invoice carries tax: an exempt or zero-rated invoice has no tax amount to convert. A country whose tax authority needs every amount in its own currency stops the invoice instead, with MISSING_EXCHANGE_RATE_REQUIRED and clearance status NEEDS_INFO; add the rate and resubmit. Hungary is the one such country today.
Party object
Used for customer, and for supplier on a purchase invoice or a self-billed invoice. Do not send supplier on a sale: the supplier of a sale is always your entity's own name, address and tax registrations, and a sale that carries it is refused with 422 UNKNOWN_FIELD_SUPPLIER_ON_SALE. Select the entity with the x-entity-id header or an entity-scoped API key.
| Field | Type | Description |
|---|---|---|
| name | string | Required |
| taxId | string | Tax/VAT identifier. On supplier (a purchase's vendor or a self-billed invoice's seller) it is the third party's own number. On customer it is strongly recommended for B2B (reverse-charge treatment, SII counterparty identification). On a purchase, customer must be this entity: a customer tax number (or, without one, a name) that does not match the entity's registered details holds the document as RECEIVED_NEEDS_REVIEW with PURCHASE_CUSTOMER_NOT_ENTITY. Optional |
| address | Address | Required |
| establishmentCountry | string | ISO 3166-1 alpha-2 country of the tax registration that issued taxId. Optional — derived from the taxId prefix when omitted. Spain VeriFactu: required together with a passport, residence or other identifier (countrySpecific.es.customerIdType). Optional |
| electronicAddress | object | Peppol electronic address (BT-34 seller, BT-49 buyer): send value and schemeId together. Meaningful on customer only (required when auto-derivation is not supported for the customer's country) — ignored on supplier, which always uses the entity's own confirmed Peppol Participant ID (set once under the dashboard's Settings → Account → Peppol Network Identity section) rather than a per-request value, so a caller can never claim a different sender identity than the one the entity has confirmed. The document is stored as NEEDS_INFO with MISSING_SELLER_PEPPOL_ID if the entity has none confirmed. Optional |
| contact | object | Optional |
| customerRef | string | Customer only (ignored on supplier). Your own reference for a previously-saved customer record — when provided, Clearvo looks it up and fills in any of name/taxId/address you omit from this customer object. If the stored customer has a human-confirmed PEPPOL_PARTICIPANT_ID reference, it also fills in customer.electronicAddress, and a stored LEITWEG_ID reference fills in countrySpecific.de.leitwegId; each fills in only when the request supplies neither the explicit value (the electronicAddress pair; countrySpecific.de.leitwegId or a non-empty buyerReference), and an explicit value always wins. See GET /v1/customer-reference-types. For an Italy (IT) invoice, it also fills in countrySpecific.it.codiceDestinatario/pecDestinatario from the stored customer when present. Fields you do supply directly always take precedence over the stored ones. Manage customers via GET/POST /v1/customers and GET/PATCH/DELETE /v1/customers/{id}, or from the dashboard's Customers page — every successfully-issued invoice also auto-captures/refreshes a customer record from its customer details, whether or not customerRef was supplied. Optional |
| supplierRef | string | Supplier only (ignored on customer). Your own reference for a previously-saved supplier record — when provided, Clearvo looks it up and fills in any of name/taxId/address you omit from this supplier object. Fields you do supply directly always take precedence over the stored ones. Primarily used on a self-billed invoice (countrySpecific.peppol.selfBilling), where supplier identifies the real third-party seller rather than the entity itself. Manage suppliers via GET/POST /v1/suppliers and GET/PATCH/DELETE /v1/suppliers/{id}, or PUT /v1/suppliers/by-ref/{ref}. Optional |
| legalRegistrationId | string | Legal registration ID, e.g. a Companies House number or SIRET (BT-30). Optional |
| identifiers | object[] | Additional party identifiers — BT-29 (seller) / BT-46 (buyer) — distinct from legalRegistrationId and taxId. For Saudi Arabia (ZATCA) the scheme is one of CRN, MOM, MLS, 700, SAG, NAT, GCC, IQA, PAS, OTH. Optional |
{
"name": "Acme SRL",
"taxId": "01234567890",
"establishmentCountry": "IT",
"address": {
"street": "Via Roma 1",
"city": "Milano",
"postalCode": "20121",
"country": "IT"
}
}
Line items
Each entry in the lines array describes one invoiced item. Amounts are net (excluding tax). taxRate is an optional percentage on each line: a rate you send is used as it is; left out, it is the rate of the line's tax code, else it is worked out from the line's taxAmount (allowing for the cent rounding and preferring a rate the jurisdiction publishes), and a line that cannot be worked out, or whose rate the jurisdiction does not publish, is rejected asking for it. A taxAmount that cannot come from the tax code's rate is rejected too: send the rate the source charged, or correct the code. When taxAmount is omitted Clearvo derives it as round(lineTotal × taxRate / 100). The EN16931 tax category is resolved from your clientTaxCode or taxTreatment together with the rate — a line never carries a taxCode field (one is rejected with 400 UNSUPPORTED_FIELD), and the retired vatRate/vatAmount names are rejected with 422 UNKNOWN_FIELD_VAT_RENAMED.
| Field | Type | Description |
|---|---|---|
| description | string | Required |
| quantity | number | Required |
| unitPrice | number | Unit price excluding tax (net). When taxIncluded is true it is the gross price and the net is back-computed as unitPrice / (1 + taxRate / 100). Required |
| taxRate | number | Tax rate as a percentage (e.g. 22 for 22%, 0 for a reverse-charge line). Optional. A rate you send is used as it is (outside 0-100 is a 400 payload error naming lines[i].taxRate). Omitted, the rate is the rate of the line's tax code (clientTaxCode, or the entity code matching sourceSystemCode); with no code rate it is worked out from the line's taxAmount and amounts, allowing for the cent rounding of the stated tax and preferring a rate the jurisdiction publishes, and a line whose rate cannot be worked out, or is not one the jurisdiction publishes, is rejected (400 INVALID_VAT_RATE) asking for it. A tax amount that cannot come from the tax code's rate is rejected the same way: send the rate the source charged, or correct the code. A POSITIVE rate with no clientTaxCode/taxTreatment is reported as a domestic taxable supply at that rate. A 0% line with no clientTaxCode/taxTreatment is rejected (400 ZERO_RATE_NEEDS_TAX_TREATMENT) - a bare 0% rate alone does not state why it is zero, so supply taxTreatment (exempt / zero_rated / reverse_charge / out_of_scope, or the relevant cross-border movement via a client tax code); the platform never guesses. The retired vatRate name is rejected with 422 UNKNOWN_FIELD_VAT_RENAMED naming taxRate - there is no alias. A line taxCode is never accepted (400 UNSUPPORTED_FIELD): the EN16931 category is always a resolved OUTPUT - see taxResolution on the response. Optional |
| taxAmount | number | Tax amount for this line in the invoice currency. Optional — when omitted it is computed as round(lineTotal × taxRate / 100); supply it explicitly to control rounding precisely. The retired vatAmount name is stored as REJECTED with UNKNOWN_FIELD_VAT_RENAMED naming taxAmount. Optional |
| clientTaxCode | string | RECOMMENDED. Your own ERP tax code (e.g. a SAP two-digit code), configured in advance via POST /tax/client-codes — lets you send the code your own system already knows rather than reasoning about tax categories at all. Mutually exclusive with taxTreatment — set at most one of the two on a single line (a line with neither is resolved from its stated facts — taxRate plus any taxTreatment — mapped as given, never inferred from the customer/seller country pair). An unrecognised code for THIS entity is never rejected outright: the invoice is accepted and the record is held (status: WAITING_FOR_YOU, reason: SETUP_NEEDED, errorCode: TAX_CODE_UNMAPPED) with a machine-readable reason and a deep link to configure the code — see the InvoiceReason and UnmappedTaxCodeReason schemas — since an unconfigured code is a setup gap, not a malformed request. Optional |
| taxTreatment | object | The AUTHORITATIVE tax treatment for this line, used only when clientTaxCode is omitted. The stated treatment (exempt / out_of_scope / zero_rated / reverse_charge) is mapped as-is — the platform does not infer or override the movement from the customer/seller countries. Required whenever this line's taxRate is 0: a 0% line with no clientTaxCode/taxTreatment is rejected (400 ZERO_RATE_NEEDS_TAX_TREATMENT) rather than guessed. Mutually exclusive with clientTaxCode. An unrecognized value is a 400 naming this field. Optional |
| customerType | enum | Per-line override of the invoice-level customerType — business vs. consumer — consulted only when this line has no clientTaxCode. Defaults to the invoice-level customerType, then to whether customer.taxId is present. One of: B2B, B2C. Optional |
| supplyType | enum | Supply type consulted only when this line has no clientTaxCode — affects reverse-charge/place-of-supply treatment for cross-border B2B services. One of: goods, digital_service, general_service. Optional |
| discountPercent | number | Discount on this line as a percentage (0–100). Mutually exclusive with discountAmount — supplying both is rejected with LINE_DISCOUNT_CONFLICT. Optional |
| discountAmount | number | Discount on this line as a fixed amount in the invoice currency (>= 0). Mutually exclusive with discountPercent. Optional |
| unitOfMeasure | string | UN/ECE Recommendation 20 unit code: EA (each), HUR (hour), DAY, KGM (kilogram), MTR (metre), C62 (unit). Optional |
| lineNumber | integer | 1-based line position. Auto-assigned sequentially when omitted; must be a positive integer when supplied. Optional |
| sellerItemId | string | Your own product/item identifier for this line (EN16931 BT-155). Optional |
| gtuCode | enum | Poland (PL) FA(3)/KSeF only — this line's GTU goods/service classification. At most one code per line (the FA(3) schema's GTU element is single-valued). countrySpecific.pl.gtuCodes (invoice-level) is a fallback ONLY when it carries exactly one code and no line sets its own gtuCode; several invoice-level codes with no line assignment is rejected with PL_GTU_LINE_ASSIGNMENT_REQUIRED. One of: GTU_01, GTU_02, GTU_03, GTU_04, GTU_05, GTU_06, GTU_07, GTU_08, GTU_09, GTU_10, GTU_11, GTU_12, GTU_13. Optional |
| lineType | enum | Type of line item — used for tax treatment in some jurisdictions (e.g. digital services; Greece checks it against the resolved goods/service classification). One of: product, service, digital_service, transport, other. Optional |
| taxIncluded | boolean | Per-line override for tax-inclusive pricing. When true, unitPrice is gross and taxRate must be set; the net price is back-computed as unitPrice / (1 + taxRate / 100). Inherits the invoice-level taxIncluded when omitted. Optional |
| gtin | string | GTIN barcode (BT-157). Optional |
| itemClassificationCode | string | Product classification code, e.g. UNSPSC or CPV (BT-158). Poland also accepts PKWiU or CN. Requires itemClassificationScheme. Optional |
| itemClassificationScheme | string | Classification scheme, e.g. UNSPSC, CPV or STI (GTIN). Required with itemClassificationCode. Optional |
| orderLineReference | string | Purchase-order line reference (BT-132). Optional |
| period | object | Billing/service period for this line (BT-134/135). Optional |
| note | string | Line-level note (BT-127). Optional |
| metadata | object | Per-line metadata — stored internally, never sent to the authority. Optional |
| allowances | AllowanceCharge[] | Line-level allowances (further discounts applied to the line total). Optional |
| charges | AllowanceCharge[] | Line-level charges (surcharges applied to the line total). Optional |
| sourceSystem | string | Which connector/ERP the line's clientTaxCode was read from (e.g. sap). Diagnostic only: echoed as source_system in the unmappedTaxCode diagnostic (reason SETUP_NEEDED, errorCode TAX_CODE_UNMAPPED); never changes which code resolves. Optional |
| sourceSystemCode | object | A connector's own raw tax-code value (e.g. Xero's TaxType OUTPUT2), resolved through the connector's system vocabulary. Mutually exclusive with clientTaxCode and taxTreatment. Optional |
| clientTaxCodeSource | enum | Who chose this line's clientTaxCode. Omitted (read as caller) for any code you typed; 'default' is set only by the platform's own bulk CSV pipeline when a blank tax_code was replaced with a default. Diagnostic only. One of: caller, default. Optional |
Tax codes
Tax codes follow the EN16931 tax category framework. They are an output: Clearvo resolves each line's category from your clientTaxCode or taxTreatment plus its taxRate, writes the correct authority-specific code into the generated XML, and reports the decision back in each line's taxResolution.category. You never send a code directly — state the legal reason for a 0% rate through taxTreatment (or a mapped client tax code), not just the rate percentage.
| Code | Category | Rates (by country) |
|---|---|---|
| S | Standard rate | IT 22% · PL 23% · DE 19% · FR 20% · ES 21% |
| AA | Reduced rate | IT 10% · PL 8% · DE 7% |
| AB | Second reduced rate | IT 5% · PL 5% |
| AC | Super-reduced rate | IT 4% (essential goods) |
| AE | Reverse charge | Cross-border B2B services under Art. 196 VAT Directive. Customer accounts for VAT. |
| K | Intra-EU zero rate | Goods dispatched to VAT-registered customer in another EU member state (Art. 138). |
| G | Export / zero rate | Goods or services exported outside the EU. |
| E | Exempt | Legally exempt from VAT. Include exemptionReason in line item where required by country. |
| O | Out of scope | Outside the scope of VAT entirely (e.g. statutory transfers). |
| Z | Zero rated (domestic) | Domestic zero-rated supplies (distinct from intra-EU zero rate). |
AE (reverse charge) requires both parties to have a valid taxId. Clearvo validates this: if the customer taxId is missing on a cross-border reverse-charge invoice, the document is stored as a rejection (200, with the error in errors[]).Payment object
Optional payment details embedded in the invoice. Included in the generated XML where the authority format supports it (FatturaPA, UBL, XRechnung).
| Field | Type | Description |
|---|---|---|
| means[] | array | Payment instructions (BG-16), one entry per way of paying. Each entry takes method (bank_transfer | direct_debit | credit_card | cash | check | other), iban (IBAN of the payee account, no spaces), bic (BIC/SWIFT code; forbidden on a German XRechnung invoice), accountName (payee account name, BT-85, max 140 characters; filled from your stored bank account's holder name when you send no iban), reference (payment reference, BT-83) and, for SEPA direct debit, mandateReference (BT-89, max 35 characters), creditorId (BT-90) and debitedIban (BT-91). Optional |
| terms.text | string | Free-text payment terms, for example "Net 30" (BT-20). Optional |
| terms.earlyPayment | object | Early-payment discount: days (a whole number, 0 or more), percent (0 to 100) and an optional baseAmount (0 or more; defaults to the tax-exclusive amount). Anything else is rejected with INVALID_EARLY_PAYMENT_DAYS, INVALID_EARLY_PAYMENT_PERCENT or INVALID_EARLY_PAYMENT_BASE_AMOUNT. Optional |
| installments[] | array | Installment schedule: dueDate, amount and an optional description per installment. Optional |
The earlier flat shape is stored as REJECTED with UNKNOWN_FIELD_RENAMED, naming the replacement: payment.iban is now payment.means[].iban (likewise method, bic, reference, mandateReference, creditorId, debitedIban), a string payment.terms is now payment.terms.text, payment.skonto.days|percentOff|baseAmount is now payment.terms.earlyPayment.days|percent|baseAmount, and payment.dueDate is removed (use the top-level dueDate).
The optional top-level statedPayableAmount is the amount due your own system computed. It is stored exactly as stated; any difference from the lines total less prepaidAmount is recorded as the rounding amount (BT-114). A difference of more than one minor unit raises the warning ROUNDING_RESIDUAL_OVER_TOLERANCE and does not block the invoice. If the target format cannot carry the stated figure consistently (EN 16931 BR-CO-16) the invoice is held with PAYABLE_AMOUNT_BR_CO_16.
Country-specific fields
Some countries require additional fields that have no EN16931 equivalent. These are passed as a countryData object alongside the standard payload.
Italy
| Field | Type | Description |
|---|---|---|
| countryData.it.codiceFiscale | string | Customer's Italian fiscal code (for individuals). Optional |
| countryData.it.codiceDestinatario | string | SDI recipient code (7-char). Provide if known; Clearvo looks it up via SMP if omitted. Optional |
| countryData.it.pecDestinatario | string | Customer PEC email address (fallback if no codice). Optional |
Germany
How the format is chosen, the electronic-address rules and sending over Peppol are in Country fields and behaviour → Germany and Peppol countries.
| Field | Type | Description |
|---|---|---|
| countrySpecific.de.invoiceFormat | string | ZUGFERD, XRECHNUNG or PEPPOL. Overrides the per-customer and per-entity defaults (the platform default is ZUGFERD). PEPPOL sends the invoice over the Peppol network as a Peppol BIS Billing 3.0 invoice and needs a confirmed Peppol ID for your entity and an explicit Peppol ID for the customer. Optional |
| countrySpecific.de.leitwegId | string | Leitweg-ID (required for all public-sector B2G invoices; XRECHNUNG only, falls back to the request's own top-level buyerReference, then to the Leitweg-ID stored on the customer, if omitted). Corresponds to EN16931 BT-10 "Buyer reference" — the standard's own name, deliberately not renamed. Optional for B2B |
Poland
Poland requires a per-entity KSeF API token registered once via POST https://api.clearvo.io/v1/pl/credentials (or the setup page). See Country fields and behaviour → Poland for the full behaviour.
| Field | Type | Description |
|---|---|---|
| countrySpecific.pl.sellerNip | string | Override supplier NIP (10 digits). Auto-derived from supplier.taxId when prefixed with PL. Optional |
| countrySpecific.pl.customerNip | string | Override customer NIP (10 digits). Auto-derived from customer.taxId. Optional |
| countrySpecific.pl.splitPayment | boolean | Enable MPP (Mechanizm Podzielonej Płatności). Required for Annex 15 transactions > PLN 15,000. Optional |
| countrySpecific.pl.gtuCodes | string[] | GTU_01–GTU_13 classification codes for Annex 15 goods/services. E.g. ["GTU_12"]. Optional |
| countrySpecific.pl.rodzajFaktury | string | FA(3) document type: VAT (invoice) or KOR (correction). Auto-derived from documentType. Optional |
Hungary
NAV Online Számla needs every amount in HUF. For an invoice in another currency send the top-level exchangeRate (units of HUF per one unit of the invoice currency); without it the invoice is stopped with MISSING_EXCHANGE_RATE_REQUIRED. See Invoices in a different currency.
Clearance errors
These are not HTTP errors — the initial POST /send returns 200, but a subsequent status poll may reveal that the authority rejected the invoice. Check status === "REJECTED" and inspect the error block (code, message, retryable, upstreamCode, upstreamMessage) and the top-level errorCode / suggestedAction / isMerchantResolvable / fixUrl fields. For the generic HTTP status codes and the error object shape shared across every Clearvo product, see Errors & status codes.
Common authority rejection reasons by country:
Italy (SDI)
- 00001 — Invalid file structure (XML schema violation).
- 00002 — Duplicate invoice number from the same sender.
- 00102 — Supplier Partita IVA not found in Revenue Agency registry.
- 00201 — Customer Codice Destinatario or PEC not found or inactive.
Poland (KSeF)
- InvalidNip — NIP number checksum invalid.
- DuplicateInvoice — Invoice FA number already submitted in this session.
- SchemaValidationError — FA(3) schema violation; check
error.detailfor XPath.
Germany (XRechnung, ZUGFeRD, Peppol)
Germany has no central clearance authority for B2B. XRechnung and ZUGFeRD invoices are accepted immediately on valid XML. A Peppol send stays PENDING until the recipient's Access Point confirms, then becomes COMPLETED with stage: delivered; a rejection from that Access Point appears as REJECTED with error.source: "PEPPOL_AP".
Credit notes and debit notes
To correct an invoice you have already sent, send a new document with documentType: "credit_note" or "debit_note" and an originalInvoiceRef block that names the invoice being corrected. You do not need to store anything we return: the original is identified by the number and date you already hold in your own system.
| Field | Required | What to send |
|---|---|---|
originalInvoiceRef.invoiceNumber | Yes | The original invoice's own invoiceNumber, exactly as you sent it. |
originalInvoiceRef.issueDate | Yes | The original invoice's issue date as YYYY-MM-DD (for example 2026-06-19). This is the original's date, not the credit note's. |
invoiceNumber, issueDate (top level) | Yes | The credit or debit note's own new number and its own date. The note never reuses the original's number. |
{
"documentType": "credit_note",
"invoiceNumber": "CN-2026-0001",
"issueDate": "2026-07-02",
"originalInvoiceRef": {
"invoiceNumber": "INV-2026-0001",
"issueDate": "2026-06-19"
}
}
The example shows only the fields specific to a credit note; send the rest of the document (supplier, customer, lines) as you would for an invoice. originalInvoiceRef sits at the top level of the request, next to documentType; invoiceNumber and issueDate are nested inside it.
How the original is matched
- Clearvo finds the original by its number and issue date. The tax treatment, currency and lines are checked against the original it finds.
- If the original was issued before you started sending to Clearvo, the credit note is not refused. It is processed on its own, with its own lines and tax, and the response carries the warning
CREDIT_NOTE_ORIGINAL_NOT_FOUND. - If an invoice with that number exists but with a different issue date, it is treated as a different invoice. The credit note is processed on its own and the response carries the warning
CREDIT_NOTE_ORIGINAL_DATE_MISMATCH. Check the date you sent. - If the original is stored but cannot be submitted yet (it needs information, cannot be routed, is undelivered, is still in flight, or is held for a platform fault or an unmapped tax code), the credit note is stored and held. The response is
200withstatus: WAITING_FOR_PLATFORM,reason: HELD_AWAITING_ORIGINAL,errorCode: CREDIT_NOTE_AWAITING_ORIGINALandoriginalInvoiceId, the id of the stored original. There is nothing to do on the credit note: it is sent automatically once the original is accepted, delivered or accumulated, and refused withCREDIT_NOTE_ORIGINAL_NOT_ELIGIBLEif the original ends rejected. It never expires. A debit note does not wait. - A credit note is reported in the period of its own date.
The reference itself is required: a credit or debit note must identify the invoice it corrects. If originalInvoiceRef.invoiceNumber or originalInvoiceRef.issueDate is missing, the document is held as NEEDS_INFO (MISSING_ORIGINAL_INVOICE_NUMBER or MISSING_ORIGINAL_ISSUE_DATE) until you send it again with the reference. The warnings above apply only when the reference is sent but names an invoice Clearvo does not hold.
Dates are YYYY-MM-DD. A date in any other format is refused with INVALID_ORIGINAL_ISSUE_DATE_FORMAT (INVALID_ISSUE_DATE_FORMAT for the note's own date) unless a date rule brings it to that format first. If your system always writes dates the same other way, set that rule up once.
In a bulk upload
Use the columns original_invoice_number and original_invoice_date (date as YYYY-MM-DD) on each credit or debit note row. Poland also uses original_invoice_ksef_number, and original_invoice_reason is optional.
Supporting files (attachments)
Send supporting files with an invoice, such as a timesheet, a purchase order or a breakdown spreadsheet, in attachments[] on POST /v1/send. They are never embedded in the e-invoice: no XML or PDF contains them, and they are not sent to a tax authority or over the Peppol network. Clearvo stores each file securely, checks it for known malware test signatures and validates it against its declared file type (this is not a full antivirus scan), and offers it as a download next to the invoice.
| Field | Required | What to send |
|---|---|---|
attachments[].reference | Yes | Your identifier for the attachment. Errors name the attachment by this reference. |
attachments[].fileName | With contentBase64 | The file name including its extension, for example timesheet.pdf. |
attachments[].mimeType | With contentBase64 | The MIME type, for example application/pdf. It must agree with the file name extension. |
attachments[].contentBase64 | For a stored file | The raw file content, base64 encoded, with no data: prefix. |
attachments[].description | No | What the file is. It is shown next to the download. |
attachments[].externalUrl | For a link-only attachment | An http or https link. Sent on its own, it is kept as a link and not downloadable from Clearvo. |
{
"attachments": [
{
"reference": "timesheet-june",
"description": "Timesheet for June",
"fileName": "timesheet-june.pdf",
"mimeType": "application/pdf",
"contentBase64": "JVBERi0xLjQK..."
}
]
}
Accepted files and limits
- Types:
pdf,csv,xlsx,xls,ods,xml,png,jpgorjpeg, andtxt. The file name extension andmimeTypemust agree. - At most 10 MB per file, 25 MB in total and 20 attachments per invoice.
- The same rules apply for every country.
- An attachment that breaks a rule refuses the request with a
422that names the attachment, and nothing is stored. Fix it and send the invoice again.
Who sees the files
- Your customer sees them as downloads on the hosted invoice page, the page the link in the invoice email opens. When that link has expired, the downloads stop with it.
- You see them on the invoice in the dashboard, and through the API (below).
- A link-only attachment shows as a link to your own address; Clearvo does not hold the file.
Read them back
GET /v1/invoices/{id} lists the attachments of an invoice you issued (when it has any), next to the supporting files a supplier attached to an invoice you received. Each entry has id (your reference), index, fileName, mimeType, sizeBytes, sha256, description, externalUrl, downloadable and origin (sender for your own files, supplier for a received invoice). The bytes are never in that response. Rows in GET /v1/invoices carry attachmentCount. {id} is the Clearvo invoice id or your own reference id.
| Endpoint | What it does |
|---|---|
GET /v1/invoices/{id}/attachments | Lists the attachments: { ok, invoiceId, attachments[] }. A stored file has downloadable: true and a downloadUrl; a link-only attachment has downloadable: false and its externalUrl. |
GET /v1/invoices/{id}/attachments/{index} | Downloads one stored file, byte for byte, as an attachment of the MIME type it was sent with. {index} is the index from the list. |
Attachment error codes
| HTTP | Code | Meaning |
|---|---|---|
| 422 | TOO_MANY_ATTACHMENTS | More than 20 attachments on one invoice. |
| 422 | ATTACHMENT_INVALID | An entry in attachments[] is not an object with a reference and a file or link. |
| 422 | ATTACHMENT_METADATA_MISSING | A file was sent without its fileName or mimeType. |
| 422 | ATTACHMENT_CONTENT_INVALID | contentBase64 is not valid base64, or the file is empty. |
| 422 | ATTACHMENT_TYPE_NOT_ALLOWED | The file type is not one of the accepted types. |
| 422 | ATTACHMENT_TYPE_MISMATCH | The mimeType does not match the file name extension, or the file content does not match the declared type. |
| 422 | ATTACHMENT_TOO_LARGE | A file is over 10 MB. |
| 422 | ATTACHMENTS_TOTAL_TOO_LARGE | The files together are over 25 MB. |
| 422 | ATTACHMENT_URL_INVALID | externalUrl is not an http or https link. |
| 422 | ATTACHMENT_MALWARE_DETECTED | The check found a known malware test signature in a file. Nothing is stored. |
| 503 | ATTACHMENT_STORAGE_UNAVAILABLE | The files could not be stored right now. Send the same request again. |
| 404 | INVOICE_NOT_FOUND | Reading: no such invoice. |
| 404 | ATTACHMENT_NOT_FOUND | Downloading: no attachment at that index, or it is only a link. |
| 409 | AMBIGUOUS_REFERENCE | Reading: your reference matches more than one invoice. Use the Clearvo id. |
| 500 | ATTACHMENT_UNAVAILABLE | Downloading: the stored file could not be read. Try again. |
MCP, SDK and CLI
- MCP:
list_invoice_attachments(read-only) lists an invoice's files with their download URLs. There is no download tool, because a file is binary: download it with the SDK, the CLI or the endpoint above. - SDK:
listInvoiceAttachments(id)anddownloadInvoiceAttachment(id, index), which returns the file bytes with its name and MIME type. - CLI:
clearvo invoices attachments <id>lists the files;clearvo invoices download-attachment <id> <index> [--out file]saves one.
Receiving invoices
Invoices addressed to your entity arrive from every channel (Peppol, an authority such as KSeF or SAT, your supplier's platform, API, upload or email) and are handled the same way. Each is checked on arrival, stored, listed with GET /v1/invoices?direction=inbound (add country to narrow it) and announced by the invoice.received webhook.
- Each record carries
intakeChannel,receivedAt, avalidationblock (rule set, error and warning counts; it states what was checked and does not declare a document compliant), the supplier'sattachmentsand arendition. - Download an attachment with
GET /v1/invoices/{id}/attachments/{index}. For an invoice that arrived as XML,GET /v1/documents/{id}?format=pdfreturns a labelled PDF reader copy rendered from the structured data. - Where the authority has no push mechanism, Clearvo collects invoices in the background and you can ask for a collection now:
POST /v1/pl/inbound/poll(Poland),POST /v1/mx/inbound/poll(Mexico, at most once per 15 minutes),POST /v1/fr/inbound/poll(France). Poland needs a token that carries the invoice access permission. - Per-country set-up for receiving is in Setup and master data.
Credit notes and debit notes over Peppol
You can send credit notes and debit notes over the Peppol network in Belgium, the Netherlands, Austria, Croatia, Slovakia, Ireland, Norway, Sweden, Denmark, Finland, Lithuania, Latvia, Estonia, Luxembourg, Slovenia, Iceland, Switzerland, Germany (when the Peppol format is used), Australia and New Zealand.
- Credit notes use
documentType: "credit_note". A credit note reverses a previously accepted invoice in full. Partial credit notes over Peppol are not supported yet (France and Spain support partial credit notes). - Debit notes use
documentType: "debit_note". Peppol has no separate debit-note document, so a debit note is sent as an invoice marked as a debit note (UNTDID 1001 type code383). - Referencing the original invoice: pass an
originalInvoiceRefblock with the original invoice's owninvoiceNumberandissueDate. Clearvo matches the original by that number and date. A stored invoice with that number but another issue date is treated as a different invoice (warningCREDIT_NOTE_ORIGINAL_DATE_MISMATCH). The credit or debit note needs its own newinvoiceNumber. If the original is not stored in Clearvo (for example it was issued before you started sending), the credit note is not refused: it is processed on its own, with its own lines and tax and the original's number and date as the reference, and the response carries the warningCREDIT_NOTE_ORIGINAL_NOT_FOUND.
{
"documentType": "credit_note",
"invoiceNumber": "CN-2026-0001",
"originalInvoiceRef": {
"invoiceNumber": "INV-2026-0001",
"issueDate": "2026-06-19"
}
}
The example shows only the fields specific to a credit note; send the rest of the invoice (supplier, customer, lines, totals) as you would for an invoice.
In Germany, ZUGFeRD, XRechnung and Peppol all support credit and debit notes. Credit and debit notes you receive over Peppol appear in your inbox with the right label, and the "received" email says "credit note" or "debit note".
Not yet supported: Singapore, Japan and the UAE
Credit notes and debit notes are not yet supported over Peppol for Singapore, Japan and the UAE. The document is stored as a rejection (200) with code CREDIT_NOTE_PEPPOL_UNSUPPORTED. Send a corrected invoice instead, or contact support.