Skip to main content

The app.json Manifest

app.json describes your app to SitePack: its name, its settings page, what it renders on the storefront and, for an API integration, which scopes and webhooks it uses. SitePack reads the manifest of the version you published last.

Where it lives​

app.json sits at the root of your app, next to the three folders SitePack publishes:

your-app-directory/
├── app.json
├── templates/       # Twig for your storefront blocks
├── assets/          # js, css, images and fonts
└── translations/    # one lowercase .json per language

Anything outside these is not uploaded by sitepack app:publish.

Basic information​

FieldRequiredWhat it is
uuidyesAssigned by SitePack when you create the app. Written by sitepack app:init or app:link; do not change it.
nameyesThe app name merchants see.
versionyesA whole number. sitepack app:publish gives each upload the next number.
descriptionyesWhat the app does, at least 10 characters. Shown in the Partner Portal and required to make the app public.
authornoYour name or company name.
menu_labelnoA shorter name for the merchant's admin menu, when name is long.
icon_urlnoPath to an icon inside your app, such as assets/img/icon.svg, shown next to your app in the merchant's admin menu. The Marketplace icon is uploaded in the Partner Portal.

Settings (admin)​

Describes the settings page the merchant fills in. Use settings_type: "abstract": SitePack renders the form from your schema.

{
  "admin": {
    "settings_type": "abstract",
    "settings_schema": {
      "type": "object",
      "properties": {
        "phone_number": { "type": "string", "title": "WhatsApp number" }
      },
      "required": ["phone_number"]
    }
  }
}

Every merchant-facing string in the schema can be a translation key. A few formats change how a string setting behaves:

  • "format": "image" becomes a media picker, see Image settings.
  • "format": "password" is a secret: a masked input in the admin, never sent to the storefront, readable only by your app's backend through the API, see Password settings.
  • "translatable": true on a free-text setting translates the merchant's value with the site, see Translations.

admin.help adds a short explanation above the form, see Help above the settings form. The field types and the iframe alternative are covered in App Settings.

Storefront (blocks and scripts)​

Runs on every page of the storefront, on the sites your app is installed on.

  • blocks: a map of block spot (head, body_start, body_end, product_form_after, ...) to a Twig template under templates/. Rendered on the server with the merchant's settings.
  • styles: stylesheets under assets/css/, linked in the <head> of every page from the app CDN (https://cdn-app.sitepack.eu/<uuid>/<version>/assets/css/<file>). Prefix your class names so they do not clash with the theme.
  • scripts: JavaScript files under assets/js/, loaded at the end of <body> as deferred classic scripts from the app CDN (https://cdn-app.sitepack.eu/<uuid>/<version>/assets/js/<file>). There is no module scope, so wrap your code in an IIFE instead of using import.
{
  "blocks": { "body_end": "whatsapp_widget.twig" },
  "scripts": ["whatsapp.js"]
}

See Storefront Blocks & Events for every block spot, the template variables and the events your script can listen to.

Post types (post_types)​

Registers your own kinds of content, such as cinemas, branches or team members. Each post type gets its own screen under Content in the merchant's admin, with a form built from the fields you declare. A public post type also gets storefront pages at /<slug> and /<slug>/<entry>.

{
  "post_types": [
    {
      "key": "cinemas",
      "name": "Cinemas",
      "singular_name": "Cinema",
      "public": true,
      "slug": "cinemas",
      "fields": [
        { "key": "city", "type": "text", "label": "City", "required": true, "column": true },
        { "key": "image", "type": "image", "label": "Photo", "column": true }
      ]
    }
  ]
}

See Post Types for every option, the field types and how themes render them.

API access (auth)​

Only for API integrations. Lists the scopes your app may ask the merchant for. A consent request can never grant more than this list.

{
  "auth": {
    "scopes": ["orders:read", "products:write"]
  }
}

Leave auth out when your app does not call the API: merchants then install it with one click from the Marketplace, and an install link shows them no permissions. The OAuth redirect URI is set in the Partner Portal, not here.

Webhooks (webhooks)​

Only for API integrations. Each entry sends one event topic to an HTTPS address on your server.

{
  "webhooks": [
    { "topic": "order.paid", "address": "https://api.your-app.com/webhooks/sitepack" }
  ]
}

Besides data topics such as order.paid or lead.created, you can subscribe to the app lifecycle topics, such as app.settings_updated. See Webhooks for every topic, the payload and how to verify the signature.

Full examples​

A storefront app​

The WhatsApp button from Your First App, trimmed:

{
  "uuid": "01a0c408-9d48-700c-b2f7-81fc01d496b7",
  "name": "WhatsApp",
  "version": 3,
  "description": "Adds a floating WhatsApp button to every storefront page.",
  "author": "SitePack",
  "icon_url": "assets/img/icon.svg",
  "admin": {
    "settings_type": "abstract",
    "settings_schema": {
      "type": "object",
      "properties": {
        "phone_number": { "type": "string", "title": "admin.settings.phone_number.title" },
        "button_color": { "type": "string", "format": "color", "default": "#25D366" }
      },
      "required": ["phone_number"]
    }
  },
  "blocks": { "body_end": "whatsapp_widget.twig" },
  "scripts": ["whatsapp.js"],
  "webhooks": []
}

An API integration​

A stock sync that also offers a small settings page:

{
  "uuid": "01a1b2c3-0000-7000-8000-000000000000",
  "name": "Stock Sync",
  "version": 12,
  "description": "Keeps stock and orders in sync between SitePack and your ERP.",
  "author": "Your company",
  "auth": {
    "scopes": ["products:read", "inventory:write", "orders:read", "app:settings:read"]
  },
  "admin": {
    "settings_type": "abstract",
    "settings_schema": {
      "type": "object",
      "properties": {
        "warehouse_code": { "type": "string", "title": "Warehouse code" },
        "sync_orders": { "type": "boolean", "title": "Send new orders to the ERP", "default": true }
      }
    }
  },
  "webhooks": [
    { "topic": "order.paid", "address": "https://api.your-app.com/webhooks/sitepack" },
    { "topic": "product.updated", "address": "https://api.your-app.com/webhooks/sitepack" }
  ]
}

Your backend reads the merchant's settings with GET /api/public/v1/app/settings, see App Settings.

Next steps​