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

> Offers, invoices, payments and Mahnwesen

Invoicing turns work into money: draft an offer or an invoice, finalize it into a
numbered e-invoice, send it, take payment, and chase what stays unpaid. Documents
can be linked to a CRM contact, a deal and a booking, so an invoice always knows
what it was for.

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

## The document lifecycle

This is the part that trips people up: **creating a document does not produce an
invoice anyone can pay.** There are three distinct calls.

<Steps>
  <Step title="Create a draft">
    `POST /invoicing/documents` returns a draft. It has no number, no PDF and no
    payment link, and you can still change everything on it.
  </Step>

  <Step title="Finalize it">
    `POST /invoicing/documents/{id}/finalize` allocates the next number from your
    number range, freezes an EN 16931 record of the document, and renders the PDF
    and the e-invoice XML. After this the document is immutable — corrections go
    through a credit note or a cancellation, which is what the law expects.
  </Step>

  <Step title="Send it">
    `POST /invoicing/documents/{id}/send` emails the PDF and XML to the buyer,
    with a payment link when a payment provider is connected.
  </Step>
</Steps>

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.

```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",
    "buyer": {
      "name": "Anna Müller",
      "addressLine1": "Brühlweg 20",
      "postalCode": "4132",
      "city": "Muttenz",
      "countryCode": "CH",
      "email": "anna.mueller@example.com"
    },
    "lines": [
      { "name": "Manual therapy, 60 min", "quantity": 1, "unitPrice": 95 }
    ],
    "contactId": "the-crm-contact-uuid",
    "dealId": "the-deal-uuid"
  }'
```

## 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.                                                                                         |
| `credit_note`        | Gutschrift, correcting an invoice.                                                                             |
| `cancellation`       | Storno, voiding an invoice in full.                                                                            |

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

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

## Tax treatment

Set `taxTreatment` on the document when the default German standard rate does not
apply:

`standard`, `tax_free_de`, `reverse_charge_13b`, `reverse_charge_18b`,
`intra_community`, `oss`, `export`, `out_of_scope`.

Per line you can also set `taxCategory` and `taxRate`.

## 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 document has one; a draft has none
yet, and the endpoint returns `{ "url": null }` until you finalize it.

Whether the buyer can pay *there* is a separate question: the page offers card,
PayPal and Mollie only for the providers you have connected, the money moves on
your own account, and the payment is recorded against the invoice automatically
through the provider's webhook. With no provider connected the page still shows
the invoice, and `send` leaves the payment link out of the email.

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

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

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

* [Contacts](/developer-docs/core-concepts/contacts)
* [CRM deal to invoice](/developer-docs/recipes/crm-deal-to-invoice)