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, and for tax forms and the 1099-NEC,
Tax forms and 1099s.