App configuration - PlatformDTC

An app folder is described by platformdtc.app.toml at its root, and each extension by a platformdtc.extension.toml in its own folder. The CLI validates both before it calls the partner API, and dtc app config push / dtc app deploy send them as an app update plus a new version. The format follows shopify.app.toml, so a Shopify app’s config maps over key for key where the concept exists.

platformdtc.app.toml

Top level

Key	Type	Required	Rules
`name`	string	yes	1–255 characters.
`handle`	string	yes	2–60 characters, `^[a-z0-9][a-z0-9-]*$`. Unique across the App Store. Reserved: `installed`, `authorize`, `billing`, `categories`, `category`, `collections`, `collection`, `search`, `partners`, `partner`, `embed`, `new`, `admin`, `api`.
`client_id`	string	after linking	`sq_app_…`. Written by `dtc app config link`; absent or empty before the folder is linked.
`application_url`	string	yes, except `type = "skill"`	`https` URL. Skill apps have no server and must omit `redirect_urls`, `webhooks`, `nav_links` and `app_proxy`. `http://localhost` and `http://127.0.0.1` are accepted only while `dtc app dev` runs.
`embedded`	boolean	yes	`true`: the app renders inside the merchant dashboard at `/apps/installed/<handle>`.
`type`	string	no	`api`, `embedded` or `skill`. Default: `embedded` when `embedded = true`, otherwise `api`.
`distribution`	string	no	`public` (listed in the App Store after review) or `custom` (installed by link). Default `custom`.
`website_url`	string	no	Your app’s public website.

The client_secret never goes in this file. dtc app config link writes it to .env as PLATFORMDTC_API_SECRET; keep .env out of version control.

`[access_scopes]`

Key	Type	Required	Rules
`scopes`	string	yes	Comma-separated, at least one: `"read_products,write_products"`. See Scopes.
`optional_scopes`	array or string	no	Scopes a merchant may decline. Array, or a comma-separated string.

[access_scopes.justifications] is required: one non-empty string per scope in scopes, keyed by the scope. The merchant reads this text on the consent screen, and review checks it (scope_justifications_complete, see App Store listing).

[access_scopes]
scopes = "read_products,write_products"
optional_scopes = ["orders:read"]

[access_scopes.justifications]
read_products = "Show product titles next to notes"
write_products = "Tag products that have notes"

`[auth]`

Key	Type	Required	Rules
`redirect_urls`	array of strings	no	The callbacks your OAuth install flow redirects to. At most 10. Each an `https` URL (localhost only during `dtc app dev`). Matched exactly during the install flow.

`[webhooks]`

Each [[webhooks.subscriptions]] entry has a uri and either topics or compliance_topics.

Key	Type	Rules
`topics`	array of strings	Event topics, for example `orders/create`, `app/uninstalled`. See Webhooks.
`compliance_topics`	array of strings	Any of `customers/data_request`, `customers/redact`, `shop/redact`.
`uri`	string	Absolute `https` URL, or a path relative to `application_url`.

Two platform rules:

One endpoint for events. Every non-compliance topic of an app is delivered to one endpoint (the app’s webhook_endpoint_url), so all topics subscriptions must resolve to the same URL. Different URLs are a validation error.
Compliance topics may each have their own URL. Public apps must declare all three compliance topics.

[[webhooks.subscriptions]]
topics = ["orders/create", "app/uninstalled"]
uri = "/webhooks"

[[webhooks.subscriptions]]
compliance_topics = ["customers/data_request", "customers/redact", "shop/redact"]
uri = "/webhooks/compliance"

`[app_proxy]`

Serves a path on the merchant’s storefront domain from your app: https://<store domain>/<prefix>/<subpath>/* is forwarded to url with a signed query string.

Key	Type	Required	Rules
`url`	string	yes (if the table is present)	`https` URL.
`prefix`	string	yes	`apps`, `a`, `community` or `tools`.
`subpath`	string	yes	`^[a-z0-9-]{1,30}$`.

`[[nav_links]]`

Links shown under your app in the merchant dashboard sidebar. Embedded apps only; at most 10.

Key	Type	Rules
`label`	string	The link text.
`url`	string	Path under `application_url`, starting with `/`.

`[extensions]`

Key	Type	Rules
`dirs`	array of strings	Folders (globs allowed) that each contain a `platformdtc.extension.toml`. Example: `["extensions/*"]`.

`[skill]`

For type = "skill" only. See Skill apps.

Key	Type	Rules
`path`	string	Path to the `SKILL.md`, relative to the app folder. Its frontmatter must declare `name` and `description`.

`[build]`

Key	Type	Rules
`dev_store`	string	The development store id `dtc app dev` installs on. Set by `dtc app dev` after you choose a store.

platformdtc.extension.toml

