# 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 an app manifest file at the root of the project directory structure. You can update the app manifest using the [Stripe Apps CLI](https://docs.stripe.com/stripe-apps/reference/cli.md), or you can edit it directly. For instance, you can [add a permission](https://docs.stripe.com/stripe-apps/reference/permissions.md) using the command `stripe apps grant permission`, or by adding a permission request to the app manifest directly. App manifest files follow a [schema](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#schema) described on this page. #### v1 manifest The v1 manifest is a `stripe-app.json` file at the root of the project directory. ## Example ```json { "id": "com.invoicing.[YOUR_APP]", "version": "1.2.3", "name": "[YOUR APP] Shipment Invoicing", "icon": "./[YOUR_APP]_icon_32.png", "sandbox_install_compatible": true, "distribution_type": "public", // or "private" (default) "stripe_api_access_type": "oauth", // or "platform" (default) or "restricted_api_key" "allowed_redirect_uris": ["https://example.com/oauth/callback"], "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 shouldn’t 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](https://docs.stripe.com/stripe-apps/distribution-options.md) for the app. | | sandbox_install_compatible | true | false | true | Enable [sandbox installs](https://docs.stripe.com/stripe-apps/enable-sandbox-support.md) for the app. | | stripe_api_access_type | “platform” | “oauth” | “restricted_api_key” | oauth | The [API authentication method](https://docs.stripe.com/stripe-apps/api-authentication.md) of your app. | | allowed_redirect_uris | Array | | The URLs that users are redirected to after installing your app with OAuth or with an install link. | | permissions | Array<[PermissionRequest](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#permissionrequest)\> | | The permissions required by the app to function. | | ui_extension | [UIExtensionManifest](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#uiextensionmanifest) | | Configuration specific to the “UI Extension” capability. | | post_install_action | [PostInstallAction](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#postinstallaction) | | 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](https://docs.stripe.com/stripe-apps/reference/extensions-sdk-api.md#props) and [override for local development using the CLI manifest flag](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#extended-manifest). | ### 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](https://docs.stripe.com/stripe-apps/reference/permissions.md). | | purpose | string | Map | “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](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#viewmanifest)\> | | React components that show up in the Dashboard in a distinct place. [Learn more](https://docs.stripe.com/stripe-apps/design.md#types-of-views). | | content_security_policy | [CSPRequest](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#csprequest) | | 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](https://docs.stripe.com/stripe-apps/reference/viewports.md). | | component | string | AddShippingSelector | An exported React component that uses one of our [view components](https://docs.stripe.com/stripe-apps/components.md#views). | ### CSPRequest A content security policy request has these fields: | Field name | Type | Example | | ----------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | connect-src | Array | 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](https://docs.stripe.com/stripe-apps/build-ui.md#use-third-party-apis) for details. | | image-src | Array | https://images.example.com/ | URLs the [Img](https://docs.stripe.com/stripe-apps/components/img.md) component can load from. If the URL ends in a slash, all of its children also receive permission. | | purpose | string | Map | “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](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP). We only allow HTTPS schemes. See [Use third-party APIs](https://docs.stripe.com/stripe-apps/build-ui.md#use-third-party-apis) for usage and troubleshooting information. ### 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](https://docs.stripe.com/stripe-apps/post-install-actions.md). | | 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`. | #### v2 manifest The v2 manifest is a `stripe-app.yaml` file at the root of the project directory. To migrate an existing app from v1 to v2, run `stripe apps migrate`. ## Example ```yaml id: com.invoicing.YOUR_APP version: 1.2.3 name: YOUR APP Shipment Invoicing icon: icons/icon.png declarations: distribution_type: public stripe_api_access: 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. stripe_api_access_type: oauth allowed_redirect_uris: - https://example.com/oauth/callback post_install_action: type: external url: https://example.com constants: API_BASE: https://api.example.com 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 extensions: [] ``` ## Schema The v2 manifest is a YAML file. Required fields are `id`, `name`, `version`, and `extensions`. | Field name | Type | Examples | | ------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------- | | id | string | com.invoicing.myapp | A globally unique identifier for your app, defined by you. Must start and end with an alphanumeric character. 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. | | icon | string | icons/icon.png | Path to a 300x300 pixel PNG image for your app in the App marketplace. | | declarations | [Declarations](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#v2-declarations) | | Top-level declarations about the app, including distribution type, API access, and permissions. | | ui_extension | [UIExtension](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#v2-uiextension) | | Configuration for the app’s user interface, permissions, and behavior in the Stripe Dashboard. | | extensions | Array<[Extension](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#v2-extension)\> | | List of extensions provided by the app. Required (may be empty). | | custom_object_definitions | [CustomObjectDefinitions](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#v2-customobjectdefinitions) | | Custom object definitions provided by the app. | ### Declarations | Field name | Type | Example | | -------------------------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------- | | distribution_type | “public” | “private” | “public” | The [distribution type](https://docs.stripe.com/stripe-apps/distribution-options.md) for the app. | | stripe_api_access | object | | Permissions for the app. Contains `permissions` and optionally `connect_permissions`, each an array of [Permission](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#v2-permission). | | stripe_api_access_type | “default” | “restricted_api_key” | “oauth” | “platform” | “oauth” | The [API authentication method](https://docs.stripe.com/stripe-apps/api-authentication.md) of your app. | | sandbox_install_compatible | true | false | true | Enable [sandbox installs](https://docs.stripe.com/stripe-apps/enable-sandbox-support.md) for the app. | | post_install_action | [PostInstallAction](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#v2-postinstallaction) | | An optional configuration to direct users to a custom location after an app is installed. | | constants | Object | `{API_BASE: https://api.example.com/v1}` | Custom values passed through to your views via context props. | | allowed_redirect_uris | Array | | A list of allowed URLs to which the user can be redirected upon successful install. | ### Permission | Field name | Type | Example | | ---------- | ------ | ------------------------------------------------ | | permission | string | customer_write | The ID of the permission. [Learn more about permissions](https://docs.stripe.com/stripe-apps/reference/permissions.md). | | purpose | string | “This app loads images from images.example.com.” | The reason for requesting the permission. | ### UIExtension | Field name | Type | Example | | ----------------------- | ----------------------------------------------------------------------------------------------------- | ------- | | views | Array<[ViewManifest](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#v2-viewmanifest)\> | | Configure where the app appears in the Dashboard. | | content_security_policy | [CSPRequest](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#v2-csprequest) | | Configure the content security policy for your app. | ### ViewManifest | Field name | Type | Example | | ---------- | ------ | ------------------------------- | | viewport | string | stripe.dashboard.invoice.detail | An identifier that indicates where a UI extension appears in the Dashboard. See the [list of available viewports](https://docs.stripe.com/stripe-apps/reference/viewports.md). | | component | string | AddShipping | The name of the React component in the `src/views` directory to render. | ### CSPRequest | Field name | Type | Example | | ----------- | ------------- | -------------------------------------------------------- | | connect-src | Array | 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](https://docs.stripe.com/stripe-apps/build-ui.md#use-third-party-apis) for details. | | image-src | Array | https://images.example.com/ | URLs the [Img](https://docs.stripe.com/stripe-apps/components/img.md) component can load from. If the URL ends in a slash, all trailing paths are also permitted. | | purpose | string | “This app loads images from https://images.example.com.” | A message to show users when the app is installed that explains why the app needs to communicate with external URLs. | ### PostInstallAction | Field name | Type | Example | | ---------- | ------ | --------------------------------------------- | | type | string | `external`, `modal`, `onboarding`, `settings` | Additional action after users install your app in the Stripe Dashboard. For more information, see [Enable post-install configuration](https://docs.stripe.com/stripe-apps/post-install-actions.md). | | url | string | https://example.com | External URL to redirect users to after installing your app. Required only when `type` is `external`. | ### Extension Each entry in the `extensions` array describes a script extension implemented by the app. | Field name | Type | Example | | -------------- | ------------------------------------------------------------------------------------------------- | ------------------------ | | id | string | my-extension | A unique identifier for the extension within the app. | | name | string | My Extension | The display name of the extension. | | description | string | | An optional developer-defined description (max 300 characters). | | interface_id | string | billing.sales.prorations | The identifier of the extension interface this extension implements. | | version | string | 0.1.0 | The semantic version of the extension. | | stripe_version | string | 2024-06-20 | The Stripe API version to use for this extension. | | permissions | Array<[Permission](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#v2-permission)\> | | Permissions required by the extension. | | script | [ScriptConfig](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#v2-scriptconfig) | | Script configuration for the extension. | | configuration | [CustomInput](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#v2-custominput) | | Custom input schema and UI for the extension. | | methods | Object | | Methods implemented by the extension. Keys are method names; values are [MethodConfig](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#v2-methodconfig) objects. | | endpoints | Array<[Endpoint](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#v2-endpoint)\> | | Endpoints provided by the extension. | ### ScriptConfig | Field name | Type | Example | | ---------- | ------------ | ------------ | | type | “typescript” | “typescript” | The script type. | | content | string | | The script content or entry point. | ### CustomInput | Field name | Type | Example | | ------------ | ------ | ------- | | input_schema | object | | The input schema definition. Requires `type: "json_schema"` and `content` (path to a `.json` file). | | ui_schema | object | | The UI schema definition in JSONForms format. Requires `type: "jsonforms"` and `content` (path to a `.json` file). | ### MethodConfig Each method value is one of: **Script implementation:** | Field name | Type | Example | | ------------------- | ----------------------------------------------------------------------------------------------------------- | -------- | | implementation_type | “script” | “script” | The type of implementation. | | custom_input | [CustomInput](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#v2-custominput) | | Custom input schema and UI for this method. | | errors | Array<[ErrorDefinition](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#v2-errordefinition)\> | | Structured error declarations for this method. | **Remote function implementation:** | Field name | Type | Example | | ------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------- | | implementation_type | “remote_function” | “remote_function” | The type of implementation. | | endpoint_id | string | | The ID of the endpoint to invoke for this method. | | resource_id | string | | The ID of the managed resource to use. | | sandbox_resource_id | string | | The ID of the managed resource to use in sandbox environments. | | errors | Array<[ErrorDefinition](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#v2-errordefinition)\> | | Structured error declarations for this method. | ### ErrorDefinition | Field name | Type | Example | | ---------- | ------- | -------------------------- | | code | string | invalid_amount | Machine-readable error identifier. Must be unique within the method and use snake_case. | | message | string | “Amount must be positive.” | Human-readable message template. | | retryable | boolean | false | Whether the caller should retry on this error. Defaults to `false`. | ### Endpoint | Field name | Type | Example | | --------------- | --------------------------------------------------------------------------------------------------------- | ------------- | | id | string | my-endpoint | A unique identifier for the endpoint within the extension. | | type | “stripe_function” | “custom_http” | “custom_http” | The type of endpoint. | | live | [EndpointDefinition](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#v2-endpointdefinition) | | Configuration for the live environment. | | managed_sandbox | [EndpointDefinition](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#v2-endpointdefinition) | | Configuration for the managed sandbox environment. | | test | [EndpointDefinition](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#v2-endpointdefinition) | | Configuration for the test environment. | ### EndpointDefinition | Field name | Type | Example | | ---------- | --------------------------------------------------------------------------------------------- | ------------------------------- | | url | string | https://api.example.com/handler | The HTTPS URL of the endpoint. | | purpose | string | “Handles proration requests.” | The purpose of the endpoint. | | auth | [EndpointAuth](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#v2-endpointauth) | | Authentication configuration for the endpoint. | ### EndpointAuth | Field name | Type | Example | | ----------- | ------------------------- | -------------- | | type | “bearer_token” | “header” | “bearer_token” | The type of authentication. | | secret_name | string | my-api-key | The name of the secret containing the authentication credential. | | header_name | string | X-Api-Key | The name of the header to use for authentication. Required when `type` is `"header"`. | ### CustomObjectDefinitions | Field name | Type | Example | | ----------- | ------------- | ------- | | definitions | Array | | List of custom object definitions. Each entry requires an `id` (string) and a `specification` object with `type: "typescript"` and a `content` path to the specification file. | ## Use an extended manifest file for development During local development you might need to use different *app manifest* (In a Stripe App, the app manifest is a stripe-app.json file in your app's root directory. It defines your app's ID, views, permissions, and other essential properties) 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: ```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: ```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: ```bash stripe apps start --manifest stripe-app.dev.json ``` Access the `constants` values in your views using [context props](https://docs.stripe.com/stripe-apps/reference/extensions-sdk-api.md#props). For example: ```jsx 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 ? Here is your message: {data.message} : 'Loading...'; }; ``` ## See also - [Stripe Apps CLI reference](https://docs.stripe.com/stripe-apps/reference/cli.md) - [Permissions reference](https://docs.stripe.com/stripe-apps/reference/permissions.md) - [How UI extensions work](https://docs.stripe.com/stripe-apps/how-ui-extensions-work.md)