Stripe Apps
StripeOfficialPublished by Stripe
- Skill
- Tool integration
- Software development
- MIT
- No issues found
AutoGineer summary
Written by AutoGineer from the skill’s own files, not by the author
This skill provides a structured approach to developing and maintaining Stripe Apps. It guides users through selecting the correct extension architecture, implementing authentication, building UI components, and managing backend services or webhooks. By leveraging bundled reference files and canonical documentation, it ensures that app development follows Stripe's best practices for security, configuration, and lifecycle management.
What it does
- Provides guidance on selecting the appropriate Stripe extension interface.
- Assists in building and modifying Stripe Dashboard UI components.
- Supports the implementation of backend services, webhooks, and secret storage.
- Helps determine the correct authentication method for Stripe API access.
- Offers instructions for testing, debugging, and publishing Stripe Apps.
- Clarifies the applicability of extensions for specific billing or workflow requirements.
When to use it
- When you need to build a custom UI extension for the Stripe Dashboard.
- When deciding between Restricted API keys, Platform keys, or OAuth for your app.
- When implementing backend logic or handling Stripe events via webhooks.
- When you need to store sensitive credentials securely using the Secret Store API.
- When troubleshooting or modifying an existing Stripe App's manifest or configuration.
Advantages
- Ensures alignment with official Stripe development patterns and security standards.
- Reduces development time by providing clear paths to relevant documentation.
- Helps prevent common architectural errors in app authentication and event handling.
- Provides a consistent workflow for the entire app lifecycle from scaffolding to release.
Usage examples
- “How do I determine if my Stripe App needs a backend?”
- The agent will reference the backend documentation to explain that a backend is required for long-term data storage, server-side secrets, or handling webhooks, while suggesting the Secret Store API for simpler needs.
- “Help me choose the right authentication type for a private Stripe App.”
- The agent will compare Restricted API keys, Platform keys, and OAuth, recommending Restricted API keys as the simplest and most secure choice for private integrations.
Install
Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/stripe/stripe-apps/downloadUnzip it into the cross-client skills folder of your project:
mkdir -p .agents/skills && unzip stripe-apps.zip -d .agents/skills
Documentation by Stripe
Stripe Apps
Select and read the existing guidance for the user’s task. Product documentation describes what an extension can do; implementation guides describe how to build it. Before recommending an extension or writing code, load the applicable bundled reference files as well as the relevant product documentation. A link or filename in this skill isn’t a substitute for reading its contents.
For a capability question, check native Stripe features and the documented applicability and limitations of the extension. For an implementation request, create or modify working files using the selected guide. For an existing app, inspect its manifest, packages, installed SDK, and local agent instructions before deciding what to change.
Choose the relevant documentation
Use information already supplied by the user or existing app. Read <references/discovery.md> when you need to clarify the app’s requirements, and <references/extension-types.md> for an overview of app architectures. Ask only for missing information that affects the task.
Product capabilities
Use these existing product documents to determine which capability fits and whether the account has the required access. Don’t infer support from an extension’s name or the existence of a scaffold.
| Task | Read |
|---|---|
| Select an extension interface and its supported implementation types | Extension points and how extensions work |
| Change how items are included on subscription invoices | Item handling extensions |
| Customize prorations | Native proration behavior and prorations extensions |
| Apply customer balances | Customer balance extensions |
| Calculate discount amounts | Discount calculation extensions |
| Add an action to Stripe Workflows | Existing workflow actions, existing custom actions, and how custom actions work |
| Customize another product’s behavior | Follow the selected interface’s product documentation from the extension-point catalog |
Implementation guidance
The references/*.md files are bundled with this skill. After selecting the capability, load the applicable files before following their links to supporting documentation. Combine rows when an app needs multiple types. Follow the selected guide’s prerequisites, scaffolding, testing, and debugging instructions.
| Task | Read |
|---|---|
| Build or modify any Dashboard UI, including drawers and full-page apps | <references/ui-extensions.md>, then each selected component’s current API documentation |
| Author, test, or debug a script extension | <references/script-extensions.md>, then the selected extension point’s implementation guide |
| Build a custom-action script | <references/script-extensions.md> and build a custom action with a script |
| Build a custom-action remote function | Build a custom action with a remote function |
| Build a self-hosted UI back-end or webhook service | <references/backend.md> and <references/authentication.md>; also load <references/webhooks.md> when receiving Stripe events |
| Store app credentials with the Secret Store API | The Secret Store API section in <references/backend.md> and store secrets, including for apps without a self-hosted back-end |
| Look up APIs, SDK patterns, configuration, or additional extension documentation | <references/canonical-docs.md> |
Use the UI reference for layout and composition, and current component documentation for import paths, props, and styling APIs. For scripts and remote functions, follow the selected extension’s documentation; UI and self-hosted back-end instructions don’t define their runtime capabilities.
Shared app lifecycle
Read these references when the corresponding task is needed. Reuse existing apps and packages; scaffold only what is missing.
| Task | Read |
|---|---|
| Scaffold, build, test, preview, or upload an app | <references/workflow.md>, together with the selected implementation guide |
| Choose authentication for access to Stripe APIs | <references/authentication.md> |
| Receive Stripe events | <references/webhooks.md> |
| Build a first-run setup experience | <references/onboarding-ux.md> and the UI reference |
| Release versions, change installed permissions, or publish to the marketplace | <references/publishing.md> |
| Submit feedback after running app toolchain commands | <references/feedback.md> |
Load bundled reference files
Use the task tables to select every applicable bundled reference under
references/, then open those files with a file-reading tool before starting the corresponding work. For example, UI with a self-hosted back-end needs both UI and back-end guidance; onboarding also needs the UI reference.Follow relevant pointers to other bundled references inside the files you load, including filenames written as code rather than links. For example, back-end guidance can require authentication guidance, and changing permissions can require publishing guidance. Use this skill’s direct links to locate those files.
Read the canonical documentation required by those references. External documentation supplements the bundled guidance on workflow, layout, and other task-specific decisions.
Resolve
references/paths relative to this skill’s directory and bare reference filenames relative to itsreferences/directory. When reading the hosted skill, fetch the corresponding reference URLs relative to the skill URL.Load only references relevant to the task, and reuse contents already read during the session unless they have changed. A full-stack app doesn’t require every document in the skill.
Read canonical pages using the available documentation tools. Prefer
stripe docswhen available, including for pages that require account access.Use current product documentation and the installed SDK’s types for API contracts and limitations. If an example in a reference disagrees, check the version and follow the applicable canonical documentation.
Read any interface-specific agent instructions supplied with an existing or newly generated extension. If none are present, use the linked product and implementation guides.
If the documentation doesn’t establish that an extension meets a requirement, state what is unknown or unsupported before proceeding.
Keep the work within the user’s request. Report the changes, validation results, and remaining steps relevant to that app.
Files
- ATTRIBUTION.mdAdded by AutoGineer819 B
- LICENSELicence file added by AutoGineer1.1 KiB
- SKILL.md7.6 KiB
- references/authentication.md4.6 KiB
- references/backend.md4.4 KiB
- references/canonical-docs.md4.4 KiB
- references/discovery.md9.2 KiB
- references/extension-types.md5.1 KiB
- references/feedback.md1.9 KiB
- references/onboarding-ux.md2.7 KiB
- references/publishing.md5.7 KiB
- references/script-extensions.md7.3 KiB
- references/ui-extensions.md20.7 KiB
- references/webhooks.md3.4 KiB
- references/workflow.md8.3 KiB
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 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 releaseYou 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 permissionsBump 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 can’t 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 (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:
Read the full error message — it usually says exactly what’s wrong
Run
pnpm buildto check for TypeScript/build errors locallyValidate 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 sandboxUpload and install your app in the sandbox to test the full install flow
When ready, upload to your main account for production use
Requirements and compatibility
Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta
“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.
Security
No issues found by our static scan· No issues found
A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.
Attribution and licence
- Published by
- Stripe
- Publisher
- Stripe (Official)
- Source
- stripe/ai · skills/stripe-apps · commit 38fa045
- Licence
- MIT License (redistribution allowed)
- LICENSE (added by AutoGineer from LICENSE)
- ATTRIBUTION.md (written by AutoGineer)
- Synced
- Also distributed in
- stripe/ai, stripe/ai, stripe/ai, stripe/ai, stripe/ai
AutoGineer is not affiliated with or endorsed by Stripe.
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download stripe-apps.zip