Publishing — versioning, releases, sandboxes, live mode, marketplace
Publishing
How to version, release, and publish your Stripe App.
Sandboxes and live mode
Plain-language: “A sandbox uses test data so you can try things safely. Live mode uses real customer data. Always build and test in a sandbox first.”
| Mode | Data | When to use |
|---|---|---|
| Sandbox | Test data (test cards, test customers) | Development and QA |
| Live mode | Real customer and payment data | Production |
Workflow: Upload → install in a sandbox → test thoroughly → install in live mode.
Do not skip sandbox testing. Even if your app looks correct locally with stripe apps start, you must install it in a sandbox and verify it works with the actual install flow before going live.
Versioning
Bump version in stripe-app.yaml before each upload:
id: com.example.my-app
version: 1.0.1
name: My AppUse semantic versioning:
1.0.0— initial release1.0.1— bug fix1.1.0— new feature (backward compatible)2.0.0— breaking change or major feature
Rules:
- Versions must be uploaded in order — if you upload
2.0.0before1.0.0,2.0.0won’t be available for release - You can have multiple uploaded versions; you choose which one to install
- Stripe auto-upgrades installed users to the latest release — they don’t need to do anything unless you changed permissions
Upload and release workflow
# 1. Bump version in stripe-app.yaml, then:
stripe apps upload
# 2. Go to Dashboard → Apps → your app → version history
# 3. Click the version you want to release
# 4. Click "Set as external test version" or "Release" (live mode)When you change permissions
This is a common source of bugs. When you add new permissions:
- Update
stripe-app.yamlwith the new permissions - Bump the version and upload
- Existing users are notified by email
- The “Review Permissions” button appears — but only on the Apps workload page (dashboard.stripe.com/apps), not on the app itself
- The app returns an invalid-request error for the new permissions until the user clicks “Review Permissions” and re-authorizes
Always warn users about this step when you change permissions. Many users miss the notification and think the app is broken.
How to notify users: Consider adding a banner in your app UI that detects when a required permission is missing and guides the user to re-authorize.
Publishing to the Stripe Apps Marketplace
For public apps — making your app available to all Stripe users.
Requirements
Before submitting:
- Verified email address on your Stripe account
- Business details filled in (legal name, address)
- App passes review requirements
- Connect platform accounts cannot publish marketplace apps
Submission
- Go to Dashboard → Apps
- Select your app
- Click Submit for review
Stripe reviews your app for security, functionality, and compliance with their guidelines.
Review requirements overview
- App must work correctly in supported sandboxes and live mode
- No prohibited content or misleading claims
- Privacy policy URL required
- Support contact required
- App icon and screenshots required
After approval
Your app appears in the Stripe Apps Marketplace. Any Stripe user can install it.
Troubleshooting uploads
Successful upload looks like:
Uploading... Done
Your app has been uploaded to version 0.0.1.Common upload failures and fixes:
| Error | Cause | Fix |
|---|---|---|
Invalid manifest / validation failed |
Missing required fields or malformed YAML | Check indentation; ensure id:, version:, name: are present |
Build failed / TypeScript errors |
UI component has type/import errors | Run pnpm build locally first to see the exact error |
Version already exists |
Already uploaded this version number | Bump version in stripe-app.yaml (e.g. 0.0.1 → 0.0.2) |
Permission denied / Not authenticated |
CLI not logged in or wrong account | Run stripe login and verify with stripe config --list |
connect-src / CSP error |
App calls a URL not declared in content_security_policy | Add the URL to content_security_policy.connect-src in stripe-app.yaml |
extensions field required |
Missing extensions: [] in stripe-app.yaml |
Add extensions: [] even if you have no backend extensions |
Component not found |
Viewport references a component name that doesn’t match your export | Ensure component: in stripe-app.yaml matches your default export name |
Debugging steps when upload fails:
- Read the full error message — it usually says exactly what’s wrong
- Run
pnpm buildto check for TypeScript/build errors locally - Validate your stripe-app.yaml has all required fields (id, version, name, declarations)
- Check that file paths match (ui/src/views/App.tsx, not a renamed file)
- If still stuck:
stripe apps upload --verbosefor detailed output
Sandboxes for app development
Sandboxes provide isolated environments for safe app development and testing.
Benefits of using Sandboxes:
- Isolated from your live account — test destructive operations safely
- Each sandbox has its own app installation and signing secrets
- Useful for testing onboarding flows, uninstall/reinstall cycles, and permission changes
How to use:
- Create a sandbox from Dashboard → Sandboxes
- Run
stripe apps starttargeting the sandbox - Upload and install your app in the sandbox to test the full install flow
- When ready, upload to your main account for production use