Skip to main content

Billing UX Map

Purpose​

This document maps the first real billing UX for org and portal before implementation starts.

It is intentionally focused on the first working billing experience, not every later finance edge case.

Core IA Split​

Keep these surfaces distinct:

  • org/settings/billing agency pays for this app via Polar
  • org/(dashboard)/billing agency bills its own clients via Stripe
  • portal/(dashboard)/billing client sees invoices, subscription status, and payment actions

Org Billing UX​

1. Billing Overview​

Primary page purpose:

  • show billing attention items across clients
  • show unpaid invoices, failed payments, overdue accounts, and active subscriptions

Should show:

  • clients with open balances
  • overdue invoices
  • failed payment states
  • subscriptions needing attention
  • Stripe connection health

2. Customer Billing Tab​

Primary page purpose:

  • make one client's billing relationship understandable and actionable inside the customer workspace

Should show:

  • billing contact
  • Stripe customer state
  • invoice list
  • subscription/retainer summary
  • payment state
  • billing documents if relevant

Primary actions:

  • create invoice from the customer billing tab
  • create subscription from the customer billing tab
  • open hosted billing portal action

Ownership rule:

  • manage billing identity/defaults from the customer overview
  • manage people/contacts from the customer people tab
  • keep invoice/subscription actions in the customer billing tab or the shared billing workspace, not the page chrome

3. Create Invoice Flow​

Recommended shape:

  • dedicated composer launched from the billing workspace or the customer billing tab
  • line items section
  • presets section
  • optional time suggestions section
  • totals and review section

Primary steps:

  1. choose client
  2. optionally create the client inline if it does not exist yet
  3. add line items or presets
  4. optionally pull suggested billable time
  5. review
  6. save draft
  7. finalize/send

4. Create Subscription Flow​

Recommended shape:

  • focused composer launched from the billing workspace or the customer billing tab

Primary inputs:

  • client
  • service label
  • price/plan selection
  • start behavior
  • billing contact context

Primary result:

  • active or pending recurring billing relationship tied to the client account

5. Stripe Connection UX​

This should likely live in org billing admin, not general settings for every user.

Should show:

  • connected / not connected
  • onboarding incomplete / action required
  • last sync or health signal

Primary actions:

  • connect Stripe
  • reconnect Stripe
  • fix onboarding requirements

Portal Billing UX​

1. Billing Home​

Primary page purpose:

  • answer what is owed and what service is active

Should show:

  • current open balance
  • recent invoices
  • active subscription/retainer summary
  • payment status alerts

Primary actions:

  • pay invoice
  • open billing portal

2. Invoice Detail​

Should show:

  • invoice number / label
  • status
  • amount
  • due date
  • line items summary
  • hosted payment/download action

3. Subscription Summary​

Should show:

  • service label
  • status
  • current billing period
  • cancellation/renewal state
  • payment method management entry point

4. Payment Method Flow​

Recommended shape:

  • app launches Stripe-hosted flow
  • user returns to portal
  • portal refreshes mirrored billing state

UX Principles​

Keep finance power in org, clarity in portal​

Org is where invoices and subscriptions are managed.

Portal is where billing is understood and paid.

Keep Stripe-native tasks hosted when Stripe already does them well​

Do not rebuild payment-method forms or hosted payment collection prematurely.

Keep invoice and subscription concepts visually separate​

Users should never have to guess whether they are looking at:

  • a one-time invoice
  • an ongoing recurring service

Keep time suggestions subordinate to human review​

Time-informed billing should help the agency bill faster, not make them fight auto-generated billing they did not ask for.