Build a marketplace app
List an app that works with a shop's orders, payments and invoices through a key with only the scopes it needs.
An app is your own service: accounting sync, a CRM, an ERP bridge, analytics. A shop's owner installs it from the dashboard's Marketplace page. We then call your install URL with a key that reaches only the scopes your listing names. The owner never sees the key and can remove the app at any time, which revokes the key at once. You never handle the shop's customers' money: the platform routes payments, and a paid app is a line on the shop's monthly invoice from us.
Getting listed
Write to the team from the community page with your app's name, a one-line summary, the category (accounting, crm, erp, analytics or other), the price a month (or free), the scopes it needs and an https install URL. We add you as a builder and the app as a draft, and send you its signing secret once. We review the app against a sandbox install before it is listed.
Scopes
Ask for the fewest that work. Write includes read.
orders:read, orders:write | /v1/orders and an order's routes |
payments:read, payments:write | /v1/payments, /v1/authorisations and /v1/payment_methods |
customers:read, customers:write | the shop's customers |
catalogue:read, catalogue:write | the items and their stock |
shipments:read, shipments:write | shipments and returns |
invoices:read | the shop's GST invoices |
exports:read | /v1/exports/{report} |
events:read | /v1/webhook_events, the event explorer, to follow what happened |
No scope reaches refunds, the API keys, the webhook endpoints, the team, the shop's settings or the marketplace itself. The seller_id in the install call says which shop the key is for. A call outside the key's scopes answers 403 out_of_scope.
The install call
When the owner installs your app we POST JSON to your install URL, signed like every webhook: X-Signature: t=<unix>,v1=<hex>, an HMAC-SHA256 with your signing secret over the timestamp, a dot and the body. Verify it with the SDK's webhook check, as in the webhooks guide. X-Event-Type is app.install or app.uninstall.
{
"type": "install",
"install_id": "8c1e…",
"seller_id": "2f7a…",
"shop": "Meena Stores",
"environment": "live",
"api_key": "sk_live_…",
"scopes": ["invoices:read", "orders:read"],
"api_base": "https://pay.example.in/v1",
"at": "2026-11-10T10:00:00Z"
}
Store the key against the install_id and answer 2xx within ten seconds. Any other answer, or none, and the install is undone: the key is revoked before the owner sees the result. An owner who tries the app in the sandbox sends "environment": "test" with an sk_test_ key on their sandbox; a sandbox install is free.
On removal, or if we delist the app, you get "type": "uninstall" with the same install_id and no key. The key has already stopped working. Delete what you hold for that shop as your terms say.
Calling the API
Use the key as any other: Authorization: Bearer sk_live_…, an Idempotency-Key on a POST, and the SDKs for Node and Java work unchanged. Rate limits are the shop's.
Money
A paid app is billed on the shop's monthly invoice for the days it was installed. Each month you get a statement of what each of your apps billed, what the shops paid, and your share of what they paid, which we pay to your bank account.