Invoicing

Invoicing turns structured data into a legally valid German e-invoice. Your system sends the buyer, the lines and the references; meetergo allocates the number, freezes an EN 16931 record, renders the PDF on your letterhead and packages it as a ZUGFeRD hybrid or an XRechnung XML. You can keep your own UI and permissions and pull every finished document back into your database. The full field list, with the EN 16931 business term (BT) each field maps to, is on the E-invoice fields page.

Invoicing is a paid feature. If your plan does not include it, every endpoint below returns 403. Any member of a company that has the feature can use these endpoints; there is no separate invoicing permission.

Authentication

Use a personal access token with the Invoicing capability (invoicing), or a full-access token. A token limited to other capabilities receives 403 This token does not carry the 'invoicing' capability.

curl https://api.meetergo.com/invoicing/documents \
  -H "Authorization: Bearer YOUR_TOKEN"

A token belongs to one company, and one company is one seller. You never send seller data on a document: name, address, tax numbers, bank account, logo and footer all come from the company’s invoicing settings (GET /invoicing/settings, PUT /invoicing/settings, or the dashboard). If you invoice from two legal entities, use two companies with one token each.

The document lifecycle

Creating a document does not produce an invoice anyone can pay. There are three distinct calls, and the third is optional when you deliver the invoice yourself.

Create a draft

POST /invoicing/documents returns a draft with an id. It has no number, no PDF and no XML, and you can still change everything on it with PATCH /invoicing/documents/{id}.

Finalize it

POST /invoicing/documents/{id}/finalize validates the document, allocates the next number from your number range, freezes the EN 16931 record, renders the PDF and the XML, packages and validates them, and stores both. The call is synchronous. The response is the finished document. After this the document is immutable; corrections go through a credit note or a cancellation, which is what the law expects.

Deliver it

Either fetch the files and send them yourself (GET /invoicing/documents/{id}/download/pdf and /download/xml), or let meetergo email them with POST /invoicing/documents/{id}/send.

1. Create a draft

Only buyer.name is strictly required to create a draft. Finalizing needs more: at least one line item, and a Steuernummer or USt-IdNr on your invoicing settings. Send everything you know at creation time; a draft can be patched, but the fewer round trips the better.

curl -X POST "https://api.meetergo.com/invoicing/documents" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "invoice",
    "language": "de",
    "issueDate": "2026-10-01",
    "deliveryDate": "2026-09-01",
    "deliveryDateEnd": "2026-09-30",
    "dueDate": "2026-10-15",
    "currency": "EUR",
    "subject": "Franchisegebühr September 2026",
    "buyer": {
      "name": "Küchenstudio Musterstadt GmbH",
      "addressLine1": "Hauptstraße 1",
      "postalCode": "12345",
      "city": "Musterstadt",
      "countryCode": "DE",
      "email": "buchhaltung@example.com",
      "vatId": "DE123456789",
      "reference": "PO-2026-0917"
    },
    "lines": [
      {
        "name": "Franchisegebühr",
        "description": "Leistungszeitraum 01.09.2026 bis 30.09.2026",
        "quantity": 1,
        "unitCode": "C62",
        "unitPrice": 1250.00,
        "taxCategory": "S",
        "taxRate": 19
      },
      {
        "name": "Marketingumlage",
        "quantity": 1,
        "unitPrice": 300.00,
        "discountPercent": 10,
        "taxCategory": "S",
        "taxRate": 19
      }
    ],
    "taxTreatment": "standard",
    "paymentTermsNote": "Zahlbar innerhalb von 14 Tagen ohne Abzug.",
    "skontoPercent": 2,
    "skontoDays": 7,
    "internalContactUserId": "the-meetergo-user-uuid",
    "note": "Bitte geben Sie bei der Zahlung die Rechnungsnummer an."
  }'

