# Manifest reference

> Every key of storeware.app.toml: its value, its limits and what it does.

Source: https://storeware.ai/docs/build-apps/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](https://storeware.ai/docs/build-apps/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:

```toml
#: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}`. |