Handovers
Overview
A released billing preview is handed over to its target: to your own invoicing, which turns it into an invoice, or to lexoffice. This page is the log of those handovers — one row per handover with target, result, number of attempts and the reason if it did not work.
Where a preview goes is decided in a fixed order:
- the target per customer, if one is stored for this customer,
- otherwise the system setting
finance.billing.handoffTarget, - otherwise lexoffice.
If the resulting target is not available — for instance because your own invoicing is not installed or switched off — the handover goes to lexoffice.
The page sits in the menu as a sub-item of Billing.
Core tasks
Find failures. Errors only above the list shows the handovers that need to be retried. The reason is shown in the Result column below the status (Open, Handed over, Failed). Go to billing run on the row opens the related preview.
Hand over again. The retry icon on a row that did not succeed opens Retry handover. The target can be changed there — for instance when lexoffice is unreachable and the invoice should be created in your own invoicing instead. A successful handover is never retried; that would produce a second document.
Targets per customer. Targets per customer makes a single customer be billed differently from the rest. There is one entry per customer; a second one updates the existing entry. The bin icon removes the exception — the system setting then applies to the customer again.
Fields in detail
Retry handover
| Field | Required | Values / format | What it does |
|---|---|---|---|
Target target | no | Own invoicing or lexoffice | Where the handover should go now. Leave it unchanged to keep the current target. A target that is not available is rejected with a message. |
Handover target per customer
| Field | Required | Values / format | What it does |
|---|---|---|---|
Customer customerId | yes | existing customer | Which customer the exception applies to. |
Target target | yes | Own invoicing or lexoffice | Where this customer's previews go. If the target is not available, lexoffice applies to them. |
Settings & permissions
- Module
module.finance. - View:
finance.billing.view. Retry:finance.lexoffice.syncor
finance.recurring.manage. Targets per customer: finance.recurring.manage.
- Default for all customers: the system setting
finance.billing.handoffTargetwithinvoicing
(own invoicing) or lexoffice, maintained under System. Without an entry, lexoffice applies.
- API:
GET /api/v1/billing-handoffs(filterstatus:pending,done,error; plus
target, customerId, brandId, previewUlid), POST /api/v1/billing-handoffs/{ulid}/retry with an optional target, /api/v1/billing-handoff-targets for the targets per customer.
FAQ & troubleshooting
"This handover already succeeded and is not retried." The row reads Handed over. A second attempt would create a second document — which is why it is blocked.
"The handover target … is not available (module not installed or disabled)." Choose the other target when retrying, or have your own invoicing activated.
A customer ends up in lexoffice although own invoicing is configured. Either your own invoicing is not available, or Targets per customer holds lexoffice for this customer.
The list is empty. No preview has been handed over yet.