Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Revenue
Platforms and marketplaces
Money management
Developer resources
Overview
Versioning
Changelog
Upgrade your API version
Upgrade your SDK version
Essentials
SDKs
API
Testing
Stripe CLI
Sample projects
Tools
Workbench
Developers Dashboard
Stripe Shell
Stripe for Visual Studio Code
Features
Workflows
Event destinations
Stripe health alertsFile uploads
AI solutions
Agent toolkit
Model Context Protocol
Security and privacy
Security
Stripebot web crawler
Privacy
Extend Stripe
Build Stripe apps
    Overview
    Get started
    Create an app
    How Stripe Apps work
    Sample apps
    Build an app
    Store secrets
    API authentication methods
    Authorization flows
    Server-side logic
    Listen to events
    Handle different modes
    Enable sandbox support
    App settings page
    Build a UI
    Onboarding
    Distribute your app
    Distribution options
    Upload your app
    Versions and releases
    Test your app
    Publish your app
    Promote your app
    Add deep links
    Create install links
    Assign roles in UI extensions
    Post-install actions
    App analytics
    Embedded components
    Embed third-party Stripe Apps
    Migrating to Stripe Apps
    Migrate or build an extension
    Migrate a plugin to Stripe Apps or Stripe Connect
    Reference
    App manifest
    CLI
    Extension SDK
    Permissions
    Viewports
    Design patterns
    Components
Use apps from Stripe
Partners
Partner ecosystem
Partner certification
HomeDeveloper resourcesBuild Stripe apps

Permissions reference

A list of available events and their required permissions.

A Stripe App needs permission to read or write user data. This includes these situations:

  • Accessing Stripe API objects—see Object permissions
  • Subscribing to events—see Event permissions

To request permissions, list them in the permissions array in your app manifest file. You can also manage this array from the CLI. Account administrators that install your app must accept the permissions that you list before using it.

If your app performs an action it lacks permissions for, Stripe might raise an invalid request error.

Manage permissions

You can add a permission to the permissions array in your stripe-app.json app manifest file using the following command:

Command Line
stripe apps grant permission "PERMISSION_NAME" "EXPLANATION"

Replace:

  • PERMISSION_NAME with the permission name. You can find permission names for objects and events in the sections below.
  • EXPLANATION with an explanation for enabling access. Users see this explanation when they install your app.

Repeat this step for each permission that you want to add to your application.

For example, after you add the customer_read permission, your app manifest file might look like this:

stripe-app.json
{ "id": "com.example.app", "version": "1.2.3", "name": "Example App", "icon": "./example_icon_32.png", "permissions": [ { "permission": "customer_read", "purpose": "Receive access to the customer’s phone number" } ], }

To remove a permission, you can also use the CLI:

Command Line
stripe apps revoke permission "PERMISSION_NAME"

Object permissions

For each API object your app reads or writes, it must request at least one of the corresponding permissions.

If you’re expanding objects in the responses of your API requests, you must also request at least one corresponding permission for each API object you expand.

ProductResourcePermissionDescription
CoreBalance balance_readGrants access to Balances.

Core

Balance Transaction Source

balance_transaction_source_read

Grants access to expand the source attribute when retrieving Balance Transactions.

This permission also implies the following permissions: application_fee_read, balance_read, and transfer_read.

CoreCharge
  • charge_read
  • charge_write
Grants access to Charges.
CoreConfirmation Token (client) confirmation_token_client_writeGrants write access to Confirmation Tokens from the client.
CoreConfirmation Token confirmation_token_readGrants read access to Confirmation Tokens.

Core

Customer

  • customer_read
  • customer_write

Grants access to Customers.

This permission also implies the following permission: billing_clock_read.

CoreDispute
  • dispute_read
  • dispute_write
Grants access to Disputes.
CoreElements elements_writeGrants access to Stripe.js Elements.
CoreEvent event_readGrants access to Events.
CoreFile
  • file_read
  • file_write
Grants access to Files.
CoreMandate
  • mandate_read
  • mandate_write
Grants access to Mandates.

Core

Payment Intent

  • payment_intent_read
  • payment_intent_write

Grants access to Payment Intents.

If you’re managing Payment Intents with Stripe.js Elements, you must also request elements_write.

This permission also implies the following permissions: product_read and sku_read.

Core

Payment Links

  • payment_links_read
  • payment_links_write

Grants access to Payment Links.

This permission also implies the following permissions: mandate_read, product_read and sku_read.

Core

Payment Method

  • payment_method_read
  • payment_method_write

Grants access to Payment Methods.

This permission also implies the following permission: source_read

CorePayment Method Domain
  • payment_method_domain_read
  • payment_method_domain_write
Grants access to Payment Method Domains.
CorePayout
  • payout_read
  • payout_write
Grants access to Payouts.
CoreProduct
  • product_read
  • product_write
Grants access to Products.

Core

Setup Intent

  • setup_intent_read
  • setup_intent_write

Grants access to SetupIntents.

If you’re managing SetupIntents with Stripe.js Elements, you must also request elements_write.

This permission also implies the following permission: mandate_read.

