On this page

Permissions Reference

Stripe Apps use a permission system to control access to Stripe API resources. Each permission must be explicitly declared in your app manifest with a clear purpose statement. Users approve these permissions when they install your app.

Managing Permissions

Declaring Permissions

Add permissions to your stripe-app.json manifest:

{
  "permissions": [
    {
      "permission": "customer_read",
      "purpose": "Read customer profiles to sync with Brevo contacts"
    },
    {
      "permission": "customer_write",
      "purpose": "Update customer metadata with Brevo sync status"
    }
  ]
}

Granting Permissions via CLI

During development, you can grant permissions using the Stripe CLI:

# Grant a specific permission
stripe apps grant permission "customer_read" \
  --purpose "Read customer profiles to sync with Brevo contacts"

# Grant multiple permissions
stripe apps grant permission "charge_read" \
  --purpose "Access payment data for event tracking"

stripe apps grant permission "event_read" \
  --purpose "Subscribe to real-time Stripe events"

Permission Best Practices

Minimum necessary: Only request permissions your app actually uses
Clear purposes: Write purpose statements that non-technical users can understand
Justify read+write: If you need both read and write, explain why in each purpose
Review regularly: Remove permissions that are no longer needed when updating your app

Tip

Requesting excessive permissions is one of the most common reasons for app rejection. Only request what you need.

Permissions by Product

Core

Resource	Permission	Description
Account	`account_read`	Read account details and settings
Account	`account_write`	Update account settings
Balance	`balance_read`	View account balance and transactions
Customer	`customer_read`	Read customer profiles, metadata, and payment methods
Customer	`customer_write`	Create, update, or delete customer records
Event	`event_read`	Read and subscribe to account events
File	`file_read`	Read uploaded files and file links
File	`file_write`	Upload files and create file links
Mandate	`mandate_read`	Read payment mandates
Product	`product_read`	Read product catalog and pricing
Product	`product_write`	Create, update, or delete products and prices
Token	`token_read`	Read tokenized payment data
Webhook Endpoint	`webhook_endpoint_read`	Read webhook endpoint configurations
Webhook Endpoint	`webhook_endpoint_write`	Create, update, or delete webhook endpoints

Payments

Resource	Permission	Description
Charge	`charge_read`	Read payment charges and refunds
Charge	`charge_write`	Create charges, capture payments, issue refunds
Dispute	`dispute_read`	Read payment disputes and evidence
Dispute	`dispute_write`	Submit dispute evidence and respond to disputes
Payment Intent	`payment_intent_read`	Read payment intent details and status
Payment Intent	`payment_intent_write`	Create, confirm, or cancel payment intents
Payment Method	`payment_method_read`	Read saved payment methods
Payment Method	`payment_method_write`	Attach or detach payment methods from customers
Payout	`payout_read`	Read payout details and schedules
Payout	`payout_write`	Create or cancel payouts
Refund	`refund_read`	Read refund details
Refund	`refund_write`	Create or update refunds
Setup Intent	`setup_intent_read`	Read setup intent details
Setup Intent	`setup_intent_write`	Create or confirm setup intents

Billing

Resource	Permission	Description
Coupon	`coupon_read`	Read discount coupons and promotion codes
Coupon	`coupon_write`	Create, update, or delete coupons
Credit Note	`credit_note_read`	Read credit notes
Credit Note	`credit_note_write`	Create or void credit notes
Invoice	`invoice_read`	Read invoice details, line items, and status
Invoice	`invoice_write`	Create, update, finalize, or void invoices
Invoice Item	`invoice_item_read`	Read pending invoice items
Invoice Item	`invoice_item_write`	Create or delete invoice items
Plan	`plan_read`	Read subscription plans and pricing
Plan	`plan_write`	Create, update, or delete plans
Price	`price_read`	Read price configurations
Price	`price_write`	Create or update prices
Quote	`quote_read`	Read price quotes
Quote	`quote_write`	Create, finalize, or accept quotes
Subscription	`subscription_read`	Read subscription details, schedules, and status
Subscription	`subscription_write`	Create, update, or cancel subscriptions
Subscription Schedule	`subscription_schedule_read`	Read subscription schedules
Subscription Schedule	`subscription_schedule_write`	Create, update, or release subscription schedules
Usage Record	`usage_record_read`	Read metered billing usage records
Usage Record	`usage_record_write`	Create usage records for metered billing

