Checkout / billing portal BIL-03
Hand off to Stripe in the browser and confirm the result on return.
| Who can use it | Self (individual); org_admin (org checkout); org_admin or billing.manage (org portal) |
|---|---|
| Where it is | /billing/return · link: https://hub.substratalapps.com/billing/return or substratal://billing/return |
| Available on | Web (PWA), iOS / iPadOS, Android, Windows, Linux (GNOME), macOS |
| Phase | Phase 2 |
What you can do here
- Upgrade (individual) — 201 {url, expires_at} → open url externally. 409 subscription_exists → open portal instead. 409 test_mode_billing_unavailable / 503 billing_unavailable → explain.
- Manage billing (individual) — 201 → open url externally. 409 no_billing_account → hide button.
- Subscribe organization — as individual
- Manage organization billing — as individual
- Return — success: poll the matching GET …/subscription until plan = standard (coverage starts when Stripe's webhook lands, usually seconds); cancelled: toast "Checkout cancelled"
Related guides
- Organizations, plans and billing — Free and Standard, organizations, seats, and who pays.
On your platform
| App | Status | How it's built |
|---|---|---|
| Web (PWA) | — | window.open (new tab) / same-tab redirect for PKCE |
| iOS / iPadOS | — | openURL / ASWebAuthenticationSession |
| Android | Planned | Custom Tabs / Auth Tab |
| Windows | — | Launcher.LaunchUriAsync |
| Linux (GNOME) | — | GtkUriLauncher (OpenURI portal) |
| macOS | — | NSWorkspace.open / ASWebAuthenticationSession |
Status is reported by each app's repository; — means that app doesn't report it yet.
For developers: API calls
| Method | Path | What it does |
|---|---|---|
| POST | /users/me/billing/checkout-sessions | Start a Stripe Checkout to subscribe yourself to Standard (User token) |
| POST | /users/me/billing/portal-sessions | Open the Stripe Customer Portal for your own subscription (User token) |
| POST | /organizations/{id}/billing/checkout-sessions | Start a Stripe Checkout to subscribe the Organization to Standard (org admin, User token) |
| POST | /organizations/{id}/billing/portal-sessions | Open the Stripe Customer Portal for the Organization's subscription (org admin or billing.manage, User token) |
Every call sends Substratal-Version: 1. Paths are at the host root, with no /v1.