The manifest
How storeware.app.toml is laid out, and what a merchant is shown for each part.
Why a file
Everything Storeware knows about your app is declared in storeware.app.toml, in your repository. Changing what it may reach is a diff somebody reviews rather than a setting somebody changed. Each deploy stores the file as written, byte for byte.
Start the file like this. The first line points your editor at the manifest's JSON Schema, so it can complete keys and flag mistakes as you type:
#:schema https://storeware.ai/docs/schemas/storeware.app.json
manifest_version = 2This page explains each part. The manifest reference lists every key with its limits, read from the schema the platform checks against.
[app]
| Key | Meaning |
|---|---|
slug | Your client id. Lower case letters, digits and hyphens. Never changes. |
name, description | What merchants see on the consent screen and in the Apps list. |
url | Your home inside the admin, opened full height with a session. |
navigation | Up to five pages inside that home: a label and a path starting with /. |
homepage_url, support_url, privacy_policy_url | Links shown to merchants. |
[oauth]
| Key | Meaning |
|---|---|
scopes | What your app may do. A merchant grants exactly these, or does not install. |
redirect_uris | Only for installs that start on your own site. Matched exactly. |
Some permissions are never granted to an app, whatever it asks: managing a shop's apps, building apps, and a developer's earnings. Permissions lists the rest.
[webhooks] and [privacy]
| Key | Meaning |
|---|---|
webhooks.url | Where events are posted. Redirects are never followed. |
webhooks.events | Topics to receive. Each needs a scope that reads the same data. |
privacy.url | Where data requests and erasures are posted. Needed with customer or order access. |
The event reference lists every topic and the scopes that cover it.
[billing]
| Key | Meaning |
|---|---|
billing.mode | managed: Storeware shows your plans at install and on your app's page. api: you ask for charges yourself. |
billing.plans.key | What you ask for, in lower_snake_case. |
billing.plans.name | What the merchant reads. |
billing.plans.interval | month (the default) or year. Charged in advance. |
billing.plans.prices | All four of usd, gbp, eur and inr, in minor units. Leave it out for a free plan. |
billing.plans.trial_days | Up to 90, once per shop. Not on a free plan. |
billing.plans.features | Up to eight short lines shown with the plan. |
billing.plans.usage | cap in all four currencies and terms in your words: charges by use, never more than the cap a period. Needs mode = "api". |
Charging merchants has a worked example.
Extensions, tools and knowledge
[[extensions.admin]]: a panel at a point in the admin, such as beside a product. See Inside the admin.[[mcp.tools]]: a tool every assistant on the shop can call. Its scopes must be among yours.[knowledge]: attributes and links your app knows about products, merged into search and every agent's view of the catalogue. Only the names you declare are kept.
URLs
Every URL must be HTTPS, except on localhost, and none may point at Storeware itself. Under app dev the localhost ones are swapped for the tunnel's in the copy that is sent; your file is not edited.
Checking it
Early access
npx @storeware/cli validatevalidate checks the manifest against the scopes and events the platform has today, and says which line is wrong.