The response is the document: id, status: "draft", number: null, the lines with their id, position and computed netAmount, and the totals netTotal, taxTotal, grossTotal. Totals are recomputed on every save and again at finalization; never send them.

internalContactUserId is the meetergo user printed as the seller contact (BG-6). XRechnung requires one. Look users up with GET /v4/user.

2. Finalize

curl -X POST "https://api.meetergo.com/invoicing/documents/{id}/finalize" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "profile": "zugferd-en16931" }'

`profile`	Output	Validation gate
`zugferd-en16931` (default)	PDF/A-3 with the EN 16931 CII XML embedded (ZUGFeRD 2.x, profile EN 16931), plus the same XML as a separate file	Mustang packaging and veraPDF PDF/A-3 conformance. The EN 16931 profile is not an XRechnung scenario, so the KoSIT validator is not applied here.
`xrechnung-cii`	XRechnung 3.0 CII XML (`urn:xeinkauf.de:kosit:xrechnung_3.0`), plus a plain PDF for humans	KoSIT validator, the same Schematron the German authorities run. The document is rejected if it does not pass.

Finalization is all or nothing. The number is allocated only after the document passes the built-in checks, so a rejected document never burns a number. Order of events:

Emittability check (mandatory fields, tax rules). Fails with 422.
Number allocation from the range for the document’s kind and year.
EN 16931 snapshot frozen, XML and PDF rendered.
External validation and packaging. Fails with 400; if the validation service is down the call fails with 503 and the document stays a draft.
PDF and XML stored, status becomes finalized.

The response is the finalized document:

{
  "id": "6f1c…",
  "kind": "invoice",
  "status": "finalized",
  "number": "RE-2026-00042",
  "issueDate": "2026-10-01",
  "dueDate": "2026-10-15",
  "grossTotal": 1808.80,
  "finalizedAt": "2026-10-01T09:12:44.000Z",
  "pdfFileAssetId": "…",
  "xmlFileAssetId": "…",
  "publicToken": "…",
  "snapshot": { "profile": "zugferd-en16931", "number": "RE-2026-00042", "seller": { … }, "buyer": { … }, "lines": [ … ], "taxTotals": [ … ], "netTotal": 1520.00, "taxTotal": 288.80, "grossTotal": 1808.80 },
  "lines": [ … ]
}

snapshot is the frozen EN 16931 record the XML and the PDF were rendered from, as JSON. If you mirror invoices into your own database, store this object: it is the complete, immutable content of the document, including the seller block resolved from settings at the time of issue.

3. Fetch the files

curl "https://api.meetergo.com/invoicing/documents/{id}/download/pdf" \
  -H "Authorization: Bearer YOUR_TOKEN"

{ "url": "https://…signed…", "filename": "RE-2026-00042.pdf" }

type is pdf or xml. The URL is a short-lived signed link: download it right away and keep the bytes, not the URL. On a draft the endpoint returns 404 Document has no generated file yet. For a rendering of a draft before finalization, GET /invoicing/documents/{id}/preview returns { "pdf": "<base64>" } with a placeholder number.

Or let meetergo send it

POST /invoicing/documents/{id}/send emails the PDF and XML to buyer.email (override with to), with the hosted payment link when a payment provider is connected and includePaymentLink is not false. status becomes sent.

Reading documents back

Endpoint	Returns
`GET /invoicing/documents?kind=invoice&status=finalized&page=1&limit=50`	`{ result: [...], total, page, limit }`, newest first. `kinds=invoice,cancellation` selects several kinds; `search` matches number and buyer name.
`GET /invoicing/documents/{id}`	One document with `lines` and, once finalized, `snapshot`.
`GET /invoicing/documents/{id}/events`	Append-only audit trail: `created`, `updated`, `finalized`, `sent`, `payment_recorded`, `reminder_sent`, `cancelled`, `accepted`, `rejected`.

There are no webhooks for invoicing documents yet. Poll the list endpoint with status filters, or read events for a document you hold.

