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 health alertsBuild with LLMsStripe for Visual Studio CodeFile uploads
Security
Extend Stripe
Partners
Partner certification

Permissions reference

A list of available events and their required permissions.

Copy page

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

Account

connected_account_readGrants access to read Accounts

Account link

account_link_writeGrants access to Account Links

Apple Pay Domain

apple_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 Fee

application_fee_read, application_fee_writeGrants access to Application Fees

Balance

balance_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 clock

billing_clock_read, billing_clock_writeGrants access to Test clocks

Billing meter

billing_meter_read, billing_meter_writeGrants access to Billing meters

Billing meter events

billing_meter_event_read, billing_meter_event_writeGrants access to Billing meter events

Charge

charge_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

Configuration

terminal_configuration_read, terminal_configuration_writeGrants access to Configurations

Confirmation Token

confirmation_token_readGrants read access to Confirmation Tokens

Confirmation Token (client)

confirmation_token_client_writeGrants write access to Confirmation Tokens from the client.

Connection Token

terminal_connection_token_writeGrants access to Connection Tokens

Coupon

coupon_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.

Dispute

dispute_read, dispute_writeGrants access to Disputes

Edit link

edit_link_writeGrants access to Login Links

Elements

elements_writeGrants access to Stripe.js Elements

Entitlements

entitlement_readGrants access to Entitlements

Event

event_readGrants access to Events

File

file_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 authorization

issuing_authorization_read, issuing_authorization_writeGrants access to Authorizations

Issuing card

issuing_card_read, issuing_card_writeGrants access to Cards

Issuing cardholder

issuing_cardholder_read, issuing_cardholder_writeGrants access to Cardholders

Issuing dispute

issuing_dispute_read, issuing_dispute_writeGrants access to Issuing Disputes

Issuing transaction

issuing_transaction_read, issuing_transaction_writeGrants access to Transactions

Location

terminal_location_read, terminal_location_writeGrants access to Locations

Mandate

mandate_read, mandate_writeGrants access to Mandates

Order

order_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

Payout

payout_read, payout_writeGrants access to Payouts

Plan

plan_read, plan_writeGrants access to Plans, Prices, and (implicitly) Products

Product

product_read, product_writeGrants access to Products

Promotion Code

promotion_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

Reader

terminal_reader_read, terminal_reader_writeGrants access to Readers

Report Runs and Report Types

report_runs_and_report_types_readGrants read access to Report Types and allows creation of Report Runs

Review

review_read, review_writeGrants access to Reviews

Secret

secret_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 rate

shipping_rate_read, shipping_rate_writeGrants access to Shipping Rates

SKU

sku_read, sku_writeGrants access to SKUs

Source

source_read, source_writeGrants access to Sources

Subscription

subscription_read, subscription_writeGrants access to Subscriptions

Tax rate

tax_rate_read, tax_rate_writeGrants access to Tax Rates

Tax settings

tax_settings_read, tax_settings_write,Grants access to Tax Settings

Tax transaction

tax_calculations_and_transactions_read, tax_calculations_and_transactions_write,Grants access to Tax Calculations and Transactions

Token

token_read, token_writeGrants access to Tokens

Top up

top_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 record

usage_record_read, usage_record_writeGrants access to Usage Records

User Email

user_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 changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc