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

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

9. Time-Informed Billing​

Goal​

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

Org-side flow​

  1. Agency opens invoice creation.
  2. App can recommend unbilled billable time entries.
  3. Agency selects, edits, combines, or ignores suggestions.
  4. Final invoice remains editable before send.

Must support​

  • recommendations from time
  • 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.