Skip to content
Create account
 or
Sign in
The Stripe Docs logo
/
Create account
Sign in
Overview
Versioning
Upgrade your API version
Developer tools
Stripe for Visual Studio CodeFile uploadsFeedback
Security
Extend Stripe
Partners
Partner ecosystemPartner certification

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:

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.

ResourcePermissionDescription
Accountconnected_account_readGrants access to read Accounts
Account linkaccount_link_writeGrants access to Account Links
Apple Pay Domainapple_pay_domain_read, apple_pay_domain_writeGrants access to Apple Pay Domain resources. To use Apple Pay, you need to register your web domains with Apple. See domain registration for more information.
Application Feeapplication_fee_read, application_fee_writeGrants access to Application Fees
Balancebalance_readGrants access to Balance

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, transfer_read

Billing clockbilling_clock_read, billing_clock_writeGrants access to Test clocks
Chargecharge_read, charge_writeGrants access to Charges

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, sku_read

Configurationterminal_configuration_read, terminal_configuration_writeGrants access to Configurations
Connection Tokenterminal_connection_token_writeGrants access to Connection Tokens
Couponcoupon_read, coupon_writeGrants access to Coupons

Credit note

credit_note_read, credit_note_write

Grants access to Credit Notes

This permission also implies the following permissions: invoice_read,

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.

Customer

customer_read, customer_write

Grants access to Customers

This permission also implies the following permission: billing_clock_read.

Disputedispute_read, dispute_writeGrants access to Disputes
Edit linkedit_link_writeGrants access to Login Links
Elementselements_writeGrants access to Stripe.js Elements
Eventevent_readGrants access to Events
Filefile_read, file_writeGrants access to Files

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.

Issuing authorizationissuing_authorization_read, issuing_authorization_writeGrants access to Authorizations
Issuing cardissuing_card_read, issuing_card_writeGrants access to Cards
Issuing cardholderissuing_cardholder_read, issuing_cardholder_writeGrants access to Cardholders
Issuing disputeissuing_dispute_read, issuing_dispute_writeGrants access to Issuing Disputes
Issuing transactionissuing_transaction_read, issuing_transaction_writeGrants access to Transactions
Locationterminal_location_read, terminal_location_writeGrants access to Locations
Mandatemandate_read, mandate_writeGrants access to Mandates
Orderorder_read, order_writeGrants access to Orders

Payment intent

payment_intent_read, payment_intent_write

Grants access to PaymentIntents

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

This permission also implies the following permissions: product_read, sku_read

Payment links

payment_links_read, payment_links_write

Grants access to Payment Links

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

Payment method

payment_method_read, payment_method_write

Grants access to PaymentMethods

This permission also implies the following permission: source_read

Payoutpayout_read, payout_writeGrants access to Payouts
Planplan_read, plan_writeGrants access to Plans, Prices, and (implicitly) Products
Productproduct_read, product_writeGrants access to Products
Promotion Codepromotion_code_read, promotion_code_writeGrants access to Promotion Codes

Quote

quote_read, quote_write

Grants access to Quotes

This permission also implies the following permissions: sku_read, product_read

Readerterminal_reader_read, terminal_reader_writeGrants access to Readers
Report Runs and Report Typesreport_runs_and_report_types_readGrants read access to Report Types and allows creation of Report Runs
Reviewreview_read, review_writeGrants access to Reviews
Secretsecret_writeGrants access to Secrets

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

Shipping rateshipping_rate_read, shipping_rate_writeGrants access to Shipping Rates
SKUsku_read, sku_writeGrants access to SKUs
Sourcesource_read, source_writeGrants access to Sources
Subscriptionsubscription_read, subscription_writeGrants access to Subscriptions
Tax ratetax_rate_read, tax_rate_writeGrants access to Tax Rates
Tax settingstax_settings_read, tax_settings_write,Grants access to Tax Settings
Tax transactiontax_calculations_and_transactions_read, tax_calculations_and_transactions_write,Grants access to Tax Calculations and Transactions
Tokentoken_read, token_writeGrants access to Tokens
Top uptop_up_read, top_up_writeGrants access to Top-ups

Transfer

transfer_read, transfer_write

Grants access to Transfers

This permission also implies the following permission: payout_read, payout_write

Usage recordusage_record_read, usage_record_writeGrants access to Usage Records
User Emailuser_email_readGrants access to user emails

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.

Event permissions

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

Loading...

See also

Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our product changelog.
Questions? Contact Sales.
Powered by Markdoc