> ## Documentation Index
> Fetch the complete documentation index at: https://developer.meetergo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoicing

> Create EN 16931 e-invoices (ZUGFeRD or XRechnung) from your own system, fetch the finished PDF and XML, and track payment

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](/developer-docs/core-concepts/invoicing-fields)
page.

<Note>
  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.
</Note>

## Authentication

Use a [personal access token](/developer-docs/personal-access-tokens) 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.`

```bash theme={null}
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.

<Steps>
  <Step title="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}`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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`.
  </Step>
</Steps>

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

```bash theme={null}
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.

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

### 2. Finalize

```bash theme={null}
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:

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

The response is the finalized document:

```json theme={null}
{
  "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

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

```json theme={null}
{ "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.

<Note>
  **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.
</Note>

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

```bash theme={null}
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}`.

<Warning>
  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.
</Warning>

## Mahnwesen

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

```json theme={null}
{
  "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](/developer-docs/core-concepts/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. |

## Related

* [E-invoice fields](/developer-docs/core-concepts/invoicing-fields)
* [Contacts](/developer-docs/core-concepts/contacts)
* [CRM deal to invoice](/developer-docs/recipes/crm-deal-to-invoice)
* Every request and response schema: API Reference → Invoicing


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.