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.

Time oversight is also not client-record authority. The live role matrix uses:

  • time.view_team to view teammate time metadata and totals
  • time.review to review submitted entries and see the private work detail required for that review
  • time.manage to edit, delete, and lock team entries

Staff without these permissions retain full access to their own entries only. Invoice operators may inspect eligible dates and durations for allocation, but private notes still follow the time-detail permission boundary.

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.