Developer Credit Notes
Overview
Lumio pays extension developers their revenue share. Every payout is documented by a self-billed credit note (Gutschrift, § 14 Abs. 2 S. 2 UStG): Lumio, the recipient of the developer's service, issues the invoice on the developer's behalf. The note is issued in the same database transaction as the payout, so no payout exists without its note, and a note that cannot be issued books no payout.
The developer finds every note and cancellation under Extensions → Payouts (/dashboard/extensions/payouts, see Developer Payouts), gets each one by e-mail with the PDF attached, and can download the PDF at any time. Operators see all notes on the admin page /credit-notes, including those of deleted developer profiles, and cancel them there (see Credit Notes).
What a note contains
| Part | Content |
|---|---|
| Number | GS-<year>-<6 digits>, e.g. GS-2026-000001. One gap-free range per calendar year (Europe/Berlin), shared by notes and cancellations. The prefix comes from [billing.credit_notes] number_prefix. |
| Issuer | Lumio's name, address and VAT ID from [billing.issuer], copied onto the note at issue. |
| Supplier | The developer's verified verification: name, company, address, country, Steuernummer and/or USt-IdNr., copied at issue. A later change of the verification never changes an issued note. |
| Service | One line per service, each with its own net amount (see Lines). The developer's own revenue share is "Revenue share for the sale of extensions via the Lumio Marketplace" with the service period. The period starts where the developer's last effective note ended (or when the profile was created) and ends on the issue date. |
| Amounts | Net, VAT and gross in cents, EUR only. The payout amount is the gross amount. |
| VAT | Derived from the tax details of the verification (below), printed as an amount or as the matching legal sentence. |
Lines
A note has one line for the profile's own revenue share. When an operator has settled a released balance onto the profile, the settled amount was earned through an earlier, deleted developer profile, so it gets its own line with its own service date (Legal decision ZAF-2843):
| Order | Line | Net amount |
|---|---|---|
| 1 | "Umsatzbeteiligung aus dem Verkauf von Erweiterungen über den Lumio Marketplace, erzielt über ein früheres Entwicklerprofil (Guthaben freigegeben am D) / Revenue share for the sale of extensions via the Lumio Marketplace, earned through an earlier developer profile (balance released on D)", then "Leistungszeitraum bis / Service period until D". D is the release date (Europe/Berlin). | The part of the settled amount paid out with this payout |
| 2 | The own revenue share with its service period, as above | The rest of the payout's net amount; the line is left out when that is 0 |
- Split. A payout first uses the settled amounts that are not yet on a note, oldest settlement first, up to the payout's net amount. A rest moves to the next note as a line 1 again, with the same
D. Several settled balances give one line 1 each. - Period. Line 1 does not move the service period. A note with only line 1 has the issue date as its period, and the next note's period starts there.
- Failed payout. The cancellation negates both lines, and the settled amount is on the next note again. An objection without a re-issue does not give it back, because the money stays paid out. A corrected re-issue copies line 1 unchanged.
- The note names nothing of the earlier profile: no developer ID, name, claim code or support reference. VAT is one rate over the whole note.
How much of each settled balance a payout took is stored in developer_released_balance_allocations (one row per settled balance and payout, two IDs and an amount). The row is deleted with the payout or the settled balance, and a failed payout deletes it. A settled balance is kept past its 8 years while part of it is not paid out yet.
The PDF is printed in German and English and is the document of record: it is rendered once, stored write-once under billing/credit-notes/<year>/<id>.pdf with its SHA-256, and checked against that hash every time it is served.
VAT treatment
The developer enters the tax details in the verification form and later in the Tax details card on the verification page (also after the verification was approved; the change does not reset the review):
| Developer | Needs | Treatment on the note |
|---|---|---|
| Germany, small business (§ 19 UStG) | Steuernummer or USt-IdNr., "small business: yes" | No VAT; "Steuerfreie Leistung als Kleinunternehmer nach § 19 Abs. 1 UStG." |
| Germany, charges VAT | Steuernummer or USt-IdNr., "small business: no" | 19 % VAT on top of the revenue share: the balance is debited by the net amount, the payout is net + VAT |
| Other EU country | USt-IdNr. | No VAT; "Steuerschuldnerschaft des Leistungsempfängers" (§ 13b UStG) |
| Outside the EU | — | No VAT; same reverse-charge sentence |
While the details are incomplete, a payout request answers TAX_DETAILS_REQUIRED and the monthly cycle skips the developer (counted as refused); nothing is booked and no number is used. Without a complete [billing.issuer] config no note and so no payout can be issued at all (CREDIT_NOTE_ISSUER_NOT_CONFIGURED).
The VAT treatment of foreign developers (individuals without business status, EU developers without a VAT ID, a VIES check) is reviewed by a tax adviser before real payouts start. The wording of the printed sentences is a draft by Legal.
Cancellation and objection
| Event | What happens |
|---|---|
| A payout fails (Stripe or PayPal error, PayPal "item failed" webhook) | In one transaction: the payout becomes failed, the net amount goes back to the balance, and a cancellation note with its own number and the negated amounts cancels the payout's note. A replayed webhook changes nothing. The next payout's note covers the period again. |
| The developer objects to a note (§ 14 Abs. 2 S. 3 UStG) | An operator records it with the date it arrived (cancelCreditNote / POST /v1/admin/credit-notes/{id}/cancel, reason developer_objection); optionally a corrected note is re-issued for the same payout and period. |
| A note has wrong data | An operator cancels it with reason correction and re-issues it from the corrected verification. A re-issue whose total would differ from the paid amount is refused (CREDIT_NOTE_AMOUNT_MISMATCH). |
Every operator cancellation emits the audit event system:developer_credit_note_cancelled. An issued note is never edited: a database trigger rejects every change except recording the cancellation, storing the PDF once and recording the delivery.
Delivery
After the payout transaction commits, the credit note worker renders and stores the PDF (every minute) and mails it to the developer's e-mail address in their e-mail language, German or English, with the PDF attached. A successful mail sets delivered_at. A failed mail is retried hourly for 14 days; notes whose PDF is pending for more than an hour or that are undelivered after a day are logged as an operator warning. The worker needs file storage ([storage]) and an enabled [email] provider.
Retention
Notes are kept 8 full calendar years after the year of issue (§ 14b Abs. 1 UStG, § 147 AO): a note from 2026 is deleted from 1 January 2035, 00:00 Europe/Berlin. A note and its cancellation are deleted together, once both are past that date. The PDF is queued for deletion in the same step. Deleting a developer profile or a payout keeps the notes (they are detached), and a GDPR erasure does not shorten the period. The daily step of the account security worker runs the purge.
Configuration
| Key | ENV | Default | Meaning |
|---|---|---|---|
billing.issuer.name | LUMIO__BILLING__ISSUER__NAME | (empty) | Lumio's legal name on the note |
billing.issuer.address | LUMIO__BILLING__ISSUER__ADDRESS | (empty) | Postal address, one line per address line |
billing.issuer.vat_id | LUMIO__BILLING__ISSUER__VAT_ID | (empty) | USt-IdNr. (or Steuernummer) on the note |
billing.credit_notes.number_prefix | LUMIO__BILLING__CREDIT_NOTES__NUMBER_PREFIX | GS | Number prefix; must not collide with Stripe's invoice numbers |
billing.credit_notes.domestic_vat_rate_bp | LUMIO__BILLING__CREDIT_NOTES__DOMESTIC_VAT_RATE_BP | 1900 | VAT for German standard-rated developers, in basis points |
With an empty issuer field the API logs a warning at start-up and refuses every payout.
API
- Developer:
developerCreditNotes,developerCreditNote(GraphQL) /GET /v1/developer/credit-notes[/{id}[/pdf]](REST);updateDeveloperTaxDetails/PUT /v1/developer/verification/tax-details. - Operators:
adminCreditNotes,adminCreditNote,cancelCreditNote/GET /v1/admin/credit-notes[/{id}[/pdf]],POST /v1/admin/credit-notes/{id}/cancel(billing:read/billing:edit).