Setting the file. One moment.
Subchapter 2.7
references/publishing.mdMarkdown6 KBView on GitHub
How to version, release, and publish your Stripe App.
Plain-language: “Test mode uses fake data so you can try things safely. Live mode uses real customer data. Always build and test in test mode first.”
| Mode | Data | When to use |
|---|---|---|
| Test mode | Fake (test cards, test customers) | Development and QA |
| Live mode | Real customer and payment data | Production |
Workflow: Upload → install in test mode → test thoroughly → install in live mode.
Do not skip test mode testing. Even if your app looks correct locally with stripe apps start, you must install it in test mode and verify it works with the actual install flow before going live.
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 featureRules:
2.0.0 before 1.0.0, 2.0.0 won’t be available for release# 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" (test mode) or "Release" (live mode)This is a common source of bugs. When you add new permissions:
stripe-app.yaml with the new permissionsAlways 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.
For public apps — making your app available to all Stripe users.
Before submitting:
Stripe reviews your app for security, functionality, and compliance with their guidelines.
Your app appears in the Stripe Apps Marketplace (opens in a new tab). Any Stripe user can install it.
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:
pnpm build to check for TypeScript/build errors locallystripe apps upload --verbose for detailed outputSandboxes provide isolated environments for safe app development and testing.
Benefits of using Sandboxes:
How to use:
stripe apps start targeting the sandbox