Document kinds and statuses

`kind`	What it is
`offer`	A quote. Can be accepted or rejected, then converted with `POST /invoicing/documents/{id}/convert-to-invoice`.
`order_confirmation`	Auftragsbestätigung.
`invoice`	The billable document (EN 16931 type code 380).
`credit_note`	Gutschrift (381), correcting an invoice in part or in full. Created with `POST /invoicing/documents/{id}/credit-note` and issued with `POST /invoicing/credit-notes/{id}/issue`.
`cancellation`	Storno (384), voiding an invoice in full. Created with `POST /invoicing/documents/{id}/cancel`.

`status`	Meaning
`draft`	Editable, no number yet.
`finalized`	Numbered and frozen, not yet sent.
`sent`	Delivered to the buyer by meetergo.
`partially_paid`	Some payments recorded, balance outstanding.
`paid`	Settled.
`cancelled`	Voided by a Storno.
`accepted` / `rejected`	Offers only.

Rendering

The PDF follows DIN 5008 and is rendered by meetergo from the same snapshot as the XML. Layout, accent colour and logo are company settings (layout, logoFileAssetId); the document language (de or en) picks the wording. There is no way to supply your own PDF; the hybrid must be built from the structured data so the visual and the XML cannot disagree.

Planned: a per-document letterhead choice, for sellers who print the same layout with different logos (for example one logo per country the buyer is in). Until it ships, one logo per company.

Tax treatment

Set taxTreatment on the document when the default German standard rate does not apply. Anything except standard and oss forces the matching EN 16931 category and its exemption wording onto every line.

`taxTreatment`	Category on the lines	Typical use
`standard`	per line (`S`, `Z`, …)	Domestic B2B/B2C
`tax_free_de`	`E`	§ 4 UStG
`reverse_charge_13b`	`AE`	Domestic reverse charge
`reverse_charge_18b`	`AE`	EU services, e.g. to an Austrian business
`intra_community`	`K`	EU goods
`oss`	per line	One-Stop-Shop, destination-country rates
`export`	`G`	Non-EU
`out_of_scope`	`O`	Not taxable in Germany, e.g. Switzerland

The exemption text printed for E, AE, K, G and O defaults to the German statutory wording and can be replaced per category in PUT /invoicing/settings (taxExemptionNotes).

Errors you will meet

Status	When	Body
`400`	Validation of the request body failed	`message[]` per field
`400`	External e-invoice validation rejected the document at finalize	`The e-invoice failed validation and was not finalized…`
`403`	Token lacks the capability, or the plan lacks the feature
`403`	Monthly invoice cap of the plan reached	`code: "PLAN_LIMIT_REACHED"`
`404`	Unknown document, or no file yet on a draft
`409`	Finalizing a document that is not a draft	`Document is already finalized`
`422`	Emittability check failed at finalize	`invoiceProblems: [{ code, scope, message }]`
`503`	Validation service unreachable; document stays a draft, retry later

invoiceProblems[].scope says where to fix it: settings (seller side) or document. Codes: missingInvoiceNumber, invalidIssueDate, missingSellerName, missingSellerTaxId, missingSellerAddress, missingBuyerName, missingLines, missingExemptionReason, and for XRechnung missingBuyerReference, missingSellerContact, missingPaymentMeans, missingSellerElectronicAddress, missingBuyerElectronicAddress.

Getting paid

Two paths, and most businesses use both. Hosted payment page. GET /invoicing/documents/{id}/payment-link returns the public URL of the invoice. Every finalized invoice has one; a draft has none yet, and the endpoint returns { "url": null } until you finalize it. The page offers card, PayPal and Mollie only for the providers you have connected; the payment is recorded against the invoice automatically through the provider’s webhook. Bank transfer and cash. Record these yourself:

curl -X POST "https://api.meetergo.com/invoicing/documents/{id}/payments" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 95, "method": "bank_transfer", "paidAt": "2026-03-01" }'

