App Manifest

The app manifest is a JSON document that registers your app with JTL. It declares the app’s identity, the URL JTL loads during setup, and the capabilities through which your app integrates with the platform. You register your app by pasting this manifest into the JSON Code Editor in the Partner Portal under Manage apps. You can also register an app using the registration wizard form directly.

Top-level Fields

Two fields identify the app and its release.

Property	Type	Required	Description
`technicalName`	string	Yes	Stable internal identifier for the app. Max 100 characters. Used as a fallback display name.
`version`	string	Yes	App release version. Strict semver, digits only (e.g. `1.0.0`). Pre-release tags are not allowed.

Lifecycle

The lifecycle object defines the URL JTL loads when a merchant installs your app.

Property	Type	Required	Description
`lifecycle.configurationUrl`	string	No	URL rendered in an iframe during setup. Use it to present setup UI, complete the AppBridge handshake, and persist the tenant connection.

The URL must be a standard http:// or https:// URL.

The manifest validator accepts {metadata.*} placeholders in this URL, but JTL does not substitute them at runtime. Use a static URL, and encode any app identity you need directly in the path or query string.

Identifying the App

If you publish multiple apps, each one needs its own configurationUrl. Two apps sharing the same URL cause the wrong setup UI to render when a merchant installs either one. Give each app a distinct URL, either with a separate route:

"lifecycle": {
  "configurationUrl": "https://example.com/setup/inventory-sync"
}

Or by encoding the app’s identity in the query string:

"lifecycle": {
  "configurationUrl": "https://example.com/setup?app=inventory-sync"
}

Use separate routes if you control routing and want cleaner URLs. Use query parameters if you prefer a single handler that switches behavior based on the app.

A working configuration flow is included when you create an app with the CLI, npm create @jtl-software/cloud-app@latest.

Capabilities

Capabilities define where and how your app integrates with JTL. Each key under capabilities maps to a surface. See Architecture Overview for a description of each integration type.

Hub

Controls how the app appears in the JTL Hub dashboard. When a merchant clicks the app’s card, the platform redirects to this URL.

Property	Type	Required	Description
`capabilities.hub.appLauncher.redirectUrl`	string	Required if `hub` is present	URL the platform redirects to when the app card is clicked in the Hub

Without a redirectUrl, the app card has no destination. Add entries to the ERP Cloud sidebar under the App section. Each menu item links to a page in your app, loaded inside the ERP iframe.

Property	Type	Required	Description
`id`	string	Yes	Stable internal identifier for the menu item
`name`	string	Yes	Display name shown in the navigation
`url`	string	Yes	URL loaded when the item is clicked

ERP API Scopes

Declare the JTL-Wawi API resources your app intends to use. Declared scopes are validated against the allowed list at registration.

Property	Type	Required	Description
`capabilities.erp.api.scopes`	array of string	No	API permission scopes the app requests

Scope values come from a fixed list, and any value outside it is rejected at registration. A subset for reference:

"scopes": [
  "items.read", "items.write",
  "orders.read", "orders.write",
  "customers.read", "customers.write",
  "inventory.read", "inventory.write"
]

Runtime enforcement of these scopes has not shipped yet, so declaring a scope here does not currently restrict what your app can call. Once enforcement is live, the API will reject calls that exceed the declared set, and the merchant will see the declared scopes at install time. See Scopes & Permissions for the current list.

ERP Panel

Add a sidebar panel that appears alongside an ERP view. Panels are context-aware and show only on matching pages. When more than one installed app targets the same view, each app renders as a tab within the panel, and tabs beyond the panel width collapse into an overflow menu.

Property	Type	Required	Description
`id`	string	No	Internal identifier for the panel
`context`	string	Yes	View path where the panel appears, in the form `$tenantSlug.<view>` (e.g. `$tenantSlug.customers`)
`url`	string	Yes	URL loaded inside the panel iframe
`requiredScopes`	array of string	No	Per-panel scope override, using the same scope values as `capabilities.erp.api.scopes`

For reading the current entity in a panel, see Reading Panel Context.

Complete Example

A manifest declaring a Hub redirect, one ERP menu item, three API scopes, and one panel on the customers view:

{
  "version": "1.0.0",
  "technicalName": "my-example-app",
  "lifecycle": {
    "configurationUrl": "https://example.com/configure"
  },
  "capabilities": {
    "hub": {
      "appLauncher": {
        "redirectUrl": "https://example.com/hub/launch"
      }
    },
    "erp": {
      "menuItems": [
        {
          "id": "menu-item-1",
          "name": "Mein Menüpunkt",
          "url": "https://example.com/erp/menu"
        }
      ],
      "api": {
        "scopes": ["orders.read", "orders.write", "items.read"]
      },
      "panel": [
        {
          "id": "panel-1",
          "context": "$tenantSlug.customers",
          "url": "https://example.com/erp/pane/customers",
          "requiredScopes": ["customers.read"]
        }
      ]
    }
  }
}

What’s Next?

Listing Manifest

Define how your app appears in the App Store or is shared privately.

App Shell & UI

Communicate with the host using AppBridge, and build UI with Platform UI components.

Essentials

Cloud Apps

Marketplace Channels

ERP Integration

Vouchers API

Top-level Fields

Lifecycle

Identifying the App

Capabilities

Hub

ERP Menu Items

ERP API Scopes

ERP Panel

Complete Example

What’s Next?

Listing Manifest

App Shell & UI

​Top-level Fields

​Lifecycle

​Identifying the App

​Capabilities

​Hub

​ERP Menu Items

​ERP API Scopes

​ERP Panel

​Complete Example

​What’s Next?

Listing Manifest

App Shell & UI

Top-level Fields

Lifecycle

Identifying the App

Capabilities

Hub

ERP Menu Items

ERP API Scopes

ERP Panel

Complete Example

What’s Next?