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.
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.1
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}.2
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.3
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
Onlybuyer.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.
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.
2. Finalize
Without
profile, the format is the buyer’s eInvoiceFormat, then the
seller’s eInvoiceFormat setting, then the seller country’s default: a
Belgian seller sends peppol-bis-3 when the buyer has a Peppol endpoint
(explicit or derivable from its enterprise or VAT number), and
zugferd-en16931 otherwise. Every other country defaults to
zugferd-en16931. Credit notes and cancellations keep the format of the
invoice they correct. meetergo does not send documents over the Peppol network
itself; hand the XML from step 3 to your access point.
If your billing system reserves numbers centrally, supply one at finalize:
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. Credit notes and cancellations take number the
same way: in the body of POST /invoicing/credit-notes/{id}/issue, of
POST /invoicing/documents/{id}/cancel, and of the finalize of a standalone
cancellation. With number, issuing needs no number range for that kind, and
/cancel needs none at all. Creating a credit note from a meetergo invoice with
/credit-note still checks that the seller has a credit-note range.
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 with503and the document stays a draft. - PDF and XML stored,
statusbecomesfinalized.
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
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.
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:
[] to disable default copies. The sent audit event records the actual
to, cc and bcc lists.
Reading documents back
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
Corrections without a meetergo invoice
Credit notes, cancellations and follow-up invoices can refer to an invoice that was never issued in meetergo, for example one from your previous system. Send its number and date asprecedingInvoice on the draft. They are written to the e-invoice as BG-3 (BT-25, BT-26) and printed under the title of the PDF.
- Credit notes and cancellations accept your own
numberlike invoices; without it they take the next number from the seller’s range. - A cancellation without
precedingInvoiceor with a total of zero or more is rejected with400. - For an invoice issued in meetergo, use
POST /invoicing/documents/{id}/credit-noteor/cancel, which also settle it. A credit note or cancellation whoseprecedingInvoice.numberis one of your meetergo invoices is rejected, as isprecedingInvoiceon a credit note created from an invoice. Offers cannot carry it. precedingInvoice.issueDatemust not be after the document’s own issue date.precedingInvoiceis optional, andnullremoves it from a draft.- Credit notes are issued as ZUGFeRD, or in the profile of the meetergo invoice they correct. Cancellations and invoices accept
profileat finalize.
Supporting documents
Invoices, credit notes and cancellations can carry supporting documents such as a Leistungsnachweis (EN 16931 BG-24). Add each one to the draft:- Allowed types:
application/pdf,image/png,image/jpeg,text/csv,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet(xlsx) andapplication/vnd.oasis.opendocument.spreadsheet(ods). - At most 10 files and 2 MB in total per document, because every file travels in the PDF, in the XML and in the invoice email.
- The pages of a PDF are appended to the document PDF, in the preview and in the issued document. Other types are embedded in the XML only.
- A PDF must be convertible to PDF/A, which every ZUGFeRD PDF is. A file that is not is refused with
400when you add it; export it as PDF/A, or print it to a new PDF. - The file is checked: content that does not match its type, an unreadable PDF or a virus is refused with
400. GET /invoicing/documents/{id}lists the attachments underattachments, without the file content.DELETE /invoicing/documents/{id}/attachments/{attachmentId}removes one.- Attachments change only on a draft and are frozen with the document at finalize. Duplicating a document does not copy them.
POST /invoicing/documents/{id}/cancelcreates and issues the Storno in one call, so it takes the same entries asattachmentsin its body.
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 owndefaultCurrency 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. UseGET 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
SettaxTreatment 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.
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
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:
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}.
SEPA direct debit
When you collect the invoice yourself by direct debit, send the mandate with the draft:59 with the mandate reference (BT-89), your
creditor identifier (BT-90) and the debited IBAN (BT-91) instead of the credit
transfer. The PDF announces the debit with the masked IBAN, the mandate
reference and the creditor identifier, and shows no transfer request and no
GiroCode. Your bank details stay in the footer.
- Invoices in EUR only. Credit notes, cancellations and offers are refused.
- All three fields are required. The creditor identifier and the IBAN are checked; spaces are removed.
- meetergo does not submit the debit to your bank. Record the payment as above once it is collected.
"paymentMeans": nullor{"code": "58"}switches the draft back to a credit transfer.
Payment wording on the PDF
Bank details stay in the seller settings and in the e-invoice either way.
Mahnwesen
Configure reminder levels once, inPUT /invoicing/settings:
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.
Linking a document to the rest of meetergo
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
Related
- E-invoice fields
- Contacts
- CRM deal to invoice
- Every request and response schema: API Reference → Invoicing