Manifest reference

Every key the platform accepts, read from the same schema the CLI and the server check a manifest against. A key not listed here is refused. The manifest explains how the sections work together.

For completion and checks in your editor, put this line at the top of storeware.app.toml. Editors that read JSON Schema for TOML, such as Taplo and the Even Better TOML extension, follow it:

#:schema https://storeware.ai/docs/schemas/storeware.app.json

Top level

Key	Value	Required	Meaning
`manifest_version`	integer	no	Which shape of manifest this is. Write 2. From 1 to 2.
`app`	table	yes	Who the app is and where it lives.
`oauth`	table	yes	What the app may reach.
`privacy`	table	no	Where data requests and erasures are posted.
`billing`	table	no	What the app charges, collected by Storeware on the merchant’s bill.
`webhooks`	table	no	Where events are posted, and which ones.
`extensions`	table	no	Panels in the admin and blocks on the shop front.
`settings`	list of tables	no	Up to 30 fields a merchant fills in on your app’s page in their settings. At most 30.
`app_proxy`	table	no	Pages under the shop’s own address, at /apps/your-slug/.
`automations`	table	no	Triggers and actions your app adds to the shop’s automations.
`checkout`	table	no	Where your app takes part in checkout.
`runtime`	table	no	Run your app on Storeware, free, at https://<slug>.storewareapps.com. In beta.
`knowledge`	table	no	What your app knows about products, merged into search and every AI agent’s view of the catalogue.
`metafields`	table	no	Typed fields your app keeps on a merchant’s records.
`mcp`	table	no	Tools your app adds to every assistant on a shop.

[app]

Who the app is and where it lives.

Key	Value	Required	Meaning
`slug`	string	yes	Your client id. Lower case letters, digits and hyphens, 2 to 63 characters. It never changes. Matches `^[a-z0-9][a-z0-9-]{1,62}$`.
`name`	string	yes	What merchants see on the consent screen and in their Apps list. At most 120 characters.
`description`	string	no	A sentence or two for merchants. At most 500 characters.
`homepage_url`	https URL	no	Your public site, shown to merchants.
`url`	https URL	no	Your home inside the admin, opened full height with a session token. With it, merchants install from Storeware.
`navigation`	list of tables	no	Up to five pages inside your home, listed under it in the admin. At most 5.
`privacy_policy_url`	https URL	no	Your privacy policy, shown to merchants.
`support_url`	https URL	no	Where merchants get help, shown to merchants.

[[app.navigation]]

Up to five pages inside your home, listed under it in the admin.

Key	Value	Required	Meaning
`label`	string	yes	The link text, up to 30 characters. At most 30 characters.
`path`	string	yes	A path inside your home, starting with /. Matches `^\/[A-Za-z0-9._~/-]*$`.

[oauth]

What the app may reach.

Key	Value	Required	Meaning
`redirect_uris`	list of https URL	no	Where an install that starts on your own site returns to, matched exactly. Not needed when app.url is set. Defaults to `[]`.
`scopes`	list of string	yes	The permissions the app asks for. A merchant grants all of them or does not install. At least 1.

[privacy]

Where data requests and erasures are posted.

Key	Value	Required	Meaning
`url`	https URL	yes	Receives the compliance events. Needed when the app reads customer or order data.

[billing]

What the app charges, collected by Storeware on the merchant’s bill.

Key	Value	Required	Meaning
`mode`	`managed`, `api`	yes	managed: Storeware shows your plans at install and on your app’s page. api: your app asks for each charge.
`plans`	list of tables	no	Up to six plans. At most 6. Defaults to `[]`.

[[billing.plans]]

Up to six plans.

