Permissions reference

A list of available events and their required permissions.

Use the Accounts v2 API to represent customers

The Accounts v2 API is generally available for Connect users, and in public preview for other Stripe users. If you’re part of the Accounts v2 preview, you need to specify a preview version in your code.

To join the Accounts v2 preview, go to Account previews and features in your Dashboard and enable Reusable payment methods for Global Payouts.

For most use cases, we recommend modeling your customers as customer-configured Account objects instead of using Customer objects.

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:

the related setting _ the related setting with the permission name. You can find permission names for objects and events in the sections below.
the related setting 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.

Product	Resource	Permissions	Description

Billing	Billing Meter Events	`billing_meter_event_read` `billing_meter_event_write`	Billing Meter Events are individual usage records reported against a meter. Read access lets you list events. Write access lets you report new usage events. See Billing Meter Events.
Billing	Billing Meters	`billing_meter_read` `billing_meter_write`	Billing Meters track usage events for usage-based billing. Read access lets you list meters and view their configurations. Write access lets you create and update meters. See Billing Meters.
Billing	Coupons	`coupon_read` `coupon_write`	Coupons define discounts that can be applied to subscriptions or invoices. Read access lets you list and retrieve coupons. Write access lets you create, update, and delete coupons. See Coupons.
Billing	Credit Notes	`credit_note_read` `credit_note_write`	Credit Notes are documents that reduce the amount owed on an invoice. Read access lets you list and retrieve credit notes. Write access lets you create and void credit notes. See Credit Notes.
Billing	Customer Portal	`customer_portal_read` `customer_portal_write`	Customer Portal provides a Stripe-hosted page where customers manage their subscriptions and billing details. Read access lets you retrieve portal configurations. Write access lets you create and update portal settings. See Customer Portal. If you're using the customer portal to manage subscriptions or payment methods, you must also request `elements_write`.
Billing	Entitlements	`entitlement_read`	Entitlements define feature access granted to customers through their subscriptions. Read access lets you check customer entitlements. See Entitlements.
Billing	Invoices	`invoice_read` `invoice_write`	Invoices are statements of amounts owed by a customer. Read access lets you list and retrieve invoice details. Write access lets you create, finalize, and void invoices. See Invoices. If you're using the hosted invoice page to manage invoices or payment methods, you must also request `elements_write`.
Billing	Prices	`plan_read` `plan_write`	Prices define how much and how often to charge for products. Read access lets you list, retrieve, and search prices. Write access lets you create, update, and delete prices. See Prices.
Billing	Promotion Codes	`promotion_code_read` `promotion_code_write`	Promotion Codes are customer-facing codes that apply coupon discounts. Read access lets you list and retrieve codes. Write access lets you create, update, and deactivate promotion codes. See Promotion Codes.
Billing	Quotes	`quote_read` `quote_write`	Quotes are proposals for recurring or one-time purchases sent to customers for acceptance. Read access lets you list and retrieve quotes. Write access lets you create, finalize, and accept quotes. See Quotes.
Billing	Subscriptions	`subscription_read` `subscription_write`	Subscriptions let you charge a customer on a recurring basis. Read access lets you list and retrieve subscription details. Write access lets you create, update, pause, and cancel subscriptions. See Subscriptions.
Billing	Tax Rates	`tax_rate_read` `tax_rate_write`	Tax Rates define percentage-based tax amounts applied to invoices and subscriptions. Read access lets you list and retrieve tax rates. Write access lets you create, update, and copy tax rates. See Tax Rates.
Billing	Test Clocks	`billing_clock_read` `billing_clock_write`	Test Clocks simulate the passage of time for testing subscription billing behavior. Read access lets you retrieve clock status. Write access lets you create and advance test clocks. See Test Clocks.
Billing	Usage Records	`usage_record_read` `usage_record_write`	Usage Records report customer consumption for metered billing on subscription items. Read access lets you retrieve usage data. Write access lets you create usage records. See Usage Records.
Checkout Sessions	Checkout Sessions	`checkout_session_read` `checkout_session_write`	Checkout Sessions power Stripe's prebuilt payment page for collecting payments. Read access lets you retrieve session details, line items, and related payment information. Write access lets you create checkout sessions, configure payment options, and expire active sessions. See Checkout Sessions.
Commerce	Product Catalog Imports	`product_catalog_import_read` `product_catalog_import_write`	Product Catalog Imports enable bulk uploading products and prices into your catalog. Read access lets you view import status. Write access lets you create and manage imports. See Product Catalog Imports.
Connect	Account Links	`account_link_write`	Account Links are short-lived URLs that redirect connected account holders to Stripe-hosted onboarding or management pages. Write access lets you create account links. See Account Links.
Connect	Application Fees	`application_fee_read` `application_fee_write`	Application Fees are charges collected by platforms on payments made through connected accounts. Read access lets you list and retrieve fee details. Write access lets you create refunds on application fees. See Application Fees.
Connect	Capital Financing Offers	`capital_for_platforms_financing_offer_read` `capital_for_platforms_financing_offer_write`	Financing Offers are Capital loan offers extended to connected accounts. Read access lets you list and retrieve offers. Write access lets you manage offer configurations. See Capital Financing Offers.
Connect	Capital Financing Summaries	`capital_for_platforms_financing_summary_read`	Financing Summaries provide an overview of a connected account's active financing, including outstanding balance and repayment progress. Read access lets you retrieve summaries. See Capital Financing Summaries.
Connect	Capital Financing Transactions	`capital_for_platforms_financing_transaction_read`	Financing Transactions record individual repayments and disbursements related to Capital financing. Read access lets you list and retrieve transactions. See Capital Financing Transactions.
Connect	Login Links	`edit_link_write`	Login Links generate single-use URLs for connected account holders to access their Express dashboard. Write access lets you create login links. See Login Links.
Connect	Top-Ups	`top_up_read` `top_up_write`	Top-ups add funds to your Stripe balance from a bank account. Read access lets you list and retrieve top-ups. Write access lets you create and cancel top-ups. See Top-Ups.
Connect	Transfers	`transfer_read` `transfer_write`	Transfers move funds from your Stripe account to a connected account. Read access lets you list and retrieve transfer details. Write access lets you create, update, cancel, and reverse transfers. See Transfers.
Core	Accounts	`connected_account_read`	Accounts represent Stripe accounts or connected accounts on your platform. Read access lets you retrieve account details and settings. Write access lets you update account information. See Accounts.
Core	Apple Pay Domains	`apple_pay_domain_read` `apple_pay_domain_write`	Apple Pay Domains are web domains registered for Apple Pay. Read access lets you list registered domains. Write access lets you register and delete domains. See Apple Pay Domains.
Core	Balance	`balance_read`	Balance represents the current funds available in your Stripe account. Read access lets you retrieve your current balance and pending amounts. See Balance.
Core	Balance Transaction Sources	`balance_transaction_source_read`	Balance Transaction Sources are the underlying objects (Charges, Refunds, and Transfers) that create Balance Transactions. Read access lets you expand the source attribute when retrieving Balance Transactions. This also implies Application Fees (Read), Balance (Read), Financing Transactions (Read), Payouts (Read), Transfers (Read), and Balance Transfers (Read). See Balance Transaction Sources.
Core	Charges and Refunds	`charge_read` `charge_write`	Charges represent completed or attempted payments, and Refunds return funds to a customer. Read access lets you list and retrieve charges and refunds. Write access lets you create, update, capture, and redact charges, and create, update, and cancel refunds. See Charges and Refunds.
Core	Client Confirmation Tokens	`confirmation_token_client_read` `confirmation_token_client_write`	Client Confirmation Tokens enable creating and reading tokens from the client during checkout flows. Write access lets you create tokens from the client side. See Client Confirmation Tokens.
Core	Confirmation Tokens	`confirmation_token_read`	Confirmation Tokens securely pass payment details from the client to your server for confirming payments. Read access lets you retrieve token details server-side. See Confirmation Tokens.
Core	Customer Sessions	`customer_session_read` `customer_session_write`	Customer Sessions enable authenticated customer interactions with embedded components. Read access lets you retrieve session details. Write access lets you create sessions. See Customer Sessions.
Core	Customers	`customer_read` `customer_write`	Customers store payment methods and transaction history for repeat buyers. Read access lets you list and retrieve customer details. Write access lets you create, update, and delete customers. See Customers.
Core	Events	`event_read`	Events represent changes to Stripe objects, delivered via webhooks. Read access lets you list and retrieve all event types. See Events.
Core	Fee Domain Resources	`fee_domain_resources_read`	Fee Domain Resources provide access to fee-related APIs for pricing and fee structures. Read access lets you retrieve fee details.
Core	Files	`file_read` `file_write`	Files are documents uploaded to Stripe, such as dispute evidence or identity documents. Read access lets you list and retrieve files and file links. Write access lets you upload files and create, update, and expire file links. See Files.
Core	Mandates	`mandate_read` `mandate_write`	Mandates are authorization records from customers approving future debits to their payment method (for example, for direct debit). Read access lets you retrieve mandate details and status. Write access enables creating mandates when confirming payments with debit payment methods like the related setting and Bacs Direct Debit. See Mandates.
Core	Payment Disputes	`dispute_read` `dispute_write`	Payment Disputes occur when a customer questions a payment with their bank. Read access lets you list and retrieve disputes. Write access lets you update, close, and escalate disputes and submit evidence. See Payment Disputes.
Core	Payment Intents	`payment_intent_read` `payment_intent_write`	Payment Intents track a payment from creation through confirmation and capture. Read access lets you list and retrieve Payment Intents and their events. Write access lets you create, update, confirm, capture, cancel, redact, increment authorizations, decrement authorizations, and reauthorize Payment Intents. See Payment Intents. If you're managing PaymentIntents with Stripe.js Elements, you must also request `elements_write`.
Core	Payment Links	`payment_links_read` `payment_links_write`	Payment Links are shareable URLs that take customers to a hosted payment page. Read access lets you retrieve and list payment links and their line items. Write access lets you create and update payment links. See Payment Links.
Core	Payment Method Configurations	`payment_method_configurations_read` `payment_method_configurations_write`	Payment Method Configurations control which payment methods are available for checkout experiences. Read access lets you list and retrieve configurations. Write access lets you create and update payment method configurations. See Payment Method Configurations.
Core	Payment Method Domains	`payment_method_domain_read` `payment_method_domain_write`	Payment Method Domains are web domains registered for wallet-based payment methods like Apple Pay and Link. Read access lets you list and retrieve registered domains. Write access lets you register new domains and validate their status. See Payment Method Domains.
Core	Payment Methods	`payment_method_read` `payment_method_write`	Payment Methods represent a customer's payment instrument (cards, bank accounts, wallets). Read access lets you list and retrieve payment method details. Write access lets you create, update, attach, and detach payment methods. See Payment Methods.
Core	Payment Records	`payment_records_read` `payment_records_write`	Payment Records capture payment attempt data reported outside of Stripe. Read access lets you list and retrieve payment records. Write access lets you create and report payment attempts. See Payment Records.
Core	Payouts	`payout_read` `payout_write`	Payouts move funds from your Stripe balance to your bank account or debit card. Read access lets you list and retrieve payout details. Write access lets you create, update, cancel, and reverse payouts. See Payouts.
Core	Products	`product_read` `product_write`	Products represent goods or services you sell. Read access lets you list and retrieve product details. Write access lets you create, update, and delete products. See Products.
Core	Setup Intents	`setup_intent_read` `setup_intent_write`	Setup Intents guide the process of saving a customer's payment method for future use without charging them. Read access lets you list and retrieve Setup Intents and setup attempts. Write access lets you create, update, confirm, cancel, and redact Setup Intents. See Setup Intents. If you're managing SetupIntents with Stripe.js Elements, you must also request `elements_write`.
Core	Shipping Rates	`shipping_rate_read` `shipping_rate_write`	Shipping Rates define delivery costs that can be applied to checkout sessions and orders. Read access lets you list and retrieve rates. Write access lets you create and update shipping rates. See Shipping Rates.
Core	Sources	`source_read` `source_write`	Sources represent payment methods created via the legacy Sources API. Read access lets you retrieve source details. Write access lets you create and update sources. See Sources.
Core	Tokens	`token_read` `token_write`	Tokens securely transmit sensitive card or bank account details from the client to your server. Read access lets you retrieve token details. Write access lets you create tokens. See Tokens.
Issuing	Issuing Authorizations	`issuing_authorization_read` `issuing_authorization_write`	Issuing Authorizations represent pending card transactions that may be approved or declined. Read access lets you list and retrieve authorizations. Write access lets you approve or decline pending authorizations. See Issuing Authorizations.
Issuing	Issuing Cardholders	`issuing_cardholder_read` `issuing_cardholder_write`	Issuing Cardholders represent individuals authorized to use issued cards. Read access lets you list and retrieve cardholder details. Write access lets you create and update cardholders. See Issuing Cardholders.
Issuing	Issuing Cards	`issuing_card_read` `issuing_card_write`	Issuing Cards are virtual or physical payment cards you create and manage. Read access lets you list cards and view their details. Write access lets you create, update, and deactivate cards. See Issuing Cards.
Issuing	Issuing Credit Ledger	`issuing_credit_ledger_read` `issuing_credit_ledger_write`	Issuing Credit Ledger tracks credit balances, entries, and adjustments for Issuing credit programs. Read access lets you view ledger entries and summaries. Write access lets you create adjustments.
Issuing	Issuing Dashboard	`issuing_read` `issuing_write`	Issuing Dashboard provides the full set of Issuing permissions scoped to the dashboard interface. Read access lets you view all Issuing resources. Write access lets you manage them. See Issuing Dashboard.
Issuing	Issuing Disputes	`issuing_dispute_read` `issuing_dispute_write`	Issuing Disputes represent chargebacks filed on transactions made with your issued cards. Read access lets you list and retrieve disputes. Write access lets you create and submit disputes. See Issuing Disputes.
Issuing	Issuing Token Network Data	`issuing_token_network_data_read`	Issuing Token Network Data provides network-level details about provisioned tokens, including device and wallet information. Read access lets you retrieve network-specific token data. See Issuing Token Network Data.
Issuing	Issuing Tokens	`issuing_token_read` `issuing_token_write`	Issuing Tokens represent network tokens (device tokens for Apple Pay and Google Pay) provisioned for issued cards. Read access lets you list and retrieve tokens. Write access lets you manage token lifecycle. See Issuing Tokens.
Issuing	Issuing Transactions	`issuing_transaction_read` `issuing_transaction_write`	Issuing Transactions represent completed purchases made with issued cards. Read access lets you list and retrieve transaction details. Write access lets you update transaction metadata. See Issuing Transactions.
Issuing	Issuing Verifications	`issuing_verification_write`	Issuing Verifications request one-time verification codes for issued cards. Write access lets you create verification requests that send a code to the cardholder.
Money Management	Money Management Payout Intents	`payout_intent_read`	Money Management Payout Intents schedule or immediately execute outbound payments. Read access lets you list and retrieve payout intents. Write access lets you create and cancel payout intents. See Money Management Payout Intents.
Money Management	Money Management Recipient Verifications	`recipient_verification_read`	Money Management Recipient Verifications confirm the identity and bank details of payment recipients. Read access lets you view verification status. Write access lets you initiate verifications.
Orders	Orders	`order_read` `order_write`	Orders represent purchases of products through the legacy Orders API. Read access lets you retrieve order details. Write access lets you create and manage orders.
Orders	Terminal SKUs	`sku_read` `sku_write`	Terminal SKUs represent hardware product variants available for purchase. Read access lets you list available SKUs and their details. Write access lets you manage SKU configurations. See Terminal SKUs.
Provisioning	Provisioning Account Requests	`provisioning_account_request_read` `provisioning_account_request_write`	Provisioning Account Requests track requests for new Stripe accounts within a provisioning workflow. Read access lets you view request status. Write access lets you create and manage requests.
Provisioning	Provisioning Projects	`provisioning_project_read` `provisioning_project_write`	Provisioning Projects organize groups of account requests and their configurations. Read access lets you view project details. Write access lets you create and manage projects.
Provisioning	Provisioning Resources	`provisioning_resource_read` `provisioning_resource_write`	Provisioning Resources are account components allocated through the provisioning workflow. Read access lets you view resource details. Write access lets you manage resources.
Radar	Reviews	`review_read` `review_write`	Reviews are flagged payments requiring human evaluation before approval. Read access lets you list and retrieve reviews. Write access lets you approve or reject flagged payments. See Reviews.
Reporting	Financial Reports	`report_runs_and_report_types_read`	Financial Reports provide automated reporting data. Read access lets you list report types and retrieve generated reports. Write access lets you create report runs. See Financial Reports.
Stripe Apps	Secrets	`secret_read` `secret_write`	Secrets provide secure storage for sensitive values used by Stripe Apps. Read access lets you retrieve secrets your app has stored. Write access lets you create and update secrets. See Secrets.
Stripe Apps	User Email	`user_email_read`	User Email provides access to email addresses of team members on your Stripe account. Read access lets you retrieve user email addresses.
Tax	Tax Calculations, Transactions	`tax_calculations_and_transactions_read` `tax_calculations_and_transactions_write`	Tax Calculations and Transactions represent computed tax amounts and recorded tax events. Read access lets you retrieve calculations and transactions. Write access lets you create calculations and record transactions. See Tax Calculations, Transactions.
Tax	Tax Locations	`tax_locations_read` `tax_locations_write`	Tax Locations represent physical locations used for tax calculation purposes. Read access lets you list and retrieve locations. Write access lets you create and manage tax locations. See Tax Locations.
Tax	Tax Settings, Registrations	`tax_settings_read` `tax_settings_write`	Tax Settings and Registrations configure how Stripe Tax calculates and collects taxes for your account. Read access lets you view settings and registrations. Write access lets you update configurations. See Tax Settings, Registrations.
Terminal	Terminal Configurations	`terminal_configuration_read` `terminal_configuration_write`	Terminal Configurations define device behavior like tipping, receipts, and offline settings. Read access lets you list and retrieve configurations. Write access lets you create and update configurations. See Terminal Configurations.
Terminal	Terminal Connection Tokens	`terminal_connection_token_write`	Terminal Connection Tokens authenticate your POS application's connection to a Terminal reader. Write access lets you create connection tokens. See Terminal Connection Tokens.
Terminal	Terminal Locations	`terminal_location_read` `terminal_location_write`	Terminal Locations represent physical addresses where Terminal readers are deployed. Read access lets you list and retrieve locations. Write access lets you create, update, and delete locations. See Terminal Locations.
Terminal	Terminal Readers	`terminal_reader_read` `terminal_reader_write`	Terminal Readers are physical devices for accepting in-person payments. Read access lets you list readers and view their status. Write access lets you register, update, and delete readers. See Terminal Readers.
Treasury	Treasury Transactions	`treasury_transaction_read`	Treasury Transactions record all money movements within a Treasury financial account. Read access lets you list and retrieve transaction details. See Treasury Transactions.
Webhook Endpoints	Webhook Endpoints, Event Destinations	`webhook_read` `webhook_write`	Webhook Endpoints and Event Destinations receive real-time notifications from Stripe APIs. This is a sensitive permission because it allows subscribing to events across your entire account. Read access lets you list endpoints. Write access lets you create and manage destinations. See Webhook Endpoints, Event Destinations. For most apps, you don't need to include `webhook_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.