Billing and promotions

Use the Stripe customer portal for invoices and payment methods. Run paid promotions from the development detail page when active price IDs are configured.

The builder console exposes two billing surfaces today:

The Billing page at /teams/[teamSlug]/billing opens a one-shot link to your team's Stripe customer portal.
The Promotion panel inside each development detail at /teams/[teamSlug]/developments/[developmentId] starts and cancels a featured-development promotion.

Both surfaces require manage-billing permission. Without it, the surfaces 404 on direct navigation and the nav items hide.

Who can manage billing

Role	Billing access by default?	Notes
Owner	Yes	Owners have full team permissions, including billing.
Admin	No	Admins manage day-to-day team operations but do not manage billing by default.
Member	No	Members do not manage billing.
Platform admin	Yes	Forcir platform administrators can support billing flows.

If a "Billing" item is missing from the team nav, the signed-in user probably lacks manage-billing.

Billing portal

Open the team workspace, then select Billing in the team nav. Select Open billing portal to launch the Stripe customer portal in a new tab.

The portal handles:

Payment methods.
Billing information.
Invoice history.
Subscription details (cancellation, plan change).

If the new tab does not open, check the browser's pop-up blocking settings. The one-shot link expires after a few minutes; if you wait too long, regenerate it from the Billing page.

Featured development promotion

A featured-development promotion gives a development paid placement in Solum's discovery surfaces.

Eligibility

The Promotion panel offers a checkout button only when all of the following are true:

Requirement	Why it matters
Team is a builder team and linked to a builder	Promotions are tied to builder developments.
Development belongs to the linked builder	A team cannot promote another builder's development.
You hold the manage-billing permission	Checkout and cancellation are billing actions.
The development is not already featured	An existing featured status blocks duplicate checkout.
No active or pending promotion exists already	Prevents duplicate subscriptions or duplicate pending checkouts.
Stripe price IDs for the duration are configured	Monthly and quarterly require live Stripe Prices in environment.

If the environment is missing the Stripe price IDs (SOL-450 wired the config), checkout aborts with HTTP 503 and the message "Promotion checkout is not configured for this environment."

Durations

The flow supports Monthly and Quarterly. Pricing is shown in Stripe checkout. Do not rely on hard-coded prices in support replies.

Starting a promotion

Sign in as a user with manage-billing.
Open the builder team workspace and the development detail page.
Pick Monthly or Quarterly.
Select Feature this development.
Complete Stripe checkout.

The promotion flips to active when Stripe fires the checkout.session.completed webhook. Until then it shows pending.

If a promotion is active, billing-authorized users can select Cancel promotion on the same development detail page. Cancellation schedules the subscription to end at the end of the current billing period; the development remains featured until that date.

Promotion statuses

Status	Meaning
Pending	Checkout has started but Stripe has not activated it yet.
Active	The development is currently featured.
Cancelled	The promotion has been cancelled or has run to expiry.
Expired	The promotion ended at the end of its billing period.

What is not in the billing surface today

Active promotions summary card on the Billing page. The Billing page only renders the customer-portal launcher today; the per-team promotion roll-up lives inline on each development detail page until the summary card ships.
Billing-only role (manage billing without consuming a seat). Roles available today are owner, admin, member. Use platform-admin support if a billing-only contact is needed.

These are roadmap items, not "ask Forcir" workarounds.

Why a checkout call may fail

Failure	What to check
403 forbidden	The signed-in user lacks manage-billing.
422 "development already featured"	The development is already in a featured state. Cancel first if you need to recheck out.
422 "active or pending promotion exists"	There is already a promotion row for this development. Resolve it (cancel or wait for Stripe webhook) before retrying.
503 "Promotion checkout is not configured"	The Stripe price IDs are missing from the environment. Operator must set `STRIPE_PRICE_FEATURED_MONTHLY` and `_QUARTERLY`.
Portal or checkout does not open	Check browser pop-up blocking and network connectivity.

Support notes for billing questions

When reporting a billing issue, include:

Team name and slug.
User email and role.
Whether the issue is billing portal, checkout, cancellation, or promotion status.
Development name for promotion issues.
Screenshot or exact message from Stripe when available.