AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

stripe-apps

Build, modify, or review Stripe Apps and extensions using the relevant documentation and reference guides. Use for custom Stripe Dashboard UI, stripe-app.yaml, @stripe/ui-extension-sdk, @stripe/extensibility-sdk, script extensions, extension interfaces, custom workflow actions, and apps that authenticate to Stripe or react to events. Also use when deciding whether a Stripe extension can support the user's billing or workflow requirements.

Original source
stripe
License
MIT
Pinned revision
1e24cf59cb0dd78df298afc3b7d372e5a5055ece

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read stripe--stripe-apps at revision 1e24cf59cb0dd78df298afc3b7d372e5a5055ece, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 13

references/publishing.md

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.

Don’t 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 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" 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 can’t 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 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 (for example, 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