Key	Value	Required	Meaning
`key`	string	yes	What your app asks for, in lower_snake_case. Matches `^[a-z][a-z0-9_]{1,31}$`.
`name`	string	yes	What the merchant reads, up to 40 characters. At most 40 characters.
`description`	string	no	One line under the name. At most 200 characters.
`interval`	`month`, `year`	no	month or year. Charged in advance. Defaults to `"month"`.
`prices`	table	no	The price in all four currencies, in minor units, each set by hand. Leave it out for a free plan.
`trial_days`	integer	no	Days before the first charge, up to 90, once per shop. From 0 to 90. Defaults to `0`.
`features`	list of string	no	Up to eight short lines shown with the plan. At most 8. Defaults to `[]`.
`usage`	table	no	Charges by use on top of the plan, billed at the end of each period, never more than the cap. Needs billing.mode api.

[billing.plans.prices]

The price in all four currencies, in minor units, each set by hand. Leave it out for a free plan.

Key	Value	Required	Meaning
`usd`	integer	yes	US dollars, in cents. From 1 to 10000000.
`gbp`	integer	yes	Pounds sterling, in pence. From 1 to 10000000.
`eur`	integer	yes	Euros, in cents. From 1 to 10000000.
`inr`	integer	yes	Indian rupees, in paise. From 1 to 10000000.

[billing.plans.usage]

Charges by use on top of the plan, billed at the end of each period, never more than the cap. Needs billing.mode api.

Key	Value	Required	Meaning
`cap`	table	yes	The most one period can cost, in all four currencies.
`terms`	string	yes	What the merchant reads about the rate, such as 2 cents a label. At most 200 characters.

[billing.plans.usage.cap]

The most one period can cost, in all four currencies.

Key	Value	Required	Meaning
`usd`	integer	yes	US dollars, in cents. From 1 to 10000000.
`gbp`	integer	yes	Pounds sterling, in pence. From 1 to 10000000.
`eur`	integer	yes	Euros, in cents. From 1 to 10000000.
`inr`	integer	yes	Indian rupees, in paise. From 1 to 10000000.

[webhooks]

Where events are posted, and which ones.

Key	Value	Required	Meaning
`url`	https URL	yes	Where events are posted. Redirects are never followed.
`events`	list of string	yes	Topics to receive. Each needs a scope that reads the same data. At least 1.

[extensions]

Panels in the admin and blocks on the shop front.

Key	Value	Required	Meaning
`admin`	list of tables	no	Panels and actions your app adds to the admin.
`storefront`	list of tables	no	Blocks your app adds to the shop front.
`sections`	list of tables	no	Up to ten sections a merchant can place on any page from the page editor. At most 10.

[[extensions.admin]]

Panels and actions your app adds to the admin.

Key	Value	Required	Meaning
`point`	`admin.product.detail.sidebar`, `admin.product.detail.action`, `admin.product.index.action`, `admin.collection.detail.sidebar`, `admin.collection.detail.action`, `admin.order.detail.sidebar`, `admin.order.detail.action`, `admin.orders.index.action`, `admin.customer.detail.sidebar`, `admin.customer.detail.action`, `admin.customers.index.action`, `admin.settings.block`	yes	Where in the admin it appears: a panel beside a record, an action in a record’s Apps menu, or an action on the rows ticked in a list.
`url`	https URL	yes	The page framed in the panel, or in the window an action opens.
`title`	string	yes	The panel’s heading, or the action’s name in the menu. At most 60 characters.

[[extensions.storefront]]

Blocks your app adds to the shop front.

Key	Value	Required	Meaning
`block`	`storefront.product.below_description`, `storefront.product.above_add_to_cart`, `storefront.cart.summary`, `storefront.collection.header`	yes	Where on the shop front the block appears.
`url`	https URL	yes	Where Storeware asks for the block’s content.
`format`	`html`, `components`	no	html, sanitised to text, lists, tables and links, or components, drawn in the shop’s own style. Defaults to `"html"`.

[[extensions.sections]]

Up to ten sections a merchant can place on any page from the page editor.

