The manifest

sentralbee.app.json is the single declarative source of your app’s identity and capabilities. It lives in your app repo, and the platform reads it at registration to mint your API key with the right scopes, wire up your embed, and — if you ask for it — surface your checkout method. Everything your app is allowed to do starts here, in one file. That’s the point of keeping it declarative: to change what the app can do, you edit one file, not code scattered across a handful of handlers. A human or an AI agent can read it top to bottom and know exactly what the app is.

A full manifest

{
	"provider": "my-app",
	"name": "My App",
	"icon": "sparkles",
	"scopes": [
		{ "pattern": "sale", "read": true },
		{ "pattern": "sale_payment", "create": true }
	],
	"embed": { "path": "/" },
	"webhooks": { "events": ["order.paid"], "path": "/webhook" },
	"checkout": {
		"create_path": "/checkout/sessions",
		"label": "Pay with My App",
		"description": "Pay by bank transfer",
		"button_color": "#2f4bff",
		"icon_path": "/icon.svg"
	}
}

Only three fields are required — provider, name, and scopes. The rest turn on the capabilities you need. An app that just embeds a UI can drop webhooks and checkout entirely.

Fields

Field	Required	Description
`provider`	✓	Stable kebab-case id (3–50 chars, lowercase letters, digits and hyphens). It’s your app’s provider, the catalog key, and — unless `audience` overrides it — your JWT `aud`. Pick it once; it identifies your app everywhere.
`name`	✓	Display name shown in the App Store.
`icon`		Icon key or emoji the dashboard renders next to your app.
`audience`		The JWT `aud` the platform mints your tokens for. Defaults to `provider` — only set it if you need the two to differ.
`scopes`	✓	Non-empty array of the permissions you request. The merchant consents to these on install, and your API key is minted to match. See below.
`embed.path`		Path, under your app’s public URL, the dashboard iframes after install. Defaults to `/`.
`webhooks.events`		Platform event types you want delivered, e.g. `["order.paid"]`.
`webhooks.path`		Path deliveries are POSTed to. Defaults to `/webhook`.
`checkout`		Present only if your app is a storefront payment method. See below.

Scopes

Each entry in scopes[] is a permission, expressed as a scope name plus the CRUD actions you need on it:

{
	"pattern": "sale_payment",
	"create": true,
	"read": true,
	"update": false,
	"delete": false
}

pattern (required) — the scope name, e.g. sale, sale_payment, product.
create / read / update / delete — the actions you need. Omitted actions default to off, so you only list what you actually use.

Request the minimum. The merchant sees exactly these on the consent screen — every extra action is one more thing they have to trust you with, and one more reason to hesitate before installing. Your API key is minted to match, so anything you didn’t ask for, you can’t do. The example above requests read on sale and create on sale_payment, and nothing else. For how scopes map to what the API will let a key do, see Scopes & permissions.

Checkout

Declaring a checkout block makes your app a payment method on storefronts. When a shopper picks your method, the platform brokers a session-authed call to your create_path, which must return { redirectUrl } pointing at your hosted pay page. The storefront renders a button using the presentation fields below, and identifies your method by the app’s top-level provider.

"checkout": {
  "create_path": "/checkout/sessions",
  "label": "Pay with Bank Transfer",
  "description": "Pay by bank transfer",
  "button_color": "#2f4bff",
  "button_text_color": "#ffffff",
  "icon_path": "/icon.svg"
}

Field	Required	Description
`create_path`	✓	Session-authed path (must start with `/`) the platform POSTs to create a checkout; returns `{ redirectUrl }`.
`label`		Button text, e.g. “Pay with Bank Transfer”.
`description`		Helper copy shown with the button.
`button_color`		CSS colour for the button background.
`button_text_color`		CSS colour for the button text.
`icon_path`		Leading icon path under your app’s public base, e.g. `/icon.svg`.

Leave checkout out entirely unless your app takes payment. The full flow — what the platform sends, what your pay page does, how the order gets marked paid — is in Checkout.

Available webhook events

List any of these under webhooks.events to have them delivered to your webhooks.path:

Event	Fires when
`order.paid`	An order is paid in full.
`order.payment_recorded`	A payment is recorded against an order (may be partial).
`import.completed`	A bulk import finishes successfully.
`import.failed`	A bulk import fails.
`webhook.ping`	A test delivery, for confirming your endpoint is wired up.

More events are added over time — check the developer portal for the current list. For verifying deliveries and handling them safely, see Webhooks.

Validate before you ship

Run sentralbee manifest to check the file. It parses sentralbee.app.json and reports every problem at once — a bad provider id, an empty scopes array, a create_path that doesn’t start with / — so you catch mistakes locally instead of at registration.

sentralbee manifest

The platform reads your manifest at registration to mint the key and wire your app. If you change what your app needs — new scopes, a new webhook event — update the manifest and re-register so the platform (and the merchant’s consent) match what your code expects.

Where to next

Concepts & lifecycle — how the platform reads your manifest at install.
Scopes & permissions — what each scope lets a key do.
Checkout — the full flow behind the checkout block.
Webhooks — verify and handle the events you subscribe to.

Get Started

Build your app

Reference

A full manifest

Fields

Scopes

Checkout

Available webhook events

Validate before you ship

Where to next

​A full manifest

​Fields

​Scopes

​Checkout

​Available webhook events

​Validate before you ship

​Where to next

A full manifest

Fields

Scopes

Checkout

Available webhook events

Validate before you ship

Where to next