# Self-billing invoices Issue an invoice in each EU or UK business promoter's name for every payout, take their own invoice from everyone else, and give every payout a statement. Under EU and UK VAT rules, a business that is paid for a service gives its customer an invoice. When your promoters are businesses in the EU or the UK, that means an invoice for every payout. **Self-billing** turns it around: you issue the invoice in the promoter's name, with their agreement, so nobody has to chase paperwork. Everyone else can upload their own invoice, and every payout has a statement. **BoltClaw prepares these documents; it does not give tax advice or file anything for you.** The self-billing agreement shown to promoters today is a placeholder, marked as one, until the final wording arrives: ask your accountant before you rely on it, and about the VAT rules that apply to your business. ## Who it is for | Promoter | What they get for each payout | |---|---| | A business in the EU or the UK with a VAT number, who accepted your self-billing agreement | A **self-billed invoice** you issue in their name | | Anyone else, when your program asks for one | Their **own invoice**, which they upload: the payout waits for it | | Everyone | A **payout statement**: who paid whom, how much, when and for which period | Turn self-billing on for a program on its **Tax** tab, or with `PATCH /v1/referrals/programs/{id}/tax` and `"self_billing": true`. It needs your own invoicing details first (your legal name, address, country and VAT number, entered in the dashboard); until they are complete the answer is `409 CONFLICT`. Asking every other promoter for their own invoice is `"invoice_required": true` on the same call. A promoter who self-bills never waits for an invoice of their own. ## The agreement A promoter accepts the agreement for one program in their dashboard, after a recent sign-in, with their business's legal name, address, country and VAT number. The version they accepted is recorded. In plain words, it says: - you issue the invoices for their referral commissions in their name, for every payout under the program, and they do not issue their own while it stands; - each invoice is accepted unless they dispute it within **14 days** of receiving it; - they tell you within 14 days when their VAT number or other details change, by updating them in their dashboard; - either side may end it at any time, and invoices already issued stay valid. ## What each invoice says A self-billed invoice is issued **when the payout is paid**, however it was paid: through your payout provider, by your own payout system, or marked paid by hand. It carries: - the supplier (the promoter's legal name, address and VAT number) and the customer (yours); - the date, its number, the period it covers and the words "Referral commissions"; - the net amount, the VAT rate and amount, or **"Reverse charge"**; - the words **"Self-billing"**, and the currency. **Numbering.** Each promoter has one series with you, without gaps, in the form `SB1A2B3C4D-00042`. Numbers are taken in the database under a lock, so two payouts paid at the same moment never share or skip one. **VAT.** The rule is decided when the invoice is issued: | Promoter and you | `vat_treatment` | On the invoice | |---|---|---| | In the same country | `domestic` | Your own domestic VAT rate, which you enter once; the payout is the gross amount, VAT included | | In different countries, and you are in the EU or the UK | `reverse_charge` | No VAT, and "Reverse charge": you account for the VAT | | You are outside the EU and the UK | `outside_scope` | No VAT, and a sentence saying the supply is outside their scope | For a UK promoter charging UK VAT, the invoice also says "The VAT shown is your output tax due to HMRC". If your domestic rate is not set when a promoter in your own country is paid, the invoice waits: set it, then issue it with `POST /v1/referrals/payouts/{id}/invoice`. The same call issues any paid payout's missing invoice, and answers the existing one when there is one. ## Acceptance and disputes An invoice is `issued` and accepted 14 days later (`accept_by`) unless the promoter accepts it sooner or disputes it first. A dispute names a reason (their details are wrong, the amount is wrong, the VAT is wrong, they did not make this supply, or something else) with an optional note, pauses the invoice and tells you with the `referral.invoice.disputed` event. After the 14 days a promoter cannot dispute it in BoltClaw and is told to contact you. To settle a dispute, fix what is wrong (the promoter corrects their own details; you correct yours), then issue a **corrected invoice**: on the payout in the dashboard, or with `POST /v1/referrals/invoices/{id}/reissue`. The disputed invoice becomes `void`, and the new one takes the next number in the promoter's series, uses the details as they are now, and starts its own 14 days. Only a disputed self-billed invoice can be replaced. ## Uploaded invoices A promoter who does not self-bill uploads their own invoice for a payout from their dashboard: one PDF of at most 5 MB, checked to be a PDF by its first bytes, stored sealed and keyed by the payout. A new upload replaces the last one. When the program asks for an invoice, the payout waits for it, in a batch and in an export file alike; **Ready to pay** shows `wait: "invoice"`. ## Reading invoices and statements `GET /v1/referrals/payouts/{id}/invoices` lists a payout's invoices, newest first, with their kind, status, number, amounts, VAT treatment, dates and any dispute. The PDFs are read through a link good for ten minutes and one download: `POST /v1/referrals/invoices/{id}/link` for an invoice (it names a promoter's business, so it needs the **Payouts** permission and every link is recorded in the activity log), and `POST /v1/referrals/payouts/{id}/statement-link` for the payout's statement. Treat a link as a secret; a replay of the same `Idempotency-Key` answers `url: null`, so ask again for a new one. Promoters download their own invoices and statements from their dashboard. ## Events | `event` | When | |---|---| | `referral.invoice.issued` | A self-billed invoice was issued (`kind: "self_billed"`, with `replaces` for a corrected one), or a promoter uploaded their own (`kind: "uploaded"`) | | `referral.invoice.disputed` | A promoter disputed a self-billed invoice within its 14 days, with the `reason` code | Each carries `program_id`, `payout_id`, `partner_id` and `invoice_id`, never a name, an address or a VAT number. See [Webhooks](https://boltclaw.ai/docs/webhooks), and for tax forms and the 1099-NEC, [Tax forms and 1099s](https://boltclaw.ai/docs/referral-tax).