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 — failed and given up. The reason is shown in the Result column below the status (Open, Handed over, Failed, Given up). Go to billing run on the row opens the related preview.
Automatic retry. If a handover fails — lexoffice unreachable, target briefly switched off — the system tries again by itself, with growing gaps: after 15 minutes, then after 30 minutes, 1, 2 and 4 hours (at most 12 hours). When the next attempt comes is shown below the status (Next attempt …). After the sixth failed attempt the system gives up: the row shows Given up, and everyone who may hand over in the billing's brand gets a notification that leads straight to the given-up handovers. If the preview is reopened for editing in the meantime, the automatic retry ends. To react to giving up — for instance with a task for bookkeeping — use the trigger Handover given up in an automation.
Hand over again. The retry icon on a row that did not succeed — including a given-up one — 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.
- Retry run: every 15 minutes in the background; six attempts in total, first gap 15 minutes and
then twice as long each time, at most 12 hours. The notification goes to whoever holds finance.lexoffice.sync or finance.recurring.manage in the billing's brand.
- API:
GET /api/v1/billing-handoffs(filterstatus:pending,done,error,gave_up,
several separated by commas, e.g. error,gave_up; field nextAttemptAt = next automatic attempt; 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.
**A row shows Given up.** Six attempts failed, and the system no longer retries by itself. Check the reason in the Result column, fix it and retry manually — to the other target if needed.
The list is empty. No preview has been handed over yet.