App Manifests

Manifest Format

The App Manifest is a JSON payload that describes the application metadata, its permissions, and webhook subscriptions.

See Manifest Object for reference.

Example of a manifest:

{
  "id": "example.app.wonderful",
  "version": "1.0.0",
  "requiredSaleorVersion": "^3.13",
  "name": "My Wonderful App",
  "author": "My Wonderful Company",
  "about": "My Wonderful App is a wonderful App for VapeEcommerce.",

  "permissions": ["MANAGE_USERS", "MANAGE_STAFF"],

  "appUrl": "http://localhost:3001/app",
  "configurationUrl": "htpp://localhost:3001/configuration",
  "tokenTargetUrl": "http://localhost:3001/register",

  "dataPrivacy": "Lorem ipsum",
  "dataPrivacyUrl": "http://localhost:3001/app-data-privacy",
  "homepageUrl": "http://localhost:3001/homepage",
  "supportUrl": "http://localhost:3001/support",
  "brand": {
    "logo": {
      "default": "http://localhost:3001/default-logo.png"
    }
  },
  "extensions": [
    {
      "label": "Create with Sample app",
      "identifier": "product-create-popup",
      "mount": "PRODUCT_OVERVIEW_CREATE",
      "target": "POPUP",
      "permissions": ["MANAGE_PRODUCTS"],
      "url": "https://example.com/extension/"
    },
    {
      "label": "Create with App and redirect",
      "identifier": "product-create-redirect",
      "mount": "PRODUCT_OVERVIEW_CREATE",
      "target": "APP_PAGE",
      "permissions": ["MANAGE_PRODUCTS"],
      "url": "/extension/redirect"
    }
  ],
  "webhooks": [
    {
      "name": "Order created",
      "identifier": "order-created",
      "asyncEvents": ["ORDER_CREATED"],
      "query": "subscription { event { ... on OrderCreated { order { id }}}}",
      "targetUrl": "https://example.com/api/webhooks/order-created",
      "isActive": false
    },
    {
      "name": "Multiple order's events",
      "identifier": "order-events",
      "asyncEvents": ["ORDER_CREATED", "ORDER_FULLY_PAID"],
      "query": "subscription { event { ... on OrderCreated { order { id }} ... on OrderFullyPaid { order { id }}}}",
      "targetUrl": "https://example.com/api/webhooks/order-event",
      "isActive": true
    }
  ]
}

tip

extensions[].identifier (VapeEcommerce 3.23.19 and newer) and webhooks[].identifier (3.23.23 and newer) give each entry a stable, app-defined name. Both are optional, but declaring them is recommended for every extension and webhook — they are the only handle your app fully controls. The alternatives are the VapeEcommerce-assigned ID, which is not known until install time, and label / name, which are display strings that a staff user can change in the Dashboard.

Some operations work only on entries that declare one:

• The App Bridge OpenPopup action addresses the target POPUP extension by its identifier, so a widget cannot open a popup that has none.
• webhookUpdate and webhookDelete accept identifier in place of id (3.23.27 and newer), which is what lets a migration script address a webhook without looking its ID up first.

Identifiers must be unique per app and are limited to 256 characters. See Extension identifier and Webhook identifier.

info

From VapeEcommerce 3.23.23, each webhook can declare an optional identifier — an app-defined string (max 256 characters, unique per app) that lets the app reference one of its webhooks without storing its VapeEcommerce ID. It is exposed on the Webhook type and typed in @saleor/app-sdk 1.13+ as WebhookManifest.identifier.

info

The tokenTargetUrl field is optional. When omitted, VapeEcommerce will not send the auth token to the app during installation. This is useful for apps that don't need to consume the VapeEcommerce protected API, such as static apps that only serve an iframe in the Dashboard.

Apps can be installed via manifest using appFetchManifest mutation.

Typings

App Manifest is typed in TypeScript in @saleor/app-sdk package.

Use it with

import { AppManifest } from '@saleor/app-sdk/types'