CoreShipping Rate
  • shipping_rate_read
  • shipping_rate_write
Grants access to Shipping Rates.
CoreSource
  • source_read
  • source_write
Grants access to Sources.
CoreToken
  • token_read
  • token_write
Grants access to Tokens.

Checkout

Checkout Session

  • checkout_session_read
  • checkout_session_write

Grants access to Sessions.

This permission also implies the following permissions: mandate_read, payment_intent_read, payment_links_read, product_read, setup_intent_read and sku_read.

BillingTest clock
  • billing_clock_read
  • billing_clock_write
Grants access to test clocks.
BillingMeter
  • billing_meter_read
  • billing_meter_write
Grants access to Meters.
BillingMeter events
  • billing_meter_event_read
  • billing_meter_event_write
Grants access to meter events.
BillingCoupon
  • coupon_read
  • coupon_write
Grants access to Coupons.

Billing

Credit note .

  • credit_note_read
  • credit_note_write

Grants access to Credit Notes.

This permission also implies the following permissions: invoice_read.

Billing

Customer portal

  • customer_portal_read
  • customer_portal_write

Grants access to the customer portal.

If you’re using the customer portal to manage subscriptions or payment methods, you must also request elements_write.

BillingEntitlements entitlement_readGrants access to Entitlements.

Billing

Invoice

  • invoice_read
  • invoice_write

Grants access to Invoices.

This permission also implies the following permission: credit_note_read.

If you’re using the hosted invoice page to manage invoices or payment methods, you must also request elements_write. –

BillingPlan
  • plan_read
  • plan_write
Grants access to Plans, Prices, and (implicitly) Products.
BillingPromotion Code
  • promotion_code_read
  • promotion_code_write
Grants access to Promotion Codes.

Billing

Quote

  • quote_read
  • quote_write

Grants access to Quotes.

This permission also implies the following permissions: sku_read and product_read.

BillingSubscription
  • subscription_read
  • subscription_write
Grants access to Subscriptions.
BillingTax rate
  • tax_rate_read,
  • tax_rate_write
Grants access to Tax Rates.
BillingUsage record
  • usage_record_read
  • usage_record_write
Grants access to Usage Records.
ReportingReport Runs and Report Types report_runs_and_report_types_readGrants read access to Report Types and allows creation of Report Runs.
ConnectAccount connected_account_readGrants access to read Accounts.
ConnectAccount link account_link_writeGrants access to Account Links.
ConnectApplication Fee
  • application_fee_read
  • application_fee_write
Grants access to Application Fees.
ConnectLogin link edit_link_writeGrants access to Login Links.
ConnectTop-up
  • top_up_read
  • top_up_write
Grants access to Top-ups.

Connect

Transfer

  • transfer_read
  • transfer_write

Grants access to Transfers.

This permission also implies the following permission: payout_read and payout_write.

IssuingIssuing authorization
  • issuing_authorization_read
  • issuing_authorization_write
Grants access to Authorizations.
IssuingIssuing card
  • issuing_card_read
  • issuing_card_write
Grants access to Cards.
IssuingIssuing cardholder
  • issuing_cardholder_read
  • issuing_cardholder_write
Grants access to Cardholders.
IssuingIssuing dispute
  • issuing_dispute_read
  • issuing_dispute_write
Grants access to Issuing Disputes.
IssuingIssuing transaction
  • issuing_transaction_read
  • issuing_transaction_write
Grants access to Transactions.
TerminalConfiguration
  • terminal_configuration_read
  • terminal_configuration_write
Grants access to Configurations.
TerminalConnection Token terminal_connection_token_writeGrants access to Connection Tokens.
TerminalLocation
  • terminal_location_read
  • terminal_location_write
Grants access to Locations.
TerminalReader
  • terminal_reader_read
  • terminal_reader_write
Grants access to Readers.
TaxTax settings
  • tax_settings_read
  • tax_settings_write
Grants access to Tax Settings.
TaxTax transaction
  • tax_calculations_and_transactions_read
  • tax_calculations_and_transactions_write
Grants access to Tax Calculations and Transactions.
RadarReview
  • review_read
  • review_write
Grants access to Reviews.
Stripe AppsSecret secret_writeGrants access to Secrets.
Stripe AppsUser Email user_email_readGrants access to user emails.

Webhooks

Webhook

  • webhook_read
  • webhook_write

Grants access to Webhook Endpoints.

For most apps, you don’t need to includewebhook_write. Instead, set up a webhook to listen to events from your connected accounts. If you still need webhook_write, contact Stripe Support.

OrdersOrder
  • order_read
  • order_write
Grants access to Orders.
OrdersSKU
  • sku_read
  • sku_write
Grants access to SKUs.

Event permissions

For each Event your app subscribes to, it must request at least one of the corresponding permissions.

Loading...

See also

  • App manifest reference
  • How UI extensions work
Was this page helpful?
YesNo
  • Need help? Contact Support.
  • Join our early access program.
  • Check out our changelog.
  • Questions? Contact Sales.
  • LLM? Read llms.txt.
  • Powered by Markdoc