Checkout

Resource	Permission	Description
Checkout Session	`checkout_session_read`	Read Checkout Session details and line items
Checkout Session	`checkout_session_write`	Create or expire Checkout Sessions
Payment Link	`payment_link_read`	Read Payment Link configurations
Payment Link	`payment_link_write`	Create or update Payment Links

Connect

Resource	Permission	Description
Application Fee	`application_fee_read`	Read application fee details
Connected Account	`connected_account_read`	Read connected account details
Connected Account	`connected_account_write`	Create or update connected accounts
Transfer	`transfer_read`	Read transfer details between accounts
Transfer	`transfer_write`	Create transfers to connected accounts
Top-up	`topup_read`	Read top-up details
Top-up	`topup_write`	Create top-ups to Stripe balance

Issuing

Resource	Permission	Description
Issuing Card	`issuing_card_read`	Read issued card details
Issuing Card	`issuing_card_write`	Create, update, or deactivate issued cards
Issuing Cardholder	`issuing_cardholder_read`	Read cardholder information
Issuing Cardholder	`issuing_cardholder_write`	Create or update cardholders
Issuing Transaction	`issuing_transaction_read`	Read card transaction details
Issuing Authorization	`issuing_authorization_read`	Read authorization requests
Issuing Authorization	`issuing_authorization_write`	Approve or decline authorization requests
Issuing Dispute	`issuing_dispute_read`	Read issuing disputes
Issuing Dispute	`issuing_dispute_write`	Create or submit issuing disputes

Reporting

Resource	Permission	Description
Report Run	`report_run_read`	Read report run results
Report Run	`report_run_write`	Create new report runs
Report Type	`report_type_read`	Read available report types

Tax

Resource	Permission	Description
Tax Calculation	`tax_calculation_read`	Read tax calculation results
Tax Calculation	`tax_calculation_write`	Create tax calculations
Tax Rate	`tax_rate_read`	Read tax rate configurations
Tax Rate	`tax_rate_write`	Create or update tax rates
Tax Registration	`tax_registration_read`	Read tax registration details

Terminal

Resource	Permission	Description
Terminal Reader	`terminal_reader_read`	Read terminal reader details
Terminal Reader	`terminal_reader_write`	Register or update terminal readers
Terminal Location	`terminal_location_read`	Read terminal location details
Terminal Location	`terminal_location_write`	Create or update terminal locations

Secret Store

Resource	Permission	Description
Secret	`secret_read`	Read secrets from the Secret Store
Secret	`secret_write`	Create, update, or delete secrets

Recommended Permissions for Tajo Brevo Integration

For the Tajo Brevo integration app, these are the recommended permissions:

{
  "permissions": [
    {
      "permission": "customer_read",
      "purpose": "Sync customer profiles and contact information to Brevo"
    },
    {
      "permission": "customer_write",
      "purpose": "Store Brevo contact ID and sync status on customer metadata"
    },
    {
      "permission": "charge_read",
      "purpose": "Track purchase events and revenue data for Brevo analytics"
    },
    {
      "permission": "product_read",
      "purpose": "Sync product catalog to Brevo for personalized email campaigns"
    },
    {
      "permission": "event_read",
      "purpose": "Listen to real-time events to trigger Brevo automation workflows"
    },
    {
      "permission": "invoice_read",
      "purpose": "Track invoice events for transactional emails via Brevo"
    },
    {
      "permission": "subscription_read",
      "purpose": "Monitor subscription lifecycle for Brevo retention campaigns"
    },
    {
      "permission": "secret_write",
      "purpose": "Securely store Brevo API credentials in Stripe Secret Store"
    },
    {
      "permission": "secret_read",
      "purpose": "Retrieve stored Brevo API credentials for data sync operations"
    },
    {
      "permission": "webhook_endpoint_write",
      "purpose": "Register webhook endpoints for real-time event delivery to Tajo"
    }
  ]
}

Permission Scopes

Permissions can operate at different scopes depending on whether your app is installed on a platform account or a connected account:

Scope	Description
Account	Permissions apply to the installing account’s own data
Connected Account	For Connect platforms, permissions can extend to connected accounts

Caution

When requesting write permissions, be prepared to explain during app review exactly how and when your app modifies data. Unnecessary write permissions are a common reason for rejection.