# Billing and paid organizations

shithub's first paid surface is organization billing. This document
records the product and engineering contract that the PAYMENTS sprint
series implements.

The current implementation already has the important shape for paid
organizations: `orgs.plan` is an enum with `free`, `team`, and
`enterprise`; organizations own repositories; organization members and
teams exist; branch protection and PR review gates exist; Actions has
schema for org/repo secrets, variables, and artifacts. Billing must
turn that substrate into a fair hosted service without taxing
public/open-source collaboration.

## Product contract

As of 2026-05-12, GitHub's public pricing page presents Free at
`$0`, Team at `$4/user/month`, and Enterprise starting at
`$21/user/month`. shithub follows the same mental model but removes
Copilot/AI promises from the paid-org offering.

Initial decisions:

- Free organizations remain self-serve.
- Team is `$4` per active organization member per month.
- Active organization members, including owners, count as paid seats.
- Team has no launch trial.
- Enterprise is a visible contact-sales stub, not self-serve.
- Stripe Billing is the first payment processor.
- PayPal, manual invoices, SAML, SCIM, LDAP, enterprise account
  hierarchy, and contracts are deferred.
- Self-serve organization creation presents `/organizations/plan` as
  the canonical plan selector. Choosing Team creates the organization
  and immediately redirects the owner to hosted Stripe Checkout.

The fairness rule is explicit: public/open-source collaboration should
stay generous. Paid gates focus on private collaboration, hosted cost,
advanced organization controls, and support expectations.

## Pricing copy rules

Pricing and onboarding pages must describe only features shithub can
actually deliver on the hosted service. Before changing pricing copy,
refresh the official GitHub pricing source and the Stripe Billing docs
because both are time-sensitive inputs.

Rules for paid-org copy:

- Do not mention Copilot, AI agents, AI code review, or AI quotas.
- Do not promise SAML, SCIM, LDAP, managed users, audit exports, data
  residency, compliance attestations, contracts, or custom support
  until the matching implementation sprint ships.
- Do not advertise Packages, Pages, Wikis, Projects, Actions minutes,
  or storage quotas until those surfaces have enforcement and usage
  accounting.
- Use upgrade language for unavailable Team features instead of hiding
  existing data. Downgrades preserve configuration and make gated
  settings read-only where possible.
- Keep public/open-source collaboration generous in both copy and
  enforcement. Avoid copy that makes public repositories feel like a
  second-class Free tier.
- Enterprise is a contact-sales stub in v1. It should collect interest
  without promising contractual features.

## Entitlement matrix

| Capability | Free | Team | Enterprise stub |
| --- | --- | --- | --- |
| Public org repositories | Included | Included | Contact sales |
| Basic private org repositories | Included | Included | Contact sales |
| Org members and invitations | Included | Billed by active member | Contact sales |
| Visible teams | Included | Included | Contact sales |
| Secret teams | Upgrade | Included | Contact sales |
| Basic branch protection | Included | Included | Contact sales |
| Advanced private-repo branch protection | Upgrade | Included | Contact sales |
| Required reviewers on private org repos | Upgrade | Included | Contact sales |
| CODEOWNERS review | Deferred | Deferred | Deferred |
| Org-level Actions secrets | Upgrade | Included | Contact sales |
| Org-level Actions variables | Upgrade | Included | Contact sales |
| Actions minutes | Low quota once metered | Higher quota once metered | Contact sales |
| Actions artifacts/storage | Low quota once metered | Higher quota once metered | Contact sales |
| Packages storage | Deferred until Packages is active | Deferred until Packages is active | Deferred |
| Pages/Wikis/Projects | Do not promise until shipped | Do not promise until shipped | Deferred |
| Audit log export | Deferred | Deferred | Later Enterprise feature |
| SAML/SCIM/managed users | Deferred | Deferred | Later Enterprise feature |
| Data residency/compliance | Deferred | Deferred | Later Enterprise feature |
| Billing support | Basic instance support | Billing support after runbook exists | Contact sales |

## Current capability audit

Already present and safe to gate:

- Organizations with `plan` and `billing_email`.
- Organization members, owner role, and invitations.
- Teams, including `privacy='secret'`.
- Branch protection rules and required review counts.
- PR review and reviewer-request substrate.
- Org/repo Actions secrets and variables schema.

Present but missing enforcement or metering:

- Storage quota type exists, but quota persistence and enforcement are
  incomplete.
- Actions minutes, artifacts, and object usage need accounting before
  paid limits can be promised.
- Packages storage cannot be sold until the Packages sprint is active
  and quota enforcement exists.

Deferred:

- SAML, SCIM, LDAP, enterprise account hierarchy, audit-log export, data
  residency, compliance promises, and custom support SLAs.
- Copilot/AI features are intentionally outside shithub's paid-org
  product.

## Billing architecture

Stripe is the payment source of truth. shithub is the entitlement source
of truth.

The billing implementation should add a local billing domain that stores
only Stripe IDs and payment summaries, never card data. Webhooks update
local subscription state after signature verification. Policy and
request handlers read local billing/entitlement state and must not call
Stripe in hot paths.

Required local concepts:

- Stripe customer per billable organization.
- Subscription state per organization.
- Subscription item ID for seat quantity sync.
- Immutable webhook receipts with unique provider event IDs.
- Invoice/payment summaries for UI.
- Seat snapshots for auditability.
- Billing grace/lock state derived from processed subscription events.

PAYMENTS SP02 adds these as local database tables:

- `org_billing_states` stores the organization billing projection used
  by entitlement checks.
- `billing_seat_snapshots` records active and billable seat counts over
  time.
- `billing_invoices` stores invoice/payment summaries for billing UI.
- `billing_webhook_events` stores immutable provider event receipts for
  idempotent webhook processing.

New organizations receive a Free billing state from a database trigger,
and the migration backfills existing organizations as Free. Subscription
snapshot writes also keep `orgs.plan` synchronized as the
human-facing summary.

PAYMENTS SP03 adds the first Stripe operator contract:

- `billing.enabled=false` keeps paid-org flows disabled while retaining
  the local billing tables.
- `billing.stripe.secret_key`, `billing.stripe.webhook_secret`, and
  `billing.stripe.team_price_id` are required before Stripe routes are
  mounted.
- Checkout success, Checkout cancel, and Billing Portal return URLs may
  be overridden explicitly; otherwise the web layer derives absolute
  organization URLs from `auth.base_url`.
- `billing.grace_period` controls how long failed-payment states may
  remain unlocked before paid entitlements are cut off.
- When billing routes are mounted, `/settings/organizations` links
  owner-managed organizations to their billing page's plan comparison.
  When billing is disabled, that action stays visibly unavailable
  instead of linking to an unmounted route.

The operator enablement flow is documented in
[`runbooks/stripe-billing.md`](./runbooks/stripe-billing.md).

PAYMENTS SP04 adds the self-serve onboarding flow:

- `/organizations/plan` is the canonical plan picker.
- Free setup creates the organization locally without Stripe.
- Team setup creates the organization, creates or reuses the Stripe
  customer, counts billable seats, and redirects directly to hosted
  Stripe Checkout.
- Checkout success and cancel returns render shithub pages. Success
  tells the owner that activation waits for webhook processing; cancel
  keeps the organization on Free and offers a retry path.

PAYMENTS SP05 adds the local entitlement boundary. Product code must ask
`internal/entitlements` for feature decisions instead of inspecting
`orgs.plan` directly. The package derives access from
`org_billing_states`, understands billing-good-standing states, and
returns upgrade metadata for user-facing handlers.

PAYMENTS SP06 wires the first Team gates:

- Secret teams require Team to create. Existing secret teams remain
  visible to authorized viewers after downgrade; owners can remove
  members and repository grants, but adding members or granting more
  repository access is blocked until Team billing is active again.
- Required reviewers and advanced status-check branch protection are
  Team-only for private organization repositories. Public organization
  repositories keep those safety controls available on Free.
