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. Seller data comes from the company’s invoicing settings (GET /invoicing/settings, PUT /invoicing/settings, or the dashboard) or the complete seller profile selected with sellerProfileId. Use additional seller profiles to invoice from multiple legal entities within one company.

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",
    "costCenter": "STORE-42",
    "customFields": [{ "label": "Profit Center", "value": "4711" }],
    "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",
      "customerNumber": "C-4711"
    },
    "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. costCenter is your own cost center (Kostenstelle/Profitcenter). It is printed on the PDF and written to DATEV KOST1. It is not part of the e-invoice XML, because BT-19 is the buyer’s accounting reference. Cost centers accept at most 36 characters, are trimmed, and cannot be blank. buyer.customerNumber (BT-46) and up to 5 customFields are supported in the PDF info block and XML. Dunning PDFs repeat these frozen references and the cost center. See E-invoice fields for limits and response examples.

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.

If your billing system reserves numbers centrally, supply one at finalize:

{ "profile": "zugferd-en16931", "number": "CENTRAL-2026-4711" }

number is trimmed and must be 1 to 64 printable characters, without control characters. It must be unique across all document kinds within your company. Duplicates return 409 with code: "NUMBER_TAKEN", including concurrent requests. No meetergo range number is consumed. Maintaining a gapless external sequence is the caller’s responsibility. Without number, meetergo allocates from the configured range. Only this endpoint accepts an external number; credit notes and cancellations use their ranges. Built-in validation runs before number allocation or the external-number uniqueness check. A later packaging or storage failure leaves the document a draft and can leave a logged gap in a meetergo number range. Order of events:

Emittability check (mandatory fields, tax rules). Fails with 422.
Check the supplied number, or allocate 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.

{
  "to": "buchhaltung@example.com",
  "cc": [
    "purchasing@example.com"
  ],
  "bcc": [
    "archive@example.com"
  ],
  "includePaymentLink": false
}

Each of cc and bcc accepts at most 5 email addresses. Addresses are trimmed and deduplicated ignoring case, and the final to address is removed from the copy lists. BCC takes priority over CC for an address appearing in both. For an accounting copy on every document email and every dunning reminder, set the default with PUT /invoicing/settings:

{
  "documentMail": {
    "bcc": [
      "accounting@example.com"
    ]
  }
}

The default accepts up to 5 addresses and is merged with per-send BCC. Set it to [] to disable default copies. The sent audit event records the actual to, cc and bcc lists.

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 come from the selected seller (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.

Multiple sellers (Rechnungssteller)

The existing invoicing settings remain the default seller. Additional legal entities have complete seller profiles, with their own legal name, address, VAT and tax details, contact and register information, tax policy, bank account, logo and PDF layout. Profiles do not inherit missing identity fields from the default seller. Each profile has its own defaultCurrency for new invoices and offers; null derives it from the profile’s country, while products keep the company-wide default. Use GET or POST /invoicing/seller-profiles to list or create profiles. GET and PATCH /invoicing/seller-profiles/{id} read and update one profile. POST /invoicing/seller-profiles/{id}/archive and /restore control availability. DELETE /invoicing/seller-profiles/{id} removes a profile only while unused. Set sellerProfileId when creating or updating a draft. Omit it on creation, or set it to null, to use the default seller. Archived profiles cannot be selected for new drafts. Existing drafts keep their archived seller and branch and can still be edited and finalized. Credit notes, cancellations, deposits and offer conversions can still follow issued documents. Active recurring schedules block archiving; any recurring template blocks deletion until its seller is changed. Finalization freezes the seller identity and branding, so later profile edits do not change issued documents or their reminders. Document lists (GET /invoicing/documents and invoicing.documents over oRPC) accept sellerProfileId: omit it or send null for all sellers, send default for the company seller only, or send a seller UUID for that seller’s documents. All results remain scoped to the caller’s company. Number series belong to a seller (sellerProfileId on the series). A seller without a series for a document kind cannot finalize that kind (HTTP 422). An explicit document range must belong to the same seller. Changing a draft’s seller clears its selected range. Follow-up creation checks the target kind’s range before saving, so a missing range returns HTTP 422 without leaving a draft. Number-range lists without sellerProfileId contain only the default seller; pass a seller ID to list its ranges. Every range includes its sellerProfileId. Every plan includes one seller, including the default. Additional sellers require a company allowance agreed with meetergo. Archived sellers still count. Exceeding the allowance returns HTTP 403 with code: "PLAN_LIMIT_REACHED", feature: "sellerProfiles" and limit. Pass sellerProfileId to the DATEV export or advisor handoff to export only that seller’s documents using its own datev.consultantNumber and datev.clientNumber. Omitting it from the ZIP download exports the default seller, which also owns incoming documents until these support seller assignment. Seller ZIP filenames include the seller name; default filenames stay unchanged. The advisor handoff uses the same selection as the download: omitted or null sellerProfileId exports only the default seller; an ID exports only that profile, including archived profiles. Each uses its own DATEV settings and advisor email, falling back to the company advisor email. The response retains sentTo and documentCount for that single export. Lexware sync only exports default-seller documents.

Branches (Filialen)

A branch is a store or office of one legal seller, including the default seller. It supplies the printed sender address and contact details plus an optional default cost center. Branches have no legal identity, number range, plan cap or extra price. Use GET and POST /invoicing/branches, GET, PATCH and DELETE /invoicing/branches/:id, and POST /invoicing/branches/:id/archive or /restore. List filters are sellerProfileId (empty for the default seller), externalKey and includeArchived=true. The optional externalKey is your own branch identifier and is unique within your company. Send branchId on a document draft. It selects the branch’s seller unless you also send sellerProfileId, which must match. The document takes the branch’s costCenter unless the same request sends a value or null. When a PATCH changes the branch without sending costCenter, the cost center becomes the new branch’s value, which may be null. Changing sellers clears an incompatible branch; branchId: null clears the selection. Finalization freezes the branch for the PDF, pay page and e-invoice. Follow-up documents keep that frozen branch even after it is archived. The PDF sender and header use the branch; the legal footer and XML postal address remain the seller’s. The XML contact uses the branch name and falls back to the seller contact for a missing branch phone or email. The seller’s electronic address stays unchanged; a branch email fills it only when missing. An active recurring schedule prevents archiving, and any document or recurring template prevents deletion.

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`	Number already used by another document in this company	`code: "NUMBER_TAKEN"`
`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

Multiple sellers (Rechnungssteller)

Branches (Filialen)

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

​Multiple sellers (Rechnungssteller)

​Branches (Filialen)

​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

Multiple sellers (Rechnungssteller)

Branches (Filialen)

Tax treatment

Errors you will meet

Getting paid

Mahnwesen

Linking a document to the rest of meetergo

Products, recurring invoices and export

Related