method accepts bank_transfer, cash or other. paidAt lets you backdate to the Wertstellung. The invoice’s amountPaid, paidAt and status are derived from the payments on it, so a partial amount produces partially_paid. A payment recorded by mistake is removed with DELETE .../payments/{paymentId}.

meetergo does not read your bank account. Incoming transfers have to be recorded through this endpoint, either by hand in the dashboard or by your own automation. The invoice PDF carries an EPC QR code so the buyer’s banking app can prefill the transfer, but the match back is yours to make.

Mahnwesen

Configure reminder levels once, in PUT /invoicing/settings:

{
  "dunning": {
    "autoSend": true,
    "interestRatePercent": 9.12,
    "levels": [
      { "label": "Zahlungserinnerung", "daysAfterDue": 7,  "feeAmount": 0,  "payWithinDays": 7 },
      { "label": "1. Mahnung",         "daysAfterDue": 14, "feeAmount": 5,  "payWithinDays": 7 },
      { "label": "2. Mahnung",         "daysAfterDue": 14, "feeAmount": 10, "payWithinDays": 7 }
    ]
  }
}

With autoSend on, meetergo sends the next due reminder on weekday mornings. Levels never skip: the first counts from the due date, later ones from the last reminder. Each reminder is its own PDF on your letterhead with the original invoice attached; the invoice document itself is never altered. If your own system owns collections, leave autoSend off and POST /invoicing/documents/{id}/dunning-pause for invoices you handle elsewhere.

Endpoint	Use
`GET /invoicing/documents/{id}/dunning/preview`	What the next reminder would say.
`POST /invoicing/documents/{id}/dunning/send`	Send it now, ahead of schedule.
`POST /invoicing/documents/{id}/dunning-pause`	Exclude this invoice from auto-send.

Linking a document to the rest of meetergo

Field	Links to
`contactId`	A CRM contact. See Contacts.
`dealId`	A CRM deal, so the deal shows its revenue.
`appointmentId`	The booking the work was done in.

GET /invoicing/buyer-prefill/company/{crmCompanyId} builds a buyer block from a CRM company you already have, so you do not have to reassemble the address.

Products, recurring invoices and export

Endpoint	Use
`/invoicing/products`	A catalogue you can reference from a line with `productId`.
`/invoicing/recurring`	Schedules that materialize invoices on a cadence, optionally finalizing and sending them.
`/invoicing/billing-runs`	Turn completed meetings in a period into invoice lines.
`/invoicing/number-ranges`	Number format per document kind and year.
`/invoicing/datev/export`	ZIP with the EXTF Buchungsstapel and document PDFs.

E-invoice fields
Contacts
CRM deal to invoice
Every request and response schema: API Reference → Invoicing

Get Started

Core Concepts

Webhooks

Components

Recipes

Best Practices

Authentication

The document lifecycle

1. Create a draft

2. Finalize

3. Fetch the files

Or let meetergo send it

Reading documents back

Document kinds and statuses

Rendering

Tax treatment

Errors you will meet

Getting paid

Mahnwesen

Linking a document to the rest of meetergo

Products, recurring invoices and export

​Authentication

​The document lifecycle

​1. Create a draft

​2. Finalize

​3. Fetch the files

​Or let meetergo send it

​Reading documents back

​Document kinds and statuses

​Rendering

​Tax treatment

​Errors you will meet

​Getting paid

​Mahnwesen

​Linking a document to the rest of meetergo

​Products, recurring invoices and export

​Related

Authentication

The document lifecycle

1. Create a draft

2. Finalize

3. Fetch the files

Or let meetergo send it

Reading documents back

Document kinds and statuses

Rendering

Tax treatment

Errors you will meet

Getting paid

Mahnwesen

Linking a document to the rest of meetergo

Products, recurring invoices and export

Related