- Downgraded private organization repositories may delete protection
  rules or submit a rule update that clears the gated review/check
  settings.
- Org-level Actions secrets and variables require Team for create or
  update in both HTML settings and REST API routes. Delete stays
  available so owners can clean up gated configuration after downgrade.
- Org-level Actions secrets and variables API routes require
  organization owner or site-admin access before entitlement checks.

PAYMENTS SP07 completes the first self-serve billing settings surface:

- `GET /organizations/{org}/settings/billing` is owner-only and is
  linked from organization settings when Stripe Billing is configured.
- The page shows current local plan state, subscription status, payment
  source summary, recent Stripe-synced invoice snapshots, and actionable
  banners for past-due, grace-period, canceled, scheduled-cancel, and
  billing-action-needed states.
- Seat accounting is shown as three separate values: current active
  members, billable seats from the latest local billing state, and
  pending invitations. Pending invitations are explicitly not billed
  until accepted.
- Team organizations manage payment method, invoices, cancellation, and
  downgrade through Stripe Billing Portal. shithub never collects card
  data directly and downgrades continue to preserve paid configuration
  as read-only data.
- Normal organization owners do not see raw Stripe customer,
  subscription, or subscription-item IDs. Site admins see a debug panel
  with those IDs and the latest locally recorded webhook receipt state.

## Entitlement architecture

Paid feature checks must live behind a central entitlement package, not
as scattered `orgs.plan` checks in handlers.

`make lint-org-plan` enforces this boundary. Schema/sqlc plumbing may
store and scan the plan value, but product behavior should ask the
entitlement package whether a feature key is available.

The package entrypoint is `entitlements.ForOrg(ctx, deps, orgID)`,
which loads the local `org_billing_states` projection and returns a
request-scoped entitlement set. Callers then use `CanUse(feature)` for
feature decisions and `Limit(name)` for paid limit metadata. The legacy
`CheckOrgFeature` helper is a thin wrapper for handlers that need only
one feature. These calls are deterministic and never call Stripe.

Expected feature keys:

- `org.secret_teams`
- `org.advanced_branch_protection`
- `org.required_reviewers`
- `org.actions_org_secrets`
- `org.actions_org_variables`
- `org.private_collaboration_limit`
- `org.storage_quota`
- `org.actions_minutes_quota`

Authorization and entitlement are separate gates. A user must have both
the policy permission and the paid entitlement for gated writes. Denials
must preserve existing `policy.Maybe404` behavior where existence leaks
matter.

Entitlement outcomes are:

- Free organizations receive `upgrade_required` for Team features.
- Team organizations with `active` or `trialing` subscriptions receive
  the feature.
- Team organizations in `past_due` remain usable only while their local
  grace window has not expired.
- Team organizations with incomplete, unpaid, paused, canceled, or
  expired-grace billing receive `billing_action_needed`.
- Enterprise remains a contact-sales stub and receives
  `enterprise_contact_sales` until a later Enterprise sprint defines a
  real feature set.

Handler upgrade helpers map paid-feature denials to HTTP 402 metadata
and a billing-settings path, but handlers must still perform normal
authorization first and preserve 404 masking for private resources.

## Downgrade behavior

Downgrades must preserve customer data. Moving from Team to Free should
not delete teams, secrets, variables, branch rules, or review settings.
Existing gated resources become read-only where possible. Users can
remove gated configuration, but cannot create or expand it until the
organization upgrades again.

## Open questions for implementation

- Whether Free should limit private org collaborators before usage
  metering exists, or whether the first paid gates are advanced controls
  only.
- Exact Free and Team quota numbers for Actions and storage. These must
  come from real host-cost estimates before SP08.

## Source references

- GitHub pricing: `https://github.com/pricing`
- GitHub plans docs:
  `https://docs.github.com/en/get-started/learning-about-github/githubs-plans`
- Stripe Billing: `https://docs.stripe.com/billing`
- Stripe pricing models:
  `https://docs.stripe.com/products-prices/pricing-models`