Change tier + add repos

Tier moves, billing-cycle switches, adding repos at the cap, and cancellation. This is the sponsor's reference for changing the subscription state once the first setup is done.

How billing actually works

Steward delegates the buying surface to Paddle — invoices, payment method, plan moves, cancellation, refunds, and the customer portal all live there. Steward's /sponsor/billing shows you the current subscription state (with status, current_period_end, canceled_at) and an Open Paddle portal button that bounces you to the portal for actions.

So: read state on /sponsor/billing; act on Paddle. The portal handles every mutation, fires a webhook back to Steward, and the Steward UI catches up within a few seconds.

Upgrading

The common move. You're on Pro, you want to be on Team.

From /sponsor/billing, click Open Paddle portal.
In the Paddle portal, Change plan → pick the higher tier → confirm.
Paddle prorates the charge (you pay the difference for the remainder of the current period only).
Paddle fires subscription.updated to Steward.
Within seconds, /sponsor/billing shows the new tier; /sponsor/usage recognises the new daily cap immediately.

Quota effects are immediate

The new daily cap applies right now. If you were hitting the Pro cap (40 credits) every afternoon, upgrading to Team midday gives you 120 more credits for the rest of today (your spend resets at UTC midnight regardless of the tier change timing).

Repo cap effects are immediate

If you'd been blocked from adding repos at the Pro cap (3 repos), the next install you start will succeed because the Team cap (10) is now in force.

Seats apply on next role grant

The new seat cap takes effect on the next role grant. Existing members aren't backfilled — they were already in seats; the new allocation just lets you grant more.

Downgrading

The opposite move. You're on Team, you want to be on Pro.

Open the Paddle portal.
Change plan → pick the lower tier → confirm.
The downgrade is scheduled for the next billing cycle — the current period keeps the higher tier's quota + features.
Paddle fires subscription.updated. /sponsor/billing shows the scheduled downgrade with its effective date.

Why downgrades wait

You already paid for the current period. The higher tier's quota + seat cap stay in force until that period ends — otherwise you'd be paying for Team and getting Pro for the remainder of the period you already bought.

If you need an immediate downgrade for reasons that justify forfeiting the prepaid quota (e.g. you signed up at the wrong tier and want to switch instead of cancel), reach out to billing@steward-dev.ai.

What happens at the effective date

When the new period starts at the lower tier:

Quota drops to the lower cap. Day-1 burn-rate caveat (see Credit usage) — the first day on a lower tier looks heavier per-credit because you're used to the higher headroom.
Repo cap enforces. If you have 6 covered repos and are downgrading from Team (10) to Pro (3), the first 3 by install order stay active; the rest enter "over-cap" state and don't receive evaluations until you remove some or upgrade back.
Seats trim. If you have 5 members at Team and downgrade to Pro (single-seat), the installer keeps their seat; the rest lose Steward-side access on next sign-in. Their GitHub access is unaffected (Steward doesn't touch the GitHub installation's permission grants).
Audit + Single Sign-On (SSO) lose Business-tier features. Existing events stay in the log; new Service Organization Control 2 (SOC2) bundle exports refuse with FAILED_PRECONDITION and the audit-blocking-mode toggle reverts to off.
No data is destroyed. Per-PR evaluation history, contributor reputation, governance configuration, audit events — all preserved. Only the live-feature surface degrades.

Switching billing cycle (monthly ↔ annual)

Annual gives two months free. The switch:

Open the Paddle portal.
Change plan → keep the same tier, pick the annual variant → confirm.
Paddle prorates the existing monthly subscription against the new annual price.

Going monthly → annual mid-period charges the difference on the spot. Going annual → monthly is unusual; if you need it, talk to billing@steward-dev.ai — there's usually a prorated refund involved.

Adding repos when at the cap

You're on Pro (3 repos). You want to add a 4th. Two paths:

Path 1: upgrade

Move to Team. Cap rises to 10 immediately; install the new repo.

Path 2: remove a covered repo first

If you've grown out of one of your original 3, uninstall the App from it via GitHub:

Go to github.com/settings/installations (or your org's /organizations/<org>/settings/installations).
Click Configure on the Steward App.
Under Repository access, remove the repo you no longer want covered.

The repo drops out of Steward's covered count within seconds (via the installation_repositories webhook). You're then back at 2/3 and can install on the new repo.

Path 3: live with it

The 4th repo's webhook still fires. The webhook receiver silently no-ops for over-cap repos — no error noise on the PR thread, no false "Steward is broken" signals. The repo sits inert until you free a slot or upgrade.

Cancellation

Open the Paddle portal → Cancel subscription.

Effective date: end of the current billing period (Paddle's default). The subscription's canceled_at is set on cancel; status flips to canceled at the period end.
What you keep until period end: full quota + every feature of your current tier.
What you keep after period end: your data. Audit log, PR evaluations, reputation ledger, governance configuration, Contributor License Agreement (CLA) signatures — all preserved. Steward downgrades you to Community-tier feature visibility; the data remains.
Restarting before period-end: just re-activate from the Paddle portal. No data loss.

`subscription.canceled` audit event

User-initiated cancels emit a distinct subscription.canceled audit event (see Audit log + compliance). This is separate from the webhook-driven subscription.updated trail, so the audit log distinguishes "the user clicked cancel" from "Paddle pushed an update for any reason." Useful for compliance.

Subscription status states

/sponsor/billing surfaces a status field. The states you might see:

Status	What it means	What to do
`active`	All good. Current period paid, features live.	Nothing.
`past_due`	Payment failed; in grace period.	Update payment method via Paddle portal before grace expires.
`canceled`	User-initiated cancel landed. Period may still be active until `current_period_end`.	Nothing, or re-activate via Paddle portal.
`paused`	Sponsor paused the subscription (Paddle feature). Quota + features paused.	Resume via Paddle portal.
`trialing`	Free-trial period (limited rollout — usually only for early-access partners).	Convert before trial end.

The grace period for past_due is typically 7 days (Paddle-configurable; check your portal for the exact window). Features stay on during grace; the subscription flips to canceled if payment never lands.

Tier-comparison cheatsheet (when you're deciding)

Question	Answer
Am I spending consistently <10% of my daily cap?	You can probably downgrade. Look at `/sponsor/usage` 30-day total against `tier_cap × 30`.
Am I hitting the cap >2 days/week consistently?	Upgrade. Static-Only mode degrades the per-PR experience.
Do I need SSO or SOC2 reporting?	Business-tier. Not available below.
Do I have a one-time PR burst (release crunch)?	Pay one month at the higher tier, downgrade after.
Did I install on the wrong account?	Don't change tier — uninstall + reinstall on the right account.

What's next

Tiers + credits — the tier ladder + per-tier daily caps you're sizing against.
Credit usage — how the daily cap arithmetic works, so a tier choice is grounded in real burn.
Read the usage dashboard — the playbook for the data you'll use to right-size.