Billing & VAT¶

Revel handles VAT calculations in-house for both ticket sales and platform fees, generates monthly platform fee invoices with PDF rendering, and validates EU VAT IDs against the European Commission's VIES system.

Architecture Overview¶

flowchart TD
    subgraph Checkout["Ticket Purchase (Stripe)"]
        Stripe[Stripe Service] -->|"calculates at purchase time"| VATCalc[VAT Service]
        VATCalc --> Payment[(Payment record)]
    end

    subgraph Monthly["Monthly Invoice Generation (Celery Beat)"]
        Beat[Celery Beat] -->|"1st of month"| GenTask[generate_monthly_invoices_task]
        GenTask --> InvSvc[Invoice Service]
        InvSvc -->|"aggregates payments"| DB[(Payment table)]
        InvSvc -->|"creates"| Invoice[(PlatformFeeInvoice)]
        InvSvc -->|"renders PDF"| WP[WeasyPrint]
        GenTask -->|"per invoice"| EmailTask[send_invoice_email_task]
    end

    subgraph Validation["VAT ID Validation"]
        Controller[VAT Controller] -->|"PUT /vat-id"| VIES[VIES REST API]
        Beat2[Celery Beat] -->|"15th of month"| RevalTask[revalidate_vat_ids_task]
        RevalTask -->|"per org"| VIES
    end

VAT Calculation¶

VAT is calculated at purchase time and persisted on each Payment record. This snapshot approach means invoices always reflect the VAT rules that were in effect when each payment was made, even if the organization's VAT status changes later.

Service: events.service.vat_service¶

Three core functions handle all VAT math:

Ticket Sale VAT¶

Ticket prices are VAT-inclusive. The VAT breakdown is extracted using:

The effective VAT rate comes from the ticket tier (if overridden) or falls back to the organization's default vat_rate.

Platform Fee VAT¶

Platform fees follow EU B2B rules. The logic in calculate_platform_fee_vat():

Payment Record Fields¶

Each Payment stores the full VAT snapshot:

net_amount, vat_amount, vat_rate              # ticket sale VAT
platform_fee_net, platform_fee_vat,           # platform fee VAT
platform_fee_vat_rate, platform_fee_reverse_charge

Penny-Perfect Distribution¶

For batch purchases (multiple tickets in one Stripe session), distribute_amount_across_items() splits the total platform fee across tickets without rounding drift — extra pennies go to the first item(s), and the sum is guaranteed to match the total exactly.

Series pass checkouts use the same helper three ways: one Stripe session at the pass price is split into per-event Payment shares, platform-fee shares, and platform-fee-VAT shares — each Payment's VAT computed from its own ticket's tier rate.

Subscription Platform Fees¶

Membership subscriptions (memberships & subscriptions) charge the platform fee via Stripe's application_fee_percent on the Subscription — percent-only: Stripe has no fixed-fee mechanism for subscriptions, so Organization.platform_fee_fixed intentionally does not apply (ADR-0013).

