App configuration
You can configure your apps locally with TOML files, then link them to apps in your Partner Dashboard and push that configuration to make it live using the Shopify CLI. You can also configure most of these settings through the Partner Dashboard. The settings in the Partner Dashboard always reflect the live state of your app.
Learn more about managing app configuration files.
App configuration file example
Anchor link to section titled "App configuration file example"
| Property | Required? | Value | Description |
|---|---|---|---|
name |
Yes | string |
The name of your app. |
client_id |
Yes | string |
The app's public identifier. |
application_url |
Yes | string matching a valid URL |
The URL of your app. For more details, see OAuth - Getting Started. Note: If you're building an extension-only app, then your application_url will be set to https://shopify.dev/apps/default-app-home by default. |
embedded |
Yes | boolean |
Embedded apps let users interact with your app without leaving the context of Shopify. |
access_scopes
Anchor link to section titled "access_scopes"Define the permissions your app requests, as well as how the permissions are requested.
| Property | Required? | Value | Description |
|---|---|---|---|
scopes |
Yes | string matching a comma-separated list of scopes |
Any access scopes that your app will request access to during the authorization process. |
use_legacy_install_flow |
No | boolean | When omitted or false, scopes are saved in your app's configuration, and are automatically requested when the app is installed on a store. When true, the legacy installation flow requests scopes through a URL paramater during the OAuth flow. The legacy installation flow is still supported, but isn't recommended because your app can end up with different scopes for each installation. |
| Property | Required? | Value | Description |
|---|---|---|---|
redirect_urls |
Yes | array of strings matching a valid URL |
Users are redirected to these URLs as part of the OAuth flow. You must include at least one redirect URL before making your app public. Learn more about redirection URLs. |
| Property | Required? | Value | Description |
|---|---|---|---|
api_version |
Yes | string matching a valid Shopify version (example: 2022-10) |
The API version used to serialize webhooks and cloud service events. |
privacy_compliance
Anchor link to section titled "privacy_compliance"Endpoints for webhooks that manage the requests to view or erase customer personal information. These are mandatory webhooks for public apps.
| Property | Required? | Value | Description |
|---|---|---|---|
customer_deletion_url |
No | string matching a valid URL |
Your app's endpoint for deleting customer information |
customer_data_request_url |
No | string matching a valid URL |
Your app's endpoint for a customer data request |
shop_deletion_url |
No | string matching a valid URL |
Your app's endpoint for deleting shop information |
Let Shopify act as a proxy when sending requests to your app. Learn more about app proxy.
| Property | Required? | Value | Description |
|---|---|---|---|
url |
Yes if app_proxy defined |
string matching a valid URL |
URL of your app proxy server |
subpath |
Yes if app_proxy defined |
string |
The combination of prefix and subpath defines where the app proxy is accessed from a merchant's shop. |
prefix |
Yes if app_proxy defined |
string matching a, apps,community, or tools |
The combination of prefix and subpath defines where the app proxy is accessed from a merchant's shop. |
| Property | Required? | Value | Description |
|---|---|---|---|
embedded |
No | boolean |
Load your app in Shopify POS using Shopify App Bridge. Learn more. |
preferences
Anchor link to section titled "preferences"| Property | Required? | Value | Description |
|---|---|---|---|
url |
No | string matching a valid URL |
URL for your app's preferences page |
Settings for running your app through the Shopify CLI
| Property | Required? | Value | Description |
|---|---|---|---|
automatically_update_urls_on_dev |
No | boolean |
Whether Shopify CLI should automatically update the app's URL on dev. This is particularly useful when using the built-in tunnel. |
dev_store_url |
No | string matching a valid store URL |
The name of the dev store used to preview your app. |