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

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.

ℹ
E-Invoicing uses the same base URL (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.

1
Submit

Send a POST /send request with your invoice data. Receive a referenceId and initial status.

2
Poll or listen

Call GET /status on a schedule, or configure a webhook to receive push notifications on every status transition.

3
Handle the outcome

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.

Getting Started

Quickstart

Submit your first invoice in under two minutes. This example sends an Italian B2B invoice to the SDI.

cURL
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:

JSON Response
{
  "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.

E-Invoicing API

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.

ℹ
Endpoint: POST https://api.clearvo.io/v1/send
!
A 200 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

JavaScript
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

FieldTypeDescription
okbooleanComes 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.
countrystringISO country code the invoice was routed to.
referenceIdstringClearvo-assigned identifier for this invoice submission. Use with GET /status.
statusstringInitial status — PENDING for async countries; COMPLETED immediately for synchronous flows (DE B2B).
stagestring?Where in the journey: queued, awaiting_authority (PENDING), or generated, reported, cleared, delivered, received (COMPLETED). Null otherwise.
reasonstringThe specific cause behind the status.
issuesarrayWarnings and errors attached to the document.
customerResponseobject?The customer's decision, when there is one.
terminalbooleantrue when the status will not change again. Stop polling when true.
submittedAtstring (ISO 8601)UTC timestamp of submission.
nextPollAfterstring (ISO 8601)Earliest time to poll for an update. Respect this to avoid rate limiting.
E-Invoicing API

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.

ℹ
Endpoint: GET https://api.clearvo.io/v1/status?country=IT&id=<referenceId>

Query parameters

ParameterTypeDescription
countrystringISO 3166-1 alpha-2 country code. Required
idstringThe referenceId returned by POST /send. Required

Polling loop (JavaScript)

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

FieldTypeDescription
statusstringCurrent status. See status values below.
stagestring?Where in the journey, for PENDING and COMPLETED.
reasonstringThe specific cause behind the status.
issuesarrayWarnings and errors attached to the document.
customerResponseobject?The customer's decision, when there is one.
terminalbooleanStop polling when true.
eventsarrayOrdered array of status transitions. Each entry has at (ISO 8601), event (the status or step name) and detail (free-text description).
clearedAtstring?Timestamp of clearance. Present when status is COMPLETED with stage cleared or delivered.
rejectedAtstring?Timestamp of rejection. Present only when REJECTED.
errorobject?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).
errorCodestring?Structured error code, present whenever the invoice failed with a mapped reason (pre-submission validation failures as well as authority rejections).
suggestedActionstring?What to do next, in plain language. Present with errorCode.
isMerchantResolvableboolean?true when you can fix the cause yourself (for example, missing data); false when it needs Clearvo or the authority. Present with errorCode.
fixUrlstring?Link to the dashboard page where the problem can be fixed, when there is one.
mcDeadlinestring?Italy only. The SDI 10-day delivery deadline in ISO 8601. Present only when reason is UNDELIVERED.
nextPollAfterstring?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.

StatusTerminal?Description
RECEIVEDNoStored, processing not finished.
PENDINGNoIn progress. stage is queued or awaiting_authority. Continue polling.
WAITING_FOR_YOUNoOnly 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_PLATFORMNoOnly 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.
ACCUMULATEDNoIncluded in a periodic report not yet filed.
COMPLETEDYesFinished 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.
REJECTEDYesThe authority or a validation rule refused the invoice. Check the error block for reason codes.
CANCELLEDYesReported, then withdrawn.
SKIPPEDYesYou discarded it, so it is not submitted. You can reverse this.
NOT_APPLICABLEYesNothing 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.
Peppol API

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.

ℹ
Endpoint: GET https://api.clearvo.io/v1/participants/lookup?country=BE&vatNumber=BE0420429272

Query parameters

ParameterTypeDescription
countrystringISO country code. Required when using vatNumber. Optional with electronicAddress
vatNumberstringCustomer VAT number. Clearvo derives the Peppol participant ID automatically. Optional if electronicAddress provided
electronicAddressstringExplicit Peppol identifier (e.g. 0420429272). Requires electronicAddressSchemeId or country. Optional if vatNumber provided
electronicAddressSchemeIdstringEAS code (e.g. 0208). Used with explicit electronicAddress. Optional
documentTypestringinvoice or credit_note. Determines which document type ID to look up in SMP. Default: invoice. Optional
forceRefreshbooleanSet to true to bypass cache and re-query the SML live. Optional

Response

FieldTypeDescription
registeredbooleantrue if the customer is registered on Peppol and has a reachable endpoint.
participantIdstring?Canonical Peppol participant ID, e.g. iso6523-actorid-upis::0208:0420429272.
endpointUrlstring?The customer's AS4 endpoint URL. Present when registered: true.
derivedFromstring?"vatNumber" or "electronicAddress" — how the participant ID was resolved.
cachedboolean?true if the result was served from cache; false if a live SML lookup was performed.
checkedAtstring?ISO 8601 timestamp of the last SML lookup.
Peppol API

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.

ℹ
Endpoint: POST https://api.clearvo.io/v1/invoices/{id}/deliver

Path parameter

ParameterTypeDescription
idstringInvoice id or referenceId returned by POST /send. Required

Request body (optional)

FieldTypeDescription
electronicAddress.valuestringOverride the customer's Peppol endpoint identifier. Use this once the customer has registered, or to correct a wrong value. Optional
electronicAddress.schemeIdstringEAS code for the override electronicAddress.value. Optional

Response

FieldTypeDescription
okbooleantrue on delivery success, false if still unroutable.
statusstringCOMPLETED on success; WAITING_FOR_YOU on failure.
reasonstringDELIVERED on success; UNROUTABLE on failure.
nrrboolean?Present on success. true if the receiver's AP returned a Non-Repudiation Receipt.
deliveryErrorobject?Present on failure. { code, message, retryable }.

Error responses

HTTPMeaning
404No record found for the given id.
409Invoice is not waiting on an unroutable customer (reason is not UNROUTABLE; for example already COMPLETED).
422No stored XML or customer endpoint cannot be determined; provide electronicAddress in the body.
E-Invoicing API

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
ITSDI (Agenzia delle Entrate)FatturaPA 1.2ClearanceMandatory since Jan 2019
PLKSeF (Ministry of Finance)FA(3) XMLClearanceLarge taxpayers from 1 Feb 2026; all other VAT payers from 1 Apr 2026; penalties from 1 Jan 2027
ROANAF e-FacturaCIUS-RO (UBL)ClearanceB2B mandatory since 1 Jan 2024
ARAFIPFactura Electrónica (CAE)ClearanceMandatory
SAZATCA (Fatoora)UBL 2.1Clearance (B2B/B2G); reporting within 24h (B2C)Mandatory, phased by taxpayer wave
EGETAETA e-invoiceClearanceMandatory
JOISTD JoFotaraUBL 2.1ClearanceMandatory
Real-time and periodic reporting — the invoice is issued directly, data is reported to the authority
HUNAV Online SzámlaOnline Számla v3.0 XMLReal-time reportingSince Jul 2018; all invoices (including zero VAT) since Jan 2021
GRAADE myDATAmyDATA XMLReal-time reportingMandatory since Nov 2021
ES (SII)AEAT — Suministro Inmediato de InformaciónSII XMLReal-time reporting (VAT ledger)Mandatory for large taxpayers, VAT groups and REDEME since Jul 2017; voluntary for others
ES (VeriFactu)AEATVeriFactu XML (hash-chained records)Certified billing recordsPostponed (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
PTAT (Autoridade Tributária)SAF-T (PT) + ATCUD + QR codeCertified invoicing + invoice-data communicationCertified software required today
FRDGFiP — via an accredited platform (PA)Factur-X (EN16931)Network delivery + e-reportingReceiving: 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)
DENo central authorityXRechnung 3.0 (UBL), ZUGFeRD (CII, EN16931 profile) or Peppol BIS 3.0Generate, or deliver over PeppolReceiving: 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
BEOpenPeppolPeppol BIS 3.0 UBLNetwork deliveryB2B mandatory from 1 Jan 2026 (penalties from 1 Apr 2026)
NLOpenPeppol / DigipoortPeppol BIS 3.0 UBLNetwork deliveryB2G mandatory
ATOpenPeppol / eRechnung.gv.atPeppol BIS 3.0 UBLNetwork deliveryB2G mandatory
HROpenPeppol / FINAPeppol BIS 3.0 UBLNetwork deliveryMandatory from 2026
SKOpenPeppol / Financial AdministrationPeppol BIS 3.0 UBL (+ Tax Data Document)Network delivery + tax data reportingB2B mandatory from 1 Jan 2027
IEOpenPeppol / OGPPeppol BIS 3.0 UBLNetwork deliveryB2G mandatory
NOOpenPeppol / DFØPeppol BIS 3.0 UBLNetwork deliveryB2G mandatory
SEOpenPeppol / SkatteverketPeppol BIS 3.0 UBLNetwork deliveryB2G mandatory
DKOpenPeppol / NemHandelPeppol BIS 3.0 UBLNetwork deliveryB2G mandatory
FIOpenPeppol / VeroPeppol BIS 3.0 UBLNetwork deliveryB2G mandatory
LTOpenPeppol / VMIPeppol BIS 3.0 UBLNetwork deliveryB2G mandatory
LVOpenPeppol / VIDPeppol BIS 3.0 UBLNetwork deliveryB2G mandatory
EEOpenPeppol / MTAPeppol BIS 3.0 UBLNetwork deliveryB2G mandatory
LUOpenPeppolPeppol BIS 3.0 UBLNetwork deliveryB2G mandatory
SIOpenPeppol / FURSPeppol BIS 3.0 UBLNetwork deliveryB2G mandatory
ISOpenPeppol / RSKPeppol BIS 3.0 UBLNetwork deliveryB2G mandatory
CHOpenPeppol / SIXPeppol BIS 3.0 UBLNetwork deliveryNo mandate; B2B via Peppol network
Peppol PINT — Asia-Pacific & Gulf
AUATO / OpenPeppolPeppol PINT A-NZNetwork deliveryB2G mandatory
NZNZ Peppol AuthorityPeppol PINT A-NZNetwork deliveryB2G mandatory
JPDigital Agency / OpenPeppolPeppol JP PINTNetwork deliveryVoluntary; B2G adoption
SGIMDA / IRAS (InvoiceNow)Peppol SG PINTNetwork deliveryGST InvoiceNow phased in from 2025 to 2031 by registrant type
AEMinistry of Finance / FTAPeppol UAE PINTNetwork deliveryPilot from 1 Jul 2026; large businesses from 1 Jan 2027
Receive-only — Clearvo ingests, validates and stores invoices your suppliers issue
MXSATCFDI 4.0ReceivingMandatory (issued by suppliers through their PAC)
BRSEFAZNF-e / NFS-eReceivingMandatory (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.

ℹ
Peppol delivery. All Peppol countries use the same BIS Billing 3.0 payload. Only 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.
✓
Singapore, Japan and the UAE are supported at format level. Production delivery there depends on local accreditation, so contact hello@clearvo.io before planning a launch.
Invoice Schema

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.

FieldTypeDescription
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.

Invoice Schema

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.

FieldTypeDescription
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
JSON — Party example
{
  "name": "Acme SRL",
  "taxId": "01234567890",
  "establishmentCountry": "IT",
  "address": {
    "street": "Via Roma 1",
    "city": "Milano",
    "postalCode": "20121",
    "country": "IT"
  }
}
Invoice Schema

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.

FieldTypeDescription
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
Invoice Schema

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.

CodeCategoryRates (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).
⚠
Using 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[]).
Invoice Schema

Payment object

Optional payment details embedded in the invoice. Included in the generated XML where the authority format supports it (FatturaPA, UBL, XRechnung).

FieldTypeDescription
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.

Invoice Schema

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

FieldTypeDescription
countryData.it.codiceFiscalestringCustomer's Italian fiscal code (for individuals). Optional
countryData.it.codiceDestinatariostringSDI recipient code (7-char). Provide if known; Clearvo looks it up via SMP if omitted. Optional
countryData.it.pecDestinatariostringCustomer 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.

FieldTypeDescription
countrySpecific.de.invoiceFormatstringZUGFERD, 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.leitwegIdstringLeitweg-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.

FieldTypeDescription
countrySpecific.pl.sellerNipstringOverride supplier NIP (10 digits). Auto-derived from supplier.taxId when prefixed with PL. Optional
countrySpecific.pl.customerNipstringOverride customer NIP (10 digits). Auto-derived from customer.taxId. Optional
countrySpecific.pl.splitPaymentbooleanEnable MPP (Mechanizm Podzielonej Płatności). Required for Annex 15 transactions > PLN 15,000. Optional
countrySpecific.pl.gtuCodesstring[]GTU_01–GTU_13 classification codes for Annex 15 goods/services. E.g. ["GTU_12"]. Optional
countrySpecific.pl.rodzajFakturystringFA(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.

Error Reference

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.detail for 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".

Reference

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.

FieldRequiredWhat to send
originalInvoiceRef.invoiceNumberYesThe original invoice's own invoiceNumber, exactly as you sent it.
originalInvoiceRef.issueDateYesThe 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)YesThe credit or debit note's own new number and its own date. The note never reuses the original's number.
JSON
{
  "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 200 with status: WAITING_FOR_PLATFORM, reason: HELD_AWAITING_ORIGINAL, errorCode: CREDIT_NOTE_AWAITING_ORIGINAL and originalInvoiceId, 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 with CREDIT_NOTE_ORIGINAL_NOT_ELIGIBLE if 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.

Reference

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.

FieldRequiredWhat to send
attachments[].referenceYesYour identifier for the attachment. Errors name the attachment by this reference.
attachments[].fileNameWith contentBase64The file name including its extension, for example timesheet.pdf.
attachments[].mimeTypeWith contentBase64The MIME type, for example application/pdf. It must agree with the file name extension.
attachments[].contentBase64For a stored fileThe raw file content, base64 encoded, with no data: prefix.
attachments[].descriptionNoWhat the file is. It is shown next to the download.
attachments[].externalUrlFor a link-only attachmentAn http or https link. Sent on its own, it is kept as a link and not downloadable from Clearvo.
JSON
{
  "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, jpg or jpeg, and txt. The file name extension and mimeType must 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 422 that 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.

EndpointWhat it does
GET /v1/invoices/{id}/attachmentsLists 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

HTTPCodeMeaning
422TOO_MANY_ATTACHMENTSMore than 20 attachments on one invoice.
422ATTACHMENT_INVALIDAn entry in attachments[] is not an object with a reference and a file or link.
422ATTACHMENT_METADATA_MISSINGA file was sent without its fileName or mimeType.
422ATTACHMENT_CONTENT_INVALIDcontentBase64 is not valid base64, or the file is empty.
422ATTACHMENT_TYPE_NOT_ALLOWEDThe file type is not one of the accepted types.
422ATTACHMENT_TYPE_MISMATCHThe mimeType does not match the file name extension, or the file content does not match the declared type.
422ATTACHMENT_TOO_LARGEA file is over 10 MB.
422ATTACHMENTS_TOTAL_TOO_LARGEThe files together are over 25 MB.
422ATTACHMENT_URL_INVALIDexternalUrl is not an http or https link.
422ATTACHMENT_MALWARE_DETECTEDThe check found a known malware test signature in a file. Nothing is stored.
503ATTACHMENT_STORAGE_UNAVAILABLEThe files could not be stored right now. Send the same request again.
404INVOICE_NOT_FOUNDReading: no such invoice.
404ATTACHMENT_NOT_FOUNDDownloading: no attachment at that index, or it is only a link.
409AMBIGUOUS_REFERENCEReading: your reference matches more than one invoice. Use the Clearvo id.
500ATTACHMENT_UNAVAILABLEDownloading: 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) and downloadInvoiceAttachment(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.
Reference

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, a validation block (rule set, error and warning counts; it states what was checked and does not declare a document compliant), the supplier's attachments and a rendition.
  • Download an attachment with GET /v1/invoices/{id}/attachments/{index}. For an invoice that arrived as XML, GET /v1/documents/{id}?format=pdf returns 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.
Delivery

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 code 383).
  • Referencing the original invoice: pass an originalInvoiceRef block with the original invoice's own invoiceNumber and issueDate. 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 (warning CREDIT_NOTE_ORIGINAL_DATE_MISMATCH). The credit or debit note needs its own new invoiceNumber. 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 warning CREDIT_NOTE_ORIGINAL_NOT_FOUND.
JSON
{
  "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.