• Collection: the percent sent to Stripe is the org's platform_fee_percent grossed up with platform VAT when applicable (percent × (1 + rate/100), capped at 100) — the same fee-plus-VAT-on-top economics as tickets. Reverse-charge and non-EU orgs get the bare percent. The grossed percent is written into the Stripe Subscription at Checkout and resynced when the org's VAT status changes: the events.service.vies_service wrappers (VIES revalidation — including the monthly events.revalidate_vat_ids sweep — VAT ID set/clear, billing-country change) compare the effective percent before/after and, when it moved, queue events.resync_org_subscription_fees, which pushes the current percent onto every non-terminal ONLINE subscription. VAT treatment at time of supply governs, so the live-state decomposition is authoritative and the frozen percent is what gets corrected. Two caveats: schedule-managed subscriptions (pending downgrades) are skipped — Stripe rejects a plain Subscription.modify while a schedule is attached, and releasing the schedule would drop the pending plan change — and admin-side changes to platform_fee_percent itself do not auto-resync. Both are covered by the resync_subscription_fees management command (--dry-run, --org-slug, per-account --sleep rate limiting; partial failures are counted, logged as subscription_fee_resync_failed, and exit non-zero).
• Ledger: each invoice.paid/invoice.payment_failed records the invoice's actual application_fee_amount onto the MembershipPayment row, decomposed into the same platform_fee, platform_fee_net, platform_fee_vat, platform_fee_vat_rate, platform_fee_reverse_charge fields ticket Payment rows carry (b2b_fee_vat_from_gross() — VAT-inclusive decomposition).
• Invoicing: monthly PlatformFeeInvoice generation aggregates fee-bearing MembershipPayment rows alongside ticket Payment rows per (org, currency); total_subscription_payments / total_subscription_revenue carry the subscription side of the stats.
• Scheduled downgrades keep the fee (verified 2026-07-29 against the live test-mode API at pinned version 2026-03-25.dahlia, issue #821): SubscriptionSchedule.create(from_subscription=...) copies the subscription's application_fee_percent into the schedule's default_settings; the phases rewrite in _downgrade_online_subscription leaves default_settings untouched, so its fee-less hand-built phases inherit the fee, and the subscription retains its own application_fee_percent for after the release. Renewals under and after a scheduled downgrade therefore still collect the platform fee. Canary: events/tests/test_service/test_stripe_schedule_fee_integration.py (run with pytest -m integration) re-verifies this end-to-end — rerun it when bumping STRIPE_API_VERSION.
• Like ticket fees, subscription platform fees are not refunded when a payment is refunded.

VIES Integration¶

Service: events.service.vies_service¶

Validates EU VAT IDs against the European Commission's VIES REST API.

sequenceDiagram
    participant Org as Organization Owner
    participant API as VAT Controller
    participant VIES as VIES REST API

    Org->>API: PUT /vat-id {vat_id: "ATU12345678"}
    API->>API: Validate format (regex)
    API->>API: Save VAT ID (pending validation)
    API->>VIES: POST check-vat-number
    alt VIES available & valid
        VIES-->>API: {valid: true, name, address}
        API->>API: Mark validated, auto-fill billing fields
        API-->>Org: 200 OK (billing info)
    else VIES available & invalid
        VIES-->>API: {valid: false}
        API-->>Org: 400 "VAT ID not valid"
    else VIES unavailable
        VIES-->>API: timeout / error
        API-->>Org: 503 "Saved but pending validation"
    end

Key behaviors:

• validate_and_update_organization() auto-fills vat_country_code from the VAT ID prefix, and billing_name and billing_address from the VIES response (if currently empty)
• On VIES unavailability, the VAT ID is saved as pending and will be validated on the next monthly revalidation cycle
• VIES addresses containing only "---" are ignored

Periodic Revalidation¶

A Celery Beat task (revalidate_vat_ids_task) runs on the 15^th of each month, dispatching one revalidate_single_vat_id_task per organization. Each sub-task retries independently with exponential backoff (60s to 1h, max 5 retries).

Invoice Generation¶

Service: events.service.invoice_service¶

Monthly platform fee invoices are generated automatically on the 1^st of each month via Celery Beat.

Generation Pipeline¶

1. Aggregate all succeeded payments for the period — ticket Payment and fee-bearing MembershipPayment rows — grouped by (organization, currency)
2. Idempotency check — skip if an invoice already exists for (org, period_start, currency)
3. Generate invoice number inside transaction.atomic() with SELECT FOR UPDATE
4. Create invoice with snapshots of org and platform business details
5. Render PDF via WeasyPrint (outside the transaction to avoid long locks)
6. Dispatch email as a separate Celery task per invoice

Invoice Numbering¶

Format: RVL-{YEAR}-{SEQUENCE:06d} (e.g., RVL-2026-000001)

Credit notes: RVL-CN-{YEAR}-{SEQUENCE:06d}

Sequences are year-scoped and independent between invoices and credit notes.

Race condition protection — 3 layers:

Invoice Model: Snapshot Design¶

PlatformFeeInvoice snapshots all org and platform details at generation time:

org_name, org_vat_id, org_vat_country, org_address     # org snapshot
platform_business_name, platform_business_address,      # platform snapshot
platform_vat_id

This ensures invoices remain accurate even if the organization is deleted or updates its billing details after the invoice is generated. The organization FK uses SET_NULL — the invoice survives org deletion.

PDF Rendering¶

Invoices are rendered as PDFs using WeasyPrint from the template templates/invoices/platform_fee_invoice.html. The PDF is stored as a ProtectedFileField, served via HMAC-signed URLs (see Protected Files).

Email Delivery¶

Each invoice email is dispatched as a separate Celery task (send_invoice_email_task) with auto-retry (exponential backoff, max 5 retries). Recipients are the org owner + billing email (or contact email fallback). A BCC goes to the platform's platform_invoice_bcc_email if configured. The email subject and body include the invoice currency for clarity in multi-currency organizations.

Organization Billing Fields¶

The Organization model stores:

Ticket Tier VAT Override¶

Each TicketTier has an optional vat_rate field. If set, it overrides the organization default for that tier. This supports scenarios like reduced VAT rates for specific ticket categories.

Platform Billing Settings¶

SiteSettings (django-solo singleton) stores platform-level billing configuration:

Revenue & VAT Reporting¶

Organizers get a financial-reporting suite for their own tax filing, all driven by one tax-precise aggregation engine (events.service.revenue_aggregation) so every view reconciles: the downloadable report rolls it up across events, the org /revenue endpoint groups it by event, and the per-event endpoint filters it to a single event.

Aggregation Engine¶

build_revenue_report_data() (and its live-endpoint projections) performs a single per-row pass over both revenue sources and folds them into buckets keyed by currency and then by VAT rate:

Key behaviors:

• Per currency, per VAT rate — each currency section carries one RateBucket per VAT rate; reverse-charge and 0%-rate rows collapse into a single 0% / reverse-charge bucket.
• Refunds attributed to the period they occurred — a sale and its refund are counted in whichever report period each one falls into (by local date), not lumped onto the sale date. Rate-bucket money is net-of-refunds; refunds are also surfaced separately (refunds_total / refunded_count).
• Net taxable turnover — per currency, the sum of net (sale minus refund) across rate buckets.
• VAT snapshot first — online payments use the persisted net_amount/vat_amount/vat_rate snapshot when present, falling back to calculate_vat_inclusive() at the org rate; offline tickets are always extracted at the org rate.
• Org timezone — sale/refund dates are converted to the org's city timezone before the period window is applied.

Report Bundle (ZIP)¶

POST /organization-admin/{slug}/revenue-report produces a multi-file ZIP built by events.service.revenue_report_service:

• *.xlsx — two sheets: Summary (per currency: one row per VAT rate, a Refunds row, a bold Net-taxable-turnover total) and Transactions (one row per sale/refund line).
• *.pdf — rendered via WeasyPrint: per-VAT-rate table, refunds, and net taxable turnover.

Generation is asynchronous (a FileExport row + Celery task — see Exports for the artifact mechanics). The result is cached: a matching READY export (same org, event, date range, and a content hash over the in-scope rows) is reused unless ?refresh=true is passed.

Scheduled Delivery¶

Orgs can opt into emailed reports via Organization.revenue_report_cadence (NONE / QUARTERLY / MONTHLY, default NONE). A monthly Beat sweep (deliver_scheduled_revenue_reports) computes the just-closed period in the org's own timezone, generates the ZIP, and emails it to the org's billing_email (plus the owner if different). Empty periods are skipped (no email, marker not advanced), and a last_revenue_report_sent_period marker prevents double-sends. QUARTERLY orgs only actually send in Jan/Apr/Jul/Oct; other months no-op.

Per-Event Schema Change¶

API Endpoints¶

Billing-info, VAT-ID, invoice, and credit-note endpoints require organization owner permissions. The revenue & VAT endpoints instead require the manage_organization permission (owner or staff with that grant) — see Revenue Endpoints.

Billing Info¶

VAT ID Management¶

Invoices & Credit Notes¶

Revenue Endpoints¶

These require manage_organization (not owner), and return the data described under Revenue & VAT Reporting.

Attendee Invoicing¶

Revel generates invoices for attendees (buyers) on behalf of organizers (sellers) for online ticket purchases. The organizer is the legal seller; Revel acts as an intermediary. The VAT breakdown is snapshotted at checkout time; for physical events the buyer's billing info feeds the invoice (name, address, verified VAT ID) but never changes the price (#868). Virtual events are the exception — see Per-event place of supply (#869): cross-border EU B2B and non-EU buyers pay net.

Architecture Overview¶

flowchart TD
    subgraph Preview["VAT Preview (pre-checkout)"]
        FE[Frontend] -->|"billing info + cart"| VPEndpoint[VAT Preview Endpoint]
        VPEndpoint -->|"validates VAT ID"| VIESCache[VIES Cache<br>Redis 30min TTL]
        VIESCache -->|"cache miss"| VIES2[VIES REST API]
        VPEndpoint -->|"calculates"| VATSvc[Attendee VAT Service]
        VATSvc -->|"price breakdown"| FE
    end

    subgraph Checkout["Stripe Checkout"]
        FE -->|"billing_info in payload"| BatchSvc[BatchTicketService]
        BatchSvc --> StripeSvc[Stripe Service]
        StripeSvc -->|"adjusted amounts"| Stripe[Stripe Checkout Session]
        StripeSvc -->|"buyer_billing_snapshot"| PaymentRec[(Payment records)]
    end

    subgraph InvoiceGen["Invoice Generation (webhook)"]
        Webhook[checkout.session.completed] -->|"on_commit"| CeleryTask[generate_attendee_invoice_task]
        CeleryTask --> InvSvc[Attendee Invoice Service]
        InvSvc -->|"HYBRID → DRAFT"| DraftInv[(AttendeeInvoice<br>DRAFT)]
        InvSvc -->|"AUTO → ISSUED"| IssuedInv[(AttendeeInvoice<br>ISSUED)]
        IssuedInv -->|"email"| EmailTask[send_email task]
    end

    subgraph Refund["Credit Notes (refund webhook)"]
        RefundWH[charge.refunded] -->|"on_commit"| CNCelery[generate_attendee_credit_note_task]
        CNCelery --> CNSvc[Credit Note Service]
        CNSvc -->|"ISSUED invoice"| CN[(AttendeeInvoiceCreditNote)]
        CNSvc -->|"DRAFT invoice"| Delete[Delete draft]
    end

Invoicing Modes¶

Organizations opt in to attendee invoicing by setting Organization.invoicing_mode:

Prerequisites (same as enabling Stripe ticket sales):

• EU-based (vat_country_code in EU member states)
• VIES-validated VAT ID
• billing_name and billing_address set

Setting to NONE is always allowed.

Attendee VAT at Checkout: Admission Is a Domestic Supply¶

Admission to events is taxed where the event takes place — Art. 53 (B2B) and Art. 54(1) (B2C) of the VAT Directive, with "admission" (including season tickets → series passes) defined by Art. 32 IR 282/2011. Reverse charge (Art. 44/196) never applies to admission, and there is no zero-rated "export of services" for it (#868). Therefore every buyer pays the full gross price at the seller's rate, regardless of country or VAT ID status:

VIES validation still runs at preview/checkout, but only so a verified buyer VAT ID can be printed on B2B invoices — for physical events it never affects the price. The pre-#868 reverse-charge/export branches under-collected VAT; python manage.py report_mischarged_attendee_vat lists the historically affected invoices for review with a tax adviser. Historical invoices re-render exactly as issued (snapshot design).

Per-event place of supply (#869)¶

Place of supply is a per-event fact, not "the org's home country":

• Event.is_virtual (default False) distinguishes physical admission from virtual attendance.
• Event VAT country — explicit Event.vat_country_code override, else derived venue.city.iso2 → event.city.iso2 → org.vat_country_code (Event.effective_vat_country). For physical events it drives the invoice's seller VAT country; when it differs from the org's VAT country, EventDetailSchema.vat_country_mismatch is True so the FE can warn the organizer ("local VAT registration or OSS may be needed — ask your adviser"). Virtual events are supplied from the org's establishment (invoice country = org country).
• Virtual events (Directive (EU) 2022/542): cross-border EU B2B with a validated VAT ID → reverse charge (Art. 44/196, buyer pays net); non-EU buyer → no EU VAT (pays net); EU B2C legally owes the buyer-country rate via OSS — charged at the organizer's rate as an interim treatment, flagged via virtual_b2c_disclaimer on the VAT preview and a tax notice on the invoice.
• Series passes always charge org-rate VAT on gross (admission incl. season tickets, Art. 32 IR 282/2011) — unchanged by is_virtual.

Online tickets never copy Payment.amount into Ticket.price_paid — it stays NULL permanently, and the 1:1 Payment row is authoritative (decision on issue #758; originally motivated by buyer-dependent net charging, kept for its own merits). Every money-bearing reader of an online ticket consults its Payment row (the revenue report aggregates payments directly; the Apple Wallet pass checks ticket.payment before any fallback) — see should_stamp_price_paid in events/service/seating/pricing.py.

Service: events.service.attendee_vat_service¶

VIES Caching¶

validate_vat_id_cached() wraps VIES validation with a Redis cache (30-minute TTL). The preview endpoint validates and caches; the checkout path reuses the cached result. VIES errors are not cached — the error propagates so the frontend can handle the fallback (charge full VAT when VIES is unavailable).

Invoice Generation¶

Triggered by the checkout.session.completed webhook via transaction.on_commit. The service:

1. Finds Payment records by stripe_session_id with status=SUCCEEDED
2. Checks buyer_billing_snapshot is present and org has invoicing_mode != NONE
3. Idempotency: checks inside transaction.atomic() for existing invoice
4. Generates sequential invoice number: {ORG_SLUG}-{YEAR}-{SEQ:06d} (e.g., TECHCONF-2026-000001)
5. Creates AttendeeInvoice with seller/buyer snapshots and line items from Payment data
6. Renders PDF via WeasyPrint (outside the transaction)
7. For AUTO mode: sends email immediately

Invoice Numbering¶

Per-org sequential numbering with the same 3-layer race protection as platform invoices:

HYBRID Mode: Draft Lifecycle¶

DRAFT → [org edits] → DRAFT → [org issues] → ISSUED → [refund] → CANCELLED
                       ↓
                  [org deletes]

• Edit: All fields except seller (org) info are editable. The org is liable for invoice content. Stale PDF is deleted on edit and regenerated on-demand at download time.
• Issue: Sets status=ISSUED, issued_at=now(), regenerates final PDF, sends email.
• Delete: Removes draft and its PDF file.

Credit Notes¶

Generated on the charge.refunded webhook, keyed on the specific Refund row(s) that webhook call just applied — not the whole Payment — so two separate partial refunds on the same payment each produce their own credit note:

• If the invoice is DRAFT → delete the draft (nothing was issued)
• If the invoice is ISSUED → create a credit note for sum(refund.amount), with VAT pro-rated per row from the original payment's VAT ratio (refund.amount × payment.vat_amount / payment.amount, rounded half-up to the cent)
• If total credited across all credit notes ≥ invoice total → mark invoice as CANCELLED

Idempotency is enforced by checking for an existing credit note covering the exact same set of refund ids (falling back to the legacy payment-id set for credit notes generated before this refund-row-keyed path existed).

Email Delivery¶

Emails are sent from the org's branded address:

API Endpoints¶

Buyer-facing (authenticated user)¶

Org admin (owner only)¶

Refunds¶

Refunding a ticket payment and cancelling the ticket are orthogonal operations: refunding never cancels, and cancelling never implies a refund unless explicitly requested. See the organizer refund journeys for the endpoint-level flow.

Refund Model¶

events.models.Refund — one row per refund attempt, not per payment. A partial refund followed by a second partial refund on the same Payment produces two rows, never an updated one.

Payment.refund_amount stays a denormalized running total of SUCCEEDED rows, maintained by the webhook, so existing readers (revenue reporting, VAT decomposition) keep working unchanged.

Every code path that moves refund money — the organizer API, user self-service cancellation, series-pass cancellation, and the bulk event-cancellation sweep — funnels through one primitive, refund_service.issue_refund(): it locks the Payment, computes remaining_refundable() (payment.amount minus every non-FAILED Refund row), creates a PENDING row, and calls stripe.Refund.create() with a deterministic idempotency key (refund:{payment_id}:{sequence}:{amount}, where sequence counts all of the payment's Refund rows regardless of status). A rolled-back attempt leaves no row, so a retry after a crash reuses the same key and the same Stripe refund instead of double-refunding; a persisted FAILED row advances the key, so retrying after e.g. balance_insufficient (the sweep's failure rows, or the standalone organizer endpoint — which records a FAILED row on Stripe failure) gets a fresh key instead of replaying the error response Stripe caches per key for ~24 hours.

Bulk Event-Cancellation Sweep¶

Cancelling an event with refund_tickets=true dispatches events.refund_cancelled_event_tickets, a cheap fan-out task that snapshots every active ticket id and dispatches one events.refund_one_cancelled_event_ticket subtask per ticket — no monolithic in-process loop. Each subtask refunds (if the ticket has an online payment) then cancels, in that order and in separate transactions, so a crash between the two steps is safely resumable: re-dispatching finds remaining_refundable() == 0 from the prior run's Refund row, falls through NothingToRefundError, and proceeds straight to cancellation. Cancellation happens regardless of whether the refund attempt succeeded, failed, or had nothing to do — a ticket must not survive a cancelled event just because Stripe declined the refund. Re-POSTing update-status with status=cancelled, refund_tickets=true is therefore the supported way to resume a crashed or partial sweep. A self-rescheduling task polls ticket state and sends org staff a single completion summary once the fan-out settles (or a bounded polling window elapses).

charge.refunded Webhook: Record-Only¶

The webhook never cancels a ticket or reclaims tier capacity — a refund, whether issued through Revel or applied directly in the Stripe dashboard, only updates Refund/Payment state. _handle_ticket_refunds (in events.service.stripe_webhook_refunds) matches each refund object in the charge to its ticket Payment row(s), first match wins:

1. An existing stripe_refund_id already on a Payment or Refund row (replay)
2. refund.metadata["refund_id"] — our own Refund row pointer, set by issue_refund()
3. refund.metadata["ticket_id"] — explicit pointer
4. Exactly one Payment on the intent (unambiguous by construction)
5. Exactly one unrefunded Payment with a matching amount — but only when every Payment on the intent costs the same. On a mixed-price batch, a partial refund on the expensive ticket is indistinguishable from a full refund of the cheap one, so the matcher refuses to guess
6. The refund amount equals the sum of all unrefunded payments on the intent (a full-batch sweep)
7. Ambiguous → logged, and a durable REFUND_UNMATCHED staff notification is raised; nothing is mutated

A Stripe-dashboard refund that matches lands as a Refund row with source=stripe_dashboard — the ticket stays valid until the organizer cancels it separately.

Referral Payout Statements¶

When referral payouts are disbursed, Revel generates a document for each payout. The document type depends on whether the referrer is a B2B entity (has a validated VAT ID) or a B2C individual.

B2B vs B2C Decision¶

Self-Billing Invoice (Gutschrift)¶

Per Austrian UStG §11, the platform issues a Gutschrift on behalf of the referrer. This is a full VAT invoice where the VAT treatment follows the same rules as platform fee invoices:

Requirements: - Referrer must have agreed to self-billing (self_billing_agreed = True on UserBillingProfile) - The document is labeled "GUTSCHRIFT" (not "Rechnung")

Payout Statement¶

For B2C referrers (individuals without a VAT ID), the platform issues a payout statement — a non-VAT document that records the payment for bookkeeping purposes. No VAT is charged or shown.

Numbering¶

Format: RVL-RP-{YEAR}-{SEQUENCE:06d} (e.g., RVL-RP-2026-000001)

Uses the same race-condition-safe sequential numbering as platform fee invoices.

Model¶

ReferralPayoutStatement (accounts app) stores: - document_type: self_billing_invoice or payout_statement - Snapshots of referrer and platform business details - Fee breakdown with VAT - PDF file (ProtectedFileField)

Processing Pipeline¶

flowchart TD
    subgraph Monthly["Monthly Payout Processing (Celery Beat)"]
        Beat[Celery Beat] -->|"1st of month, 06:30 UTC"| PayTask[process_referral_payouts]
        PayTask -->|"per CALCULATED payout"| Check{Pre-flight checks}
        Check -->|"Stripe enabled + billing profile + self-billing agreed"| GenStmt[Generate statement PDF]
        Check -->|"Missing requirement"| Skip[Skip]
        GenStmt --> Transfer[stripe.Transfer.create]
        Transfer -->|"success"| Paid["status → PAID"]
        Transfer -->|"Stripe error"| Failed["status → FAILED"]
        Paid --> Email[Send statement email]
    end

Email Settings¶

Billing emails (platform fee invoices and referral payout statements) use dedicated sender configuration:

Both are configured via environment variables and fall back to DEFAULT_FROM_EMAIL when not set.

Celery Beat Schedule¶

Tasks are registered via data migrations.