Mollie metadata
tillor namespace on Mollie payments for linking, groups and bookkeeping
Last updated on
Mollie stores metadata with every payment. Tillor reads and writes fields in the tillor namespace. Link in the app: Mollie.
Three kinds:
- Link metadata - Tillor writes back to Mollie so the payment can be recognised
- Ingestion hints - you set them when creating the Mollie payment
- Direct bookkeeping metadata - bypasses Tillor and goes straight to the bookkeeping
Link metadata
{
"tillor": {
"paymentId": "clx123...",
"invoiceId": "clx456...",
"customerId": "clx789...",
"paymentGroupId": "clxgrp..."
}
}Tillor writes paymentId, invoiceId, customerId and paymentGroupId to Mollie as soon as a payment is attached to an invoice, a customer or a payment group. Existing non-Tillor metadata is left in place.
| Field | Description |
|---|---|
paymentId | Tillor payment |
invoiceId | Tillor invoice |
customerId | Tillor customer |
paymentGroupId | Payment group, even if that group is not yet attached to an invoice |
Ingestion hint: descriptionSuffix
You set this yourself when creating the Mollie payment. Tillor uses it for the payment description as soon as there is an invoice link.
{
"tillor": {
"descriptionSuffix": "Parkeerplaats P1"
}
}Format in Tillor: INV/XXXX/XXXX - {suffix}.
Ingestion hints for payment groups
Handy for POS shifts or activities: bundle several payments before you book an invoice.
{
"tillor": {
"paymentGroupName": "Yoga sunrise - Lake Como",
"paymentGroupExternalId": "act_42"
}
}One of the two fields is enough. Using both is better if the label may change but the ID stays stable.
| Field | Description |
|---|---|
paymentGroupName | Visible label in Tillor. Matches existing open groups by name, or becomes the label of a new group |
paymentGroupExternalId | Stable key from your system. Matches on this instead of on name; the label follows paymentGroupName |
- Tillor looks for an open group with this external ID (or, without an ID, with this name).
- No match? A new open group is created. Its name is
paymentGroupName, otherwisepaymentGroupExternalId. - The payment joins the group as soon as it is paid in Tillor.
- Groups that are already attached to an invoice are not reused.
Were the hints not yet on the Mollie payment when Tillor first saw the payment? The group is still filled once the payment is paid, is not attached to an invoice and is not yet in a group. This happens at the next synchronisation or on an incoming Mollie notification.
When to use?
Pre-tag every Mollie payment from your POS. The group appears under Administration > Payments, section Payment groups.
Do not combine with invoiceId
A grouped payment cannot be attached to an invoice on its own. If you send both group hints and invoiceId, the group wins.
Direct bookkeeping metadata (tillor.bookkeeping)
Unknown Mollie payments go to suspense account 499000 by default. With tillor.bookkeeping, Tillor books them to the specified customer:
{
"tillor": {
"bookkeeping": {
"customerCode": "100001",
"documentType": "INV",
"department": "a",
"fiscalYear": "2026",
"documentNumber": "00042"
}
}
}| Field | Description |
|---|---|
customerCode | Customer code in the bookkeeping - required |
documentType | E.g. INV, UF |
department | Department |
fiscalYear | Financial year |
documentNumber | Document number |
If bookkeeping is present, the payment does not come in as a regular Tillor payment. The metadata is used when building the bookkeeping report.