App Manifest

The qumra.app.json file is the core configuration file for your Qumra app. It defines your app's identity, permissions, webhooks, and navigation pages.

Complete Example

{
  "name": "orders-sync",
  "handle": "orders-sync",
  "version": "1.0.0",
  "description": "Sync your Qumra store orders automatically with Google Sheets or external systems.",
  "author": {
    "name": "Your Name",
    "email": "dev@example.com"
  },
  "appUrl": "http://localhost:3000",
  "oauth": {
    "required": true,
    "callback_path": "/auth/callback",
    "scopes": ["read_orders", "write_orders", "read_customers"]
  },
  "webhooks": {
    "api_version": "2025-07-01",
    "subscriptions": [
      {
        "topics": ["product/create"],
        "uri": "/product-create"
      }
    ]
  },
  "pages": [
    { "path": "/", "label": "Home" },
    { "path": "/about", "label": "About" },
    { "path": "/contacts", "label": "Contacts" }
  ],
  "scopes": [
    "READ_ORDERS",
    "WRITE_ORDERS",
    "READ_CUSTOMERS",
    "READ_PRODUCTS"
  ]
}

Manifest Fields

Field	Type	Required	Description
name	string	Yes	The display name of your app.
handle	string	Yes	A unique slug identifier for your app.
version	string	Yes	Semantic version of your app (e.g. 1.0.0).
description	string	Yes	A short description of what your app does.
author	object	Yes	Author info containing name and email.
appUrl	string	Yes	The base URL where your app is hosted.
oauth	object	No	OAuth 2.0 configuration for authentication.
webhooks	object	No	Webhook subscriptions for event-driven updates.
pages	array	No	Navigation pages displayed in the Qumra admin.
scopes	array	Yes	API permission scopes your app requires.

OAuth Configuration

The oauth object configures the OAuth 2.0 authentication flow for your app.

Field	Type	Description
oauth.required	boolean	Whether OAuth authorization is required to use the app.
oauth.callback_path	string	The path on your app that receives the OAuth callback.
oauth.scopes	string[]	Lowercase OAuth scopes requested during the authorization flow.

Webhooks Configuration

The webhooks object defines which store events your app subscribes to.

Field	Type	Description
webhooks.api_version	string	The API version for webhook payloads (e.g. 2025-07-01).
webhooks.subscriptions	array	Array of webhook subscription objects.
webhooks.subscriptions[].topics	string[]	Event topics to subscribe to (e.g. product/create).
webhooks.subscriptions[].uri	string	The endpoint path on your app that receives the webhook.

Pages Configuration

The pages array defines navigation entries that appear in the Qumra admin panel when your app is installed.

Field	Type	Description
pages[].path	string	The route path relative to your app's base URL.
pages[].label	string	The display label shown in the admin navigation menu.

Scopes Dual Definition

API permission scopes and OAuth scopes are defined separately and use different casing conventions:

• scopes (top-level) -- uses UPPERCASE values like READ_ORDERS, WRITE_ORDERS. These define the API permissions your app requires.
• oauth.scopes -- uses lowercase values like read_orders, write_orders. These are requested during the OAuth authorization flow.

Make sure both lists are consistent. If your app needs READ_ORDERS access, include READ_ORDERS in scopes and read_orders in oauth.scopes.

For a full list of available scopes, see the Scopes Reference.