Key	Value	Required	Meaning
`handle`	string	yes	The section’s key, in lower_snake_case. It never changes. Matches `^[a-z][a-z0-9_]{1,31}$`.
`name`	string	yes	What the merchant sees in the page editor, up to 40 characters. At most 40 characters.
`description`	string	no	One line about the section, shown in the page editor. At most 200 characters.
`url`	https URL	yes	Where Storeware asks for the section’s content.
`format`	`html`, `components`	no	components (the default) or html. Defaults to `"components"`.

[app_proxy]

Pages under the shop’s own address, at /apps/your-slug/.

Key	Value	Required	Meaning
`url`	https URL	yes	Where Storeware forwards each request, signed and without the shopper’s cookies.

[automations]

Triggers and actions your app adds to the shop’s automations.

Key	Value	Required	Meaning
`triggers`	list of tables	no	Up to 20 things that can start an automation, fired by your app. At most 20. Defaults to `[]`.
`actions`	list of tables	no	Up to 20 steps a merchant can add to an automation. At most 20. Defaults to `[]`.

[[automations.triggers]]

Up to 20 things that can start an automation, fired by your app.

Key	Value	Required	Meaning
`key`	string	yes	The trigger’s key, in lower_snake_case letters. Matches `^[a-z][a-z_]{1,31}$`.
`label`	string	yes	What the merchant reads, such as A review was left. At most 60 characters.
`description`	string	no	One line about when it fires. At most 200 characters.
`fields`	list of tables	no	Up to 20 values the trigger carries, which a condition can test. At most 20. Defaults to `[]`.

[[automations.triggers.fields]]

Up to 20 values the trigger carries, which a condition can test.

Key	Value	Required	Meaning
`key`	string	yes	The value’s key, in lower_snake_case. Matches `^[a-z][a-z0-9_]{1,63}$`.
`label`	string	yes	What the merchant reads. At most 60 characters.
`type`	`text`, `number`, `boolean`, `date`, `url`	yes	The kind of value.

[[automations.actions]]

Up to 20 steps a merchant can add to an automation.

Key	Value	Required	Meaning
`key`	string	yes	The action’s key, in lower_snake_case letters. Matches `^[a-z][a-z_]{1,31}$`.
`label`	string	yes	What the merchant reads, such as Send a text. At most 60 characters.
`description`	string	no	One line about what it does. At most 200 characters.
`url`	https URL	yes	Where Storeware posts the step, signed, with an idempotency key.
`fields`	list of tables	no	Up to 20 values the merchant fills in for the step. At most 20. Defaults to `[]`.

[[automations.actions.fields]]

Up to 20 values the merchant fills in for the step.

Key	Value	Required	Meaning
`key`	string	yes	The value’s key, in lower_snake_case. Matches `^[a-z][a-z0-9_]{1,63}$`.
`label`	string	yes	What the merchant reads. At most 60 characters.
`type`	`text`, `multi_line_text`, `number`, `boolean`, `url`, `select`	yes	The kind of value.
`required`	boolean	no	Whether the step needs it. Defaults to `false`.
`options`	list of tables	no	For a select, the choices: from 2 to 30. At most 30. At least 2.

[[automations.actions.fields.options]]

For a select, the choices: from 2 to 30.

Key	Value	Required	Meaning
`value`	string	yes	What your app receives. At most 60 characters.
`label`	string	yes	What the merchant reads. At most 60 characters.

[checkout]

Where your app takes part in checkout.

Key	Value	Required	Meaning
`delivery_rates`	table	no	Delivery choices your app offers. If it fails or is slow, the shop’s own rates are shown.

[checkout.delivery_rates]

Delivery choices your app offers. If it fails or is slow, the shop’s own rates are shown.

Key	Value	Required	Meaning
`url`	https URL	yes	Where Storeware asks for rates, with the basket and address. Needs checkout:read.

[runtime]

Run your app on Storeware, free, at https://<slug>.storewareapps.com. In beta.

