[alx-xo]

GRW-79

Summary

• Migrate hosted Stripe Checkout to the Embedded form (ui_mode: "form") on a dedicated Billing setup page, with a themed payment form, order summary, and promotion-code entry.
• Add subscription-aware Overview, Billing setup, and Payment method navigation. Checkout entry points share the setup route; Free/Base signup and partner discounts remain supported.
• Add organization-scoped session-status lookup, redirect recovery, session replacement, and delayed-payment webhook handling. Preserve historical session parameters and idempotency during migration.
• Update local Stripe setup to preserve configured key pairs, validate publishable-key readiness, and save configuration atomically. Cover checkout lifecycle behavior through real React Query flows and Stripe-boundary tests.

Deploy the server and dashboard together: createStripeCheckout now returns a client secret and publishable key. Configure STRIPE_PUBLISHABLE_KEY from the same Stripe account as STRIPE_API_KEY, and subscribe the webhook endpoint to checkout.session.async_payment_succeeded and checkout.session.async_payment_failed alongside its existing events.

Motivation

Collect payment details inside the dashboard and give billing setup a dedicated page. Keep existing promotion and subscription behavior while recovering canceled redirects and earlier hosted sessions through the same checkout lifecycle.

Gutternote review steps

1. Enable gram-payg-self-serve-billing for a sandbox organization with an active trial or an unsubscribed Free/Base account, and sign in as an org admin. Configure the preview's matching Stripe secret/publishable keys and webhook delivery. The seeded demo does not enable this flag itself.
2. Open Billing (/<org>/billing) and select Billing setup, or click Add payment method from the trial card. Expect the dedicated setup page (/<org>/billing/setup) with an order summary and Stripe form. Check light/dark themes, a narrow viewport, and promotion-code entry; an accepted partner promotion should be pre-applied.
3. Complete checkout with Stripe sandbox payment details. Expect Confirming billing setup, followed by Payment method (/<org>/billing/payment-method) after backend subscription confirmation. A delayed payment remains in the processing state until confirmed.
4. Try a redirect-based sandbox payment method and cancel its authorization. Returning to billing should resume an open checkout; an expired session should be replaced. Check retry behavior when checkout initialization or status lookup fails.
5. For an already subscribed organization, select Payment method from Billing. Spot-check checkout entry points on the trial-ended gate and lockout panel, plus restricted access for a non-admin.

Linear Issue: GRW-79

  

---

Summary by cubic

Migrates hosted Stripe Checkout to the embedded form so pay-as-you-go setup starts inside the dashboard. The checkout endpoint now returns a client secret and publishable key that mount Stripe's form on a dedicated Billing setup page instead of redirecting to hosted Checkout.

• Adds Billing setup and Payment method pages with Overview, Billing setup, and Payment method navigation, an order summary, promotion-code entry, and light/dark theming driven by the dashboard theme; a unified billing state picks between the setup and payment-method views.
• Sets STRIPE_PUBLISHABLE_KEY paired with STRIPE_API_KEY; mise run stripe:setup saves the CLI publishable key only when it also uses the CLI secret, never next to an env-provided STRIPE_API_KEY.
• Expires live hosted Checkout sessions before creating an embedded session, since Stripe rejects an idempotency key whose parameters change; new sessions accept a theme query parameter while existing sessions keep their original appearance.
• Adds an organization-scoped session-status lookup and redirect recovery that replaces expired sessions; the dialog clears when the active organization changes, and the lockout and trial-ended gate open billing routes for the active organization.
• Webhook handling now covers checkout.session.async_payment_succeeded and checkout.session.async_payment_failed alongside the existing events.
• Pins @stripe/react-stripe-js 7.0.0 and @stripe/stripe-js 10.1.0 for the embedded form while preserving legacy versions for @polar-sh/checkout via packageExtensions.

Migration

• Deploy the server and dashboard together: createStripeCheckout now returns a client secret and publishable key.
• Configure STRIPE_PUBLISHABLE_KEY from the same Stripe account as STRIPE_API_KEY, and subscribe the webhook to the two async-payment checkout events.

^{Written for commit 775b80c. Summary will update on new commits.}

Screenshots

Billing setup

Payment method

Platform MCP assessment

Decision: intentionally omit new or changed Platform MCP tools for this checkout migration. The outcome is an organization administrator completing billing setup or updating a payment method for the explicitly selected active organization, not a project-scoped management operation. The existing Platform MCP tool catalogue and registration have no billing/subscription checkout tool to update; this does not change existing tool contracts, server instructions, or shipped workflows.

• Browser and sensitive-data boundary: embedded Stripe checkout is a browser-bound payment-entry and confirmation flow. The checkout client secret belongs only at the authenticated dashboard/Stripe boundary; payment details and checkout credentials must not be exposed in agent inputs, results, or transcripts. This assessment does not propose agents collecting payment details or driving checkout through a new endpoint-shaped tool.
• Target and permission boundary: the dashboard requires organization read/admin access. Backend checkout status requires both permissions for the active organization and matches the returned session's organization and Stripe customer to that organization's billing metadata; a supplied session ID or return URL is not authority to access another tenant or evidence of completed payment. Organization switching must discard the prior checkout state.
• External-client audience: OAuth organization membership alone does not substitute for per-operation organization-admin authorization. Keep this interactive payment workflow in the authenticated dashboard rather than exposing checkout client secrets through external MCP. A future bounded, non-sensitive billing inspection/navigation outcome would require its own design and authorization assessment; it is not being added here.
• Managed-assistant audience: exact-project assistant identity is not an organization administrator's payment authority. Do not expand its scope into organization-wide billing or admit payment entry/checkout credentials to assistant tools.
• Evidence and verification boundary: BillingSetup.tsx contains the scope gates and organization-keyed checkout lifecycle; stripe_checkout_status.go enforces organization/customer ownership, with admin/read and foreign-session cases in stripe_checkout_status_test.go. platformmcp/descriptor.go distinguishes external OAuth from project-assistant audiences. The browser review steps above cover payment entry, organization-admin access, redirect recovery, and confirmation. This records the intended design and inspected code/tests, not a claim that new browser checks were run or that the locally rebased changes have been pushed.

---

🚀 Preview Environment (PR #7459)

Preview URL: https://pr-7459.dev.getgram.ai

Component	Status	Details	Updated (UTC)
✅ Database	Ready	Created and validated	2026-10-29 00:19:27.
✅ Images	Available	Container images ready	2026-10-29 00:20:08.

_{Gram Preview Bot}

[changeset-bot]

🦋 Changeset detected

Latest commit: 775b80c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
server	Minor
dashboard	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[linear-code]

GRW-79

[cubic-dev-ai]

All reported issues were addressed across 36 files

<sub>This PR changes payment, billing, or quota logic. Ultrareviews find 2.4x more serious bugs than standard reviews. Comment @cubic-dev-ai ultrareview to run one.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 10 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 36 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>