App manifest reference

Learn about the app manifest, an index of all fields, types, and descriptions for your app manifest file.

An app manifest describes how your app integrates with the Stripe platform. Every Stripe app needs a stripe-app.json manifest file at the root of the project directory structure.

You can update the app manifest using the Stripe Apps CLI, or you can edit it directly. For instance, you can add a permission using the command stripe apps grant permission, or by adding a permissionRequest to the app manifest directly.

App manifest files follow a schema described on this page.

Example

stripe-app.json
{
  "id": "com.invoicing.[YOUR_APP]",
  "version": "1.2.3",
  "name": "[YOUR APP] Shipment Invoicing",
  "icon": "./[YOUR_APP]_icon_32.png",
  "distribution_type": "public",
  "permissions": [
    {
      "permission": "invoice_write",
      "purpose": "Allows [YOUR APP] to add shipping line items to an invoice."
    },
    {
      "permission": "product_read",
      "purpose": "Allows [YOUR APP] to use product sizes for calculating shipping."
    }
  ],
  "ui_extension": {
    "views": [
      {
        "viewport": "stripe.dashboard.invoice.detail",
        "component": "AddShipping"
      }
    ],
    "content_security_policy": {
      "connect-src": [
        "https://api.example.com/a_specific_endpoint",
        "https://api.example.com/a_whole_subdirectory/"
      ],
      "image-src": [
        "https://images.example.com/one_image.jpg",
        "https://images.example.com/a_whole_subdirectory/"
      ],
      "purpose": "These URLs allow the app to contact [YOUR APP] for creating shipping details and loading images of shipping partner logos"
    }
  },
  "post_install_action": {
    "type": "external",
    "url": "https://example.com"
  },
  "constants": {
    "API_BASE": "https://api.example.com"
  }
}

Schema

App manifest files are JSON files with these fields:

Field name	Type	Examples
id	slug	com.invoicing.myapp
A globally unique identifier for your app, defined by you. Stripe validates upon initial submission.
version	string	1.2.4
An app version that you define. You can use whatever format you want for version identifiers.
name	string	My App
The name shown in the UI when referring to your app. Public distribution apps should not include the words “Stripe”, “app”, “free” or “paid”.
icon	string	./favicon.png
The relative path within the app bundle to a 300x300 pixel PNG icon to show alongside attribution.
distribution_type	“public” \| “private”	“public”
The distribution type for the app.
stripe_api_access_type	“platform” \| “oauth” \| “restricted_api_key”	oauth
The API authentication method of your app.
allowed_redirect_uris	Array<String>	none
The URLs that users are redirected to after installing your app with OAuth or with an install link.
permissions	Array<PermissionRequest>	none
The permissions required by the app in order to function.
ui_extension	UIExtensionManifest	none
Configuration specific to the “UI Extension” capability.
post_install_action	PostInstallAction	none
An optional configuration to direct users to custom location after an app is installed.
constants	Object	`{"API_BASE": "https://api.example.com/v1"}`
An object with arbitrary constant values that you can access in the UI extension context props and override for local development using the CLI manifest flag.

PermissionRequest

A permission request has these fields:

Field name	Type	Example
permission	string	customer_write
Permissions that the app is requesting. Learn more about permissions.
purpose	string \| Map<locale, string>	“This app loads images from images.example.com.”
A user-facing explanation that tells people installing your app why it needs these permissions.
name	string	“Necessary for [YOUR APP] to update invoices with selected shipping charges”
A Stripe-facing explanation that tells app reviewers why your app needs these permissions.

UiExtensionManifest

A UI extension manifest has these fields:

Field name	Type	Example
views	Array<ViewManifest>	none
React components that show up in the Dashboard in a distinct place. Learn more.
content_security_policy	CSPRequest	none
Request for your UI extension to be granted access to specific URLs for a specific purpose.

ViewManifest

A view manifest has these fields:

Field name	Type	Example
viewport	string	stripe.dashboard.invoice.detail
An identifier that indicates where a UI extension might appear within the Dashboard. See the list of available viewports.
component	string	AddShippingSelector
An exported React component that uses one of our view components.

CSPRequest

A content security policy request has these fields:

Field name	Type	Example
connect-src	Array<string>	https://o0.ingest.sentry.io/api/
URLs of permitted third-party APIs. If the URL ends in a slash, all of its children also receive permission. See Use third-party APIs for details.
image-src	Array<string>	https://images.example.com/
URLs the Img component can load from. If the URL ends in a slash, all of its children also receive permission.
purpose	string \| Map<locale, string>	“This app loads images from https://images.example.com and sends anonymous error reports to our partner Sentry for debugging purposes."
An explanation to show users when the app is installed that explains why the plugin needs to communicate directly with these URLs.

URLs must conform to the CSP spec. We only allow HTTPS schemes.

PostInstallAction

A post-install action has these fields:

Field name	Type	Example
type	string	`external`, `settings`
Additional action after users installed your app in the Stripe Dashboard. For more information, see Enable post-install configuration.
url	string	https://example.com
External URL to redirect users to after installing your app. This is required only if the post-install action type is `external`.

Use an extended manifest file for development

During local development you may need to use different app manifest values than those you use in production. For example, your app’s backend could be located at https://api.example.com/v1 but your local development backend runs at http://localhost:8888/v1.

Given this example of a manifest file:

stripe-app.json
{
  "id": "com.invoicing.[YOUR_APP]",
  "version": "1.2.3",
  "name": "[YOUR APP] Shipment Invoicing",
  "icon": "./[YOUR_APP]_icon_32.png",
  "permissions": [],
  "ui_extension": {
    "views": [
      {
        "viewport": "stripe.dashboard.invoice.detail",
        "component": "InvoiceDetail"
      }
    ],
    "content_security_policy": {
      "connect-src": ["https://api.example.com/v1"],
      "purpose": "Allow the app to retrieve example data"
    }
  },
  "constants": {
    "API_BASE": "https://api.example.com/v1"
  }
}

Create another manifest file called stripe-app.[anything].json that extends your main manifest and overrides it with local values. For example:

stripe-app.dev.json
{
  "extends": "stripe-app.json",
  "ui_extension": {
    "content_security_policy": {
      "connect-src": ["http://localhost:8888/v1"]
    }
  },
  "constants": {
    "API_BASE": "http://localhost:8888/v1"
  }
}

To use the local manifest file during development, load it using the --manifest flag. For example:

Command Line
stripe apps start --manifest stripe-app.dev.json

Access the constants values in your views using context props. For example:

import {useEffect, useState} from 'react';
import type {ExtensionContextValue} from '@stripe/ui-extension-sdk/context';
import {Box} from '@stripe/ui-extension-sdk/ui';

const InvoiceDetail = ({environment}: ExtensionContextValue) => {
  const [data, setData] = useState(null);

  useEffect(() => {
    fetch(`${environment.constants.API_BASE}/some-endpoint`)
      .then(response => response.json())
      .then(json => setData(json));
  }, []);

  return data ? <Box>Here is your message: {data.message}</Box> : 'Loading...';
};