famdone/.agents/skills/stripe-apps/references/publishing.md

Publishing — versioning, releases, test vs live mode, marketplace

Publishing

How to version, release, and publish your Stripe App.

Test mode vs live mode

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.

Versioning

Bump version in stripe-app.yaml before each upload:

id: com.example.my-app
version: 1.0.1
name: My App

Use semantic versioning:

• 1.0.0 — initial release
• 1.0.1 — bug fix
• 1.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.0 before 1.0.0, 2.0.0 won’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" (test mode) or "Release" (live mode)

When you change permissions

This is a common source of bugs. When you add new permissions:

1. Update stripe-app.yaml with the new permissions
2. Bump the version and upload
3. Existing users are notified by email
4. The “Review Permissions” button appears — but only on the Apps workload page (dashboard.stripe.com/apps), not on the app itself
5. 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

1. Go to Dashboard → Apps
2. Select your app
3. Click Submit for review

Stripe reviews your app for security, functionality, and compliance with their guidelines.

Review requirements overview

• App must work correctly in test 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:

1. Read the full error message — it usually says exactly what’s wrong
2. Run pnpm build to check for TypeScript/build errors locally
3. Validate your stripe-app.yaml has all required fields (id, version, name, declarations)
4. Check that file paths match (ui/src/views/App.tsx, not a renamed file)
5. If still stuck: stripe apps upload --verbose for 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:

1. Create a sandbox from Dashboard → Sandboxes
2. Run stripe apps start targeting the sandbox
3. Upload and install your app in the sandbox to test the full install flow
4. When ready, upload to your main account for production use