Tax: VAT invoices and 1099s

Referalli issues the tax paperwork for the commissions you pay. Every payout comes with a self-billed invoice, which you issue on your partner's behalf. US partners also get a 1099-NEC, filed through a filing provider you connect.

Your legal details

Both documents need your legal identity:

curl -X PUT https://referalli.com/v1/org/tax-profile \
  -H "Authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{
    "legalName": "Acme GmbH",
    "address": "Hauptstr. 1, 10115 Berlin",
    "country": "DE",
    "vatId": "DE123456789",
    "domesticVatBps": 1900,
    "viesCheck": true
  }'

Every field is optional, and a call changes only the fields it sends. GET /v1/org/tax-profile returns them. Both require the owner, admin or finance role.

Self-billed invoices

Every payout carries an invoice that you issue for the partner. It holds:

• a number that is sequential per merchant per year (SBI-2026-1, SBI-2026-2, …), with no gaps and no duplicates, even when runs are created at the same time;

• the supplier (the partner: name and address from their tax form, plus their VAT number) and the customer (you, from your tax profile);

• the commission lines, the net amount, any VAT, and the total;

• the VAT treatment and the matching wording.

GET /v1/payouts/{id}/invoice returns the invoice as JSON. Add ?format=html for a printable page: use your browser's "Save as PDF". Partners get the same page from GET /v1/partner/payouts/{id}/invoice?format=html. Invoices issued before these fields existed still render.

Partner VAT numbers

A partner adds their EU VAT number in the portal (PUT /v1/partner/orgs/{orgId}/vat with {"vatId": "FR…"}), or you set it with PUT /v1/partners/{id}/vat. Send null to remove it. A number that doesn't match its country's format returns 400. With viesCheck on, one that VIES doesn't list as registered also returns 400, and an accepted one records vatVerifiedAt.

The self-billing agreement

Self-billing needs the partner's prior agreement. A VAT-registered partner accepts it once per merchant, in the portal or with POST /v1/partner/orgs/{orgId}/self-billing and {"accept": true}. GET on the same path returns the status and the current agreement version. Until a VAT-registered partner accepts, payout runs skip them with self_billing_agreement_missing. Their balance waits; nothing is lost. Partners without a VAT number aren't affected. Each invoice records the agreement version and the date it was accepted.

1099-NEC filing

US persons (partners with a W-9 on file) who were paid $600 or more in a calendar year get a Form 1099-NEC. Referalli works out who needs one, files the forms through your filing provider, and delivers each partner's Copy B.

Connect a filing provider

Filing uses your own provider account (BYOK); Referalli holds no filing credentials of its own.

curl -X PUT https://referalli.com/v1/org/tax-filing \
  -H "Authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"provider": "test"}'

Connecting a provider requires the owner or admin role.

Review, then file

GET /v1/tax/1099/preview?year=2026 lists each recipient with Box 1 (nonemployee compensation, in USD cents) and anything that blocks filing them:

payerReady is false until your legal details include your legal name, EIN and address; payerIssues lists what's missing.

curl -X POST https://referalli.com/v1/tax/1099/filings \
  -H "Authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"year": 2026}'

This files every ready recipient in one batch and returns the filing with its status (submitting, submitted, accepted or rejected) and its documents. A partner is never filed twice for a year, even if two requests arrive at the same time. GET /v1/tax/1099/filings?year=2026 lists filings. For a provider that accepts forms later, POST /v1/tax/1099/filings/{id}/refresh checks the status again.

Filing is safe to interrupt. Referalli records the filing (submitting) and its documents (pending) before it calls your provider, and sends the filing's id as the provider's idempotency key. If the call fails or its answer is lost, the filing stays submitting with the error shown, and an hourly sweep (or refresh) resends the same batch with the same key, so the provider returns its first result instead of filing again. A document that's pending counts as filed, so it can't be filed twice in the meantime.

Delivery to partners

When a form is accepted, Copy B is delivered: the partner finds it under Payouts → Tax forms in the portal (GET /v1/partner/tax-documents, then GET /v1/partner/tax-documents/{id} for the printable form), gets a notification, and, where the provider supports it, an email copy. Copy B shows only the last four digits of the partner's TIN. A tax.form_delivered event is published for each one.

Corrections

If a partner's total for the year changes after filing (a late payout, say), file a corrected form: POST /v1/tax/1099/documents/{id}/correct. It refiles with the current total and marks the form CORRECTED. The original stays on record, and the correction points to it with correctionOf. When the amount on file already matches, the call returns 409.

Filing and corrections require the owner, admin or finance role, and every filing is audited.