Key	Value	Required	Meaning
`main`	string	no	The file `storeware app deploy` bundles. Defaults to src/worker.ts. At most 200 characters. Defaults to `"src/worker.ts"`.
`egress`	list of string	no	Hosts your code may call besides Storeware’s API, such as api.example.com. Nothing else is reachable. At most 20. Defaults to `[]`.
`bundle`	string	no	The bundle’s SHA-256, written by `storeware app deploy`. Do not edit it. Matches `^[0-9a-f]{64}$`.

[knowledge]

What your app knows about products, merged into search and every AI agent’s view of the catalogue.

Key	Value	Required	Meaning
`url`	https URL	yes	Where Storeware asks your app about a product.
`attributes`	list of string	no	Attribute keys your app may set, in lower_snake_case. Defaults to `[]`.
`relations`	list of string	no	Relations your app may assert between two products. Defaults to `[]`.
`scopes`	list of string	no	Scopes these calls use. Defaults to `[]`.

[metafields]

Typed fields your app keeps on a merchant’s records.

Key	Value	Required	Meaning
`definitions`	list of tables	yes	Up to 50 fields. At most 50. At least 1.
`scopes`	list of string	no	Scopes these writes use. Defaults to `[]`.

[[metafields.definitions]]

Up to 50 fields.

Key	Value	Required	Meaning
`owner_type`	`product`, `variant`, `collection`, `customer`, `order`, `store`	yes	The kind of record the field belongs to.
`key`	string	yes	The field’s key, in lower_snake_case. Matches `^[a-z][a-z0-9_]{1,63}$`.
`name`	string	yes	What a merchant sees. At most 200 characters.
`description`	string	no	A longer note for the merchant. At most 2000 characters.
`type`	`single_line_text`, `multi_line_text`, `integer`, `decimal`, `boolean`, `date`, `url`	yes	The kind of value the field holds.
`is_list`	boolean	no	Whether the field holds a list of values. Defaults to `false`.
`storefront_visible`	boolean	no	Whether shoppers see it. Never allowed for customer or order fields. Defaults to `false`.

[mcp]

Tools your app adds to every assistant on a shop.

Key	Value	Required	Meaning
`tools`	list of tables	no	The tools.

[[mcp.tools]]

The tools.

Key	Value	Required	Meaning
`name`	string	yes	The tool’s name, in lower_snake_case. Matches `^[a-z][a-z0-9_]{2,63}$`.
`description`	string	yes	What the tool does, for the model choosing it. At most 500 characters.
`url`	https URL	yes	Where Storeware calls the tool.
`scopes`	list of string	no	Scopes the tool uses. Defaults to `[]`.
`input_schema`	table of any keys	no	The tool’s arguments, as JSON Schema. Defaults to `{"type":"object","additionalProperties":false}`.

Top levelCopy Anchor Link

[app]Copy Anchor Link

[[app.navigation]]Copy Anchor Link

[oauth]Copy Anchor Link

[privacy]Copy Anchor Link

[billing]Copy Anchor Link

[[billing.plans]]Copy Anchor Link

[billing.plans.prices]Copy Anchor Link

[billing.plans.usage]Copy Anchor Link

[billing.plans.usage.cap]Copy Anchor Link

[webhooks]Copy Anchor Link

[extensions]Copy Anchor Link

[[extensions.admin]]Copy Anchor Link

[[extensions.storefront]]Copy Anchor Link

[[extensions.sections]]Copy Anchor Link

[app_proxy]Copy Anchor Link

[automations]Copy Anchor Link

[[automations.triggers]]Copy Anchor Link

[[automations.triggers.fields]]Copy Anchor Link

[[automations.actions]]Copy Anchor Link

[[automations.actions.fields]]Copy Anchor Link

[[automations.actions.fields.options]]Copy Anchor Link

[checkout]Copy Anchor Link

[checkout.delivery_rates]Copy Anchor Link

[runtime]Copy Anchor Link

[knowledge]Copy Anchor Link

[metafields]Copy Anchor Link

[[metafields.definitions]]Copy Anchor Link

[mcp]Copy Anchor Link

[[mcp.tools]]Copy Anchor Link

On this page