Key	Type	Required	Rules
`type`	string	yes	`theme_app_block`, `theme_app_embed`, `web_pixel`, `admin_link`, `admin_action` or `agent_tools` (below).
`handle`	string	yes	`^[a-z0-9][a-z0-9-]{0,63}$`, unique within the app.
`name`	string	yes	1–64 characters. Shown to merchants, for example in the theme editor’s block picker.
`target`	string	depends on type	`theme_app_embed`: `head` or `body`. `admin_link` / `admin_action`: `product_details`, `order_details` or `customer_details`. Omit for other types.
`entry`	string	blocks, embeds, pixels	Path to the built JavaScript bundle, relative to the extension folder. At most 256 KiB. `dtc app deploy` runs `npm run build` first when the folder’s `package.json` has a `build` script. Admin links and actions have none.
`settings_schema`	string	no	Path to a JSON file holding an array of setting definitions (theme setting types; web pixels accept `text` only). Not for admin links and actions.
`url`	string	`admin_link` / `admin_action`	The page it opens in your embedded app: a path on your app’s origin such as `/orders/review` (not `/`). See Extensions.

type = "theme_app_block"
handle = "star-rating"
name = "Star rating"
entry = "dist/index.js"
settings_schema = "settings.json"

When a merchant uninstalls the app, its theme app blocks render nothing.

Agent tools

A folder with type = "agent_tools" declares the tools the merchant’s AI assistant can call on your app (see Agent tools). It has no bundle: it takes type, handle, name and tools only, and an app has at most one.

Key	Type	Required	Rules
`tools`	string	yes	Path to a JSON file inside the extension folder holding an array of at most 20 tools.

Each tool in the file:

Key	Type	Required	Rules
`name`	string	yes	`^[a-z][a-z0-9_]{0,39}$`, unique in the file.
`title`	string	yes	1–64 characters, read by the merchant.
`description`	string	yes	1–512 characters, read by the assistant.
`input_schema`	object	yes	JSON Schema with `"type": "object"`, at most 16 KiB.
`required_scopes`	array of strings	yes	1–10 scopes from `[access_scopes]` `scopes` or `optional_scopes`.
`url`	string	yes	Public `https` URL, or a path relative to `application_url`.
`read_only`	boolean	no	Default `false`.
`requires_approval`	boolean	no	Default `false`; always on when a required scope moves money or contacts customers. Not with `read_only = true`.

extensions/assistant/platformdtc.extension.toml

type = "agent_tools"
handle = "assistant"
name = "Assistant tools"
tools = "tools.json"

extensions/assistant/tools.json

[
  {
    "name": "add_order_note",
    "title": "Add an order note",
    "description": "Adds a note to an order. Use when the merchant asks to note something on an order.",
    "input_schema": {
      "type": "object",
      "properties": { "order_id": { "type": "string" }, "note": { "type": "string" } },
      "required": ["order_id", "note"]
    },
    "required_scopes": ["write_products"],
    "url": "/agent/add_order_note"
  }
]

Complete example

platformdtc.app.toml

name = "Order Notes"
handle = "order-notes"
client_id = "sq_app_…"
application_url = "https://notes.example.com"
embedded = true
type = "embedded"
distribution = "public"
website_url = "https://notes.example.com"

[access_scopes]
scopes = "read_products,write_products"
optional_scopes = ["orders:read"]

[access_scopes.justifications]
read_products = "Show product titles next to notes"
write_products = "Tag products that have notes"

[auth]
redirect_urls = ["https://notes.example.com/auth/callback"]

[[webhooks.subscriptions]]
topics = ["orders/create", "app/uninstalled"]
uri = "/webhooks"

[[webhooks.subscriptions]]
compliance_topics = ["customers/data_request", "customers/redact", "shop/redact"]
uri = "/webhooks/compliance"

[app_proxy]
url = "https://notes.example.com/proxy"
prefix = "apps"
subpath = "order-notes"

[[nav_links]]
label = "Settings"
url = "/settings"

[extensions]
dirs = ["extensions/*"]

[build]
dev_store = "…"

How the file maps to the API

TOML	Partner API field
`name`, `handle`, `distribution`, `website_url`	same names on the app
`type` (or `embedded`)	`app_type`
`application_url`	`app_url` (and `embedded_app_url` for embedded apps)
`[auth] redirect_urls`	`redirect_uris`
`topics` subscription `uri`	`webhook_endpoint_url`
`compliance_topics` subscriptions	`compliance_webhook_urls` (topic → URL)
`[access_scopes]`	version `requested_scopes`, `optional_scopes`, `scope_justifications`
all `topics`	version `webhook_topics`
`[[nav_links]]`, `[app_proxy]`	version `nav_links`, `app_proxy`
`[skill] path`	version `skill_md` (the file’s contents)
the `agent_tools` extension’s `tools` file	version `agent_tools` (relative `url`s resolved against `application_url`)

App fields change with PATCH /partner/apps/{id}. Everything in the version column creates a new version, and a new version needs a new review before merchants can install it.

​platformdtc.app.toml

​Top level

​[access_scopes]

​[auth]

​[webhooks]

​[app_proxy]

​[[nav_links]]

​[extensions]

​[skill]

​[build]

​platformdtc.extension.toml

​Agent tools

​Complete example

​How the file maps to the API

platformdtc.app.toml

Top level

`[access_scopes]`

`[auth]`

`[webhooks]`

`[app_proxy]`

`[[nav_links]]`

`[extensions]`

`[skill]`

`[build]`

platformdtc.extension.toml

Agent tools

Complete example

How the file maps to the API