Skip to main content

Agency Billing Workflows

Purpose​

This document defines the exact billing workflows the app should support first for agencies using their own Stripe account.

These are the operational workflows that should feel native inside the app.

Workflow Standard​

For each workflow below:

  • the app is the working surface
  • Stripe is the billing truth
  • mirrored billing state in the app exists for client/account context and portal UX

1. Connect Agency Stripe Account​

Goal​

Let an agency connect its Stripe account so the app can operate billing on its behalf.

Org-side flow​

  1. Agency opens billing setup in org.
  2. Agency starts Stripe connection.
  3. Agency authorizes or completes Stripe onboarding.
  4. App stores agency Stripe connection state.
  5. App shows whether billing is ready, incomplete, or broken.

Must support​

  • initial connection
  • reconnect flow
  • requirement/incomplete onboarding state
  • visible sync health

Should not require in v1​

  • multiple Stripe accounts per agency

2. Ensure Client Billing Customer Mapping​

Goal​

Every client account should have a billing identity inside the agency's Stripe account.

Org-side flow​

  1. Agency opens a client account.
  2. Agency enters or confirms billing identity/defaults in the customer create flow or customer overview.
  3. App creates or links a Stripe customer for that client.
  4. App stores the durable app-facing billing data on the client account and keeps the internal billing mapping in sync behind it.

Must support​

  • one client account to one primary Stripe customer mapping
  • billing email/contact info
  • customer-level billing defaults such as invoice prefix, sequence, locale, tax status, and invoice rendering template
  • clear status when no Stripe mapping exists yet

3. Draft Invoice​

Goal​

Let agencies prepare an invoice without sending it immediately.

Org-side flow​

  1. Agency opens client billing.
  2. Agency chooses Create invoice from the billing workspace or a customer billing tab.
  3. App starts a draft invoice workflow.
  4. Agency adds line items manually, from presets, or from time-based recommendations.
  5. App saves the draft state through Stripe-backed invoice workflow.

Must support​

  • manual line items
  • reusable service/preset line items
  • optional recommended line items from time entries later
  • draft review before finalization

4. Finalize And Send Invoice​

Goal​

Move a draft invoice into a real payable client invoice.

Org-side flow​

  1. Agency reviews draft invoice.
  2. Agency finalizes invoice.
  3. Agency sends invoice or invoice link.
  4. Client sees invoice in the portal and via Stripe-hosted payment flow.

Must support​

  • finalize invoice
  • send invoice or invoice link
  • portal-visible invoice state
  • hosted payment entry point

Public sharing boundary​

The Stripe-hosted invoice URL is the public payment artifact. Org and portal users may copy it and send it to a payer, who can review and pay that invoice without creating or signing into a portal account.

Keep these related surfaces authenticated:

  • draft invoices and draft line items
  • invoice, subscription, and transaction collections
  • saved payment methods
  • customer billing-portal sessions
  • subscription lifecycle and pricing controls

Hosted quote pages and Stripe receipt URLs may also be shared because each URL is scoped to one Stripe-hosted artifact. A billing-portal session must never be treated as a durable share link because it grants broader customer access and is created for an authenticated portal or org user.

5. Track Invoice State​

Goal​

Keep org and portal views aligned with actual Stripe invoice state.

Must support​

  • draft
  • open / due
  • paid
  • overdue
  • payment failed
  • void

Sync rule​

Invoice state should update from Stripe events first, not only manual refresh.

6. Create Retainer Or Recurring Subscription​

Goal​

Let agencies create recurring billing relationships for ongoing service.

Org-side flow​

  1. Agency opens client billing.
  2. Agency chooses Create subscription from the billing workspace or a customer billing tab.
  3. Agency selects or creates the service context.
  4. App creates Stripe subscription on behalf of the agency's Stripe account.
  5. Portal reflects active recurring billing state.

Must support​

  • recurring retainer/service subscription
  • agency-visible service label in app language
  • portal-visible subscription summary
  • current status and renewal/cancel state
  • no required project-selection step for normal recurring billing
  • optional project or engagement association when the agency wants that context

7. Manage Subscription Lifecycle​

Goal​

Let the agency manage ongoing recurring billing without leaving the app for normal tasks.

Must support​

  • view active status
  • update service context if the pricing model changes
  • cancel or schedule cancellation
  • detect past-due or payment-problem state

Can wait​

  • complex usage billing
  • multiple overlapping subscriptions as a primary v1 pattern

8. Open Client Billing Portal​

Goal​

Give the client a safe Stripe-hosted place to manage payment details and billing actions.

Portal-side flow​

  1. Client opens billing in the portal.
  2. Client chooses payment-method or billing-management action.
  3. App launches Stripe-hosted billing portal session or equivalent hosted flow.
  4. Client returns to the portal with updated state.

Must support​

  • payment method update flow
  • subscription/payment management entry point
  • return back into portal context

Production v1 authority rule​

Portal users can view invoices and subscriptions, pay through hosted invoice pages, manage saved payment methods, and enter Stripe's hosted customer portal. They must not directly set agency-owned subscription prices, quantities, discounts, trials, schedules, pause behavior, or collection rules in the app. Any customer-initiated subscription changes must go through Stripe's hosted portal and the connected agency account's Stripe portal configuration.

9. Time-Informed Billing​

Goal​

Let tracked time help billing without forcing agencies into rigid time-based invoicing.

Org-side flow​

  1. Agency may create a manual invoice directly, or use the optional period-based Ready to bill surface on All invoices.
  2. Readiness defaults to the current month and shows one compact row per client and currency only when eligible tracked time exists.
  3. Prepare invoice opens a separate draft with the client, currency, and exact period already selected. It does not add or reserve time.
  4. For direct creation, the agency chooses a client-wide invoice or an optional project-specific invoice scope.
  5. App shows one Ready to bill recommendation for the invoice currency: total hours, calculated value, project count, and date range.
  6. Agency explicitly adds the recommendation. Under the surface, the app preserves separate project, historical-rate, and currency-safe groups; project invoices remain limited to their selected project.
  7. Agency may open Review to inspect exact entries, choose a custom period, or override a group rate before sending.
  8. Final invoice remains editable before send.

Must support​

  • recommendations from time
  • project override → client default → manual override rate resolution
  • capture-time rate and currency snapshots so later default changes never silently reprice older work
  • multiple independently priced time lines on a client-wide invoice
  • strict project matching on project-specific invoices
  • duplicate-entry rejection across invoice time groups
  • one confirmable recommendation without silently adding or invoicing anything
  • one optional period overview that never replaces direct manual invoice creation
  • currency separation without implicit conversion
  • manual override
  • no hard lock between tracked time and sent invoice

10. Billing Notifications​

Goal​

Keep both sides informed when billing state changes.

Must support​

  • invoice sent
  • invoice overdue
  • payment failed
  • subscription issue or cancellation state

11. Post-Send Invoice Lifecycle​

Goal​

Let agencies handle the normal real-world mess that happens after an invoice is already sent.

Why this matters​

For a legitimate agency product, this is not optional forever.

Clients change scope. Mistakes happen. Goodwill adjustments happen. Partial refunds happen. Sometimes an invoice should be voided.

If the app cannot eventually handle those realities, agencies will keep living in Stripe for important billing operations.

Eventual required operations​

  • void open invoice when it should no longer be collectible
  • apply partial adjustments or credits when scope/value changes
  • refund paid invoices fully or partially
  • mark off bad debt or uncollectible outcomes where Stripe supports that truth
  • preserve a visible audit trail of what changed and why

Product rule​

These flows should be built as Stripe-aligned billing operations inside the app.

They should not create a shadow accounting system.

12. Invoice Change Timing Model​

To keep the product sane, invoice changes should be thought of in three stages:

Before send​

  • line items can be edited freely
  • discounts/adjustments are normal draft behavior
  • time-based recommendations can be changed freely

After send but before payment​

  • agencies may need to void, revise through the proper Stripe-aligned path, or issue credits/adjustments depending on the billing situation

After payment​

  • agencies may need refunds, credits, or follow-up corrective records

The app should present these as different operational states, not one generic edit invoice action.

Not First-Wave Blockers​

These still do not need to land in the very first billing release:

  • full in-app refund/credit-note surface on day one
  • partial-payment complexity beyond what Stripe naturally supports
  • quote-to-invoice workflow
  • usage-based subscription logic

They are later billing phases, not product-scope exclusions.