Skip to main content

Billing Permissions Model

Purpose​

This document defines the first practical permission model for billing.

It is intentionally simple. The product should not start with a huge permission matrix.

It should also not assume that every agency uses the exact same fixed role bundle forever.

Recommended planning stance:

  • these role names are initial templates, not permanent hardcoded truth
  • the agency owner should be able to decide which non-owner roles can perform which billing actions
  • specific user exceptions can exist later, but should not replace the base role model

Agency-Side Roles​

These are recommended default templates for the first wave, not rigid immutable roles.

1. Agency Owner​

Can:

  • connect Stripe
  • manage billing settings
  • create and send invoices
  • create and manage subscriptions
  • view all billing data
  • manage client billing contacts

2. Agency Admin / Finance Manager​

Can:

  • create and send invoices
  • create and manage subscriptions
  • view all billing data
  • manage client billing contacts

Cannot by default:

  • disconnect the agency Stripe account unless explicitly allowed later

Owner-configurable note:

  • an agency owner may choose to delegate or restrict some of these powers inside that agency

3. Account Manager / Project Manager​

Can:

  • view client billing summary
  • draft invoice recommendations
  • prepare invoices for review

Cannot by default:

  • finalize/send invoices
  • create or cancel subscriptions
  • modify Stripe connection settings

Owner-configurable note:

  • an agency owner may choose to allow some account managers to invite portal users, prepare invoices, or view broader billing details

4. Staff / Contributor​

Can:

  • contribute time entries that may inform billing later

Cannot by default:

  • view billing summaries or invoice state
  • create invoices
  • send invoices
  • create subscriptions

Owner-configurable note:

  • specific staff may receive narrow extra privileges if the agency has a real operational need

Client-Side Roles​

1. Client Owner / Client Admin​

Can:

  • view all client-facing billing data
  • pay invoices
  • open billing portal
  • manage payment-method workflows through Stripe-hosted flows
  • invite or manage other client users later if enabled

2. Client Billing Contact​

Can:

  • view billing data
  • pay invoices
  • open billing portal

Cannot by default:

  • manage broader account administration

3. Client Collaborator​

Can:

  • view projects, files, docs, and updates as allowed

Cannot by default:

  • view billing
  • pay invoices
  • manage payment methods

4. Client Viewer​

Can:

  • view explicitly shared content

Cannot by default:

  • act on billing
  • upload/manage account-wide settings

Permission Principles​

Client access is the scope gate; billing RBAC is the finance gate​

On the agency side, a user should normally need access to the client account before any client billing context is relevant.

But client-account access alone should not automatically grant full finance visibility.

The intended model is:

  • client-account access decides which clients a staff user can work with
  • billing roles and capabilities decide how much financial detail that staff user can see or act on

Hard rule:

  • if a user does not have billing permission, they should not see billing at all
  • do not soften this with teaser summaries like paid, overdue, or next invoice

Role Template Rule​

Treat the role sections above as recommended defaults.

The actual product direction should be:

  • owner controls the agency's non-owner billing permissions
  • role templates provide the starting point
  • user-specific exceptions are allowed but should stay exceptional

Billing visibility should be narrower than project visibility​

Many client-side collaborators should see project progress without seeing finance details.

Stripe connection control should be highly restricted​

Only top-level agency operators should control the agency Stripe connection.

Time contribution is not billing authority​

A staff member logging time should not automatically gain invoice authority.

For implementation planning, the first billing permission groups should roughly be:

  • billing.connection.manage
  • billing.view
  • billing.invoice.create
  • billing.invoice.edit
  • billing.invoice.send
  • billing.invoice.void
  • billing.subscription.view
  • billing.subscription.manage
  • billing.portal.access

Reasoning:

  • viewing billing is separate from creating or sending invoices
  • editing a draft invoice is separate from sending it
  • subscription visibility is separate from subscription management
  • destructive or high-trust actions should not be hidden behind one generic billing permission

On the client side, the product can start with simpler role bundles rather than fine-grained capabilities.