Skip to main content

The app.json Manifest

The app.json file is the heart of your SitePack App. It acts as a manifest that defines your app's identity, permissions, user interface extensions, and webhook subscriptions. When a merchant installs your app, SitePack reads this file to understand how to integrate your service into their store.

The Manifest Structure​

The app.json is a standard JSON file containing several key sections. Below is a breakdown of the most important fields.

Basic Information​

These fields define your app's identity in the SitePack App Marketplace and Admin.

  • id: A unique, URL-friendly identifier for your app (e.g., sitepack-shipping-expert).
  • name: The display name of your app as seen by merchants.
  • version: The current version of your app (using Semantic Versioning).
  • author: Your name or company name.
  • description: A short summary of what your app does.
  • category: The marketplace category (e.g., Logistics, Marketing, Tools).
  • icon_url: A URL to a square PNG or SVG icon for your app.

Authentication (auth)​

This section defines how SitePack should handle the OAuth 2.0 flow for your app.

  • redirect_uri: The endpoint on your server where SitePack will send the authorization code.
  • scopes: An array of permissions your app requires (e.g., orders:read, products:write). Only request the minimum scopes needed for your app to function.

Setup & Configuration (setup)​

Define where the merchant should be directed to complete the app setup.

  • onboarding_url: The URL where the merchant is sent immediately after installation to link their account or perform initial setup.
  • configuration_url: The settings page for your app, accessible from the SitePack Admin App list.

Admin UI (admin_ui)​

Extend the SitePack Admin interface with your own navigation items and widgets.

  • navigation: Add custom menu items to the SitePack Admin sidebar.
    • label: The text to display in the menu.
    • path: The relative path within your app's admin interface.
    • icon: An icon identifier (e.g., truck, settings).
  • widgets: Embed your app's functionality directly into existing SitePack Admin pages.
    • location: Where the widget should appear (e.g., admin.order.detail.sidebar).
    • src: The URL of the page to iframe into the widget.
    • height: The reserved height for the iframe.

Theme Extensions (theme_extensions)​

Define how your app interacts with the storefront.

  • app_blocks: Register snippets that can be injected into SitePack Themes using the {% app_block %} tag.
    • target: The identifier used in the theme to place your block (e.g., product_page_info).
    • snippet: The path to the Twig snippet within your app's bundle (if applicable).

Webhooks (webhooks)​

Subscribe to real-time events happening in the store.

  • topic: The event you want to listen to (e.g., order.created, product.deleted).
  • address: The HTTPS endpoint on your server where SitePack will POST the event data.
  • format: Usually json.

Support (support)​

Provide contact information for merchants who need help with your app.

  • email: Your support email address.
  • docs_url: A link to your app's documentation.

Full Example​

Here is a complete example of a valid app.json file for a shipping integration:

{
  "id": "sitepack-shipping-expert",
  "name": "Shipping Expert Pro",
  "version": "2.1.0",
  "author": "Logistics Solutions B.V.",
  "description": "Automatiseer je verzendlabels en track & trace voor PostNL, DHL en DPD.",
  "category": "Logistics",
  "icon_url": "https://cdn.shippingexpert.com/assets/icon.png",

  "auth": {
    "redirect_uri": "https://api.shippingexpert.com/auth/callback",
    "scopes": [
      "orders:read",
      "orders:write",
      "products:read",
      "customers:read"
    ]
  },

  "setup": {
    "onboarding_url": "https://app.shippingexpert.com/setup",
    "configuration_url": "https://app.shippingexpert.com/settings"
  },

  "admin_ui": {
    "navigation": [
      {
        "label": "Verzendlabels",
        "path": "/shipping-labels",
        "icon": "truck"
      }
    ],
    "widgets": [
      {
        "id": "label-generator-sidebar",
        "location": "admin.order.detail.sidebar",
        "src": "https://app.shippingexpert.com/widgets/order-sidebar",
        "height": "300px"
      }
    ]
  },

  "theme_extensions": {
    "app_blocks": [
      {
        "id": "shipping-estimator",
        "label": "Shipping Cost Estimator",
        "target": "product_page_info",
        "snippet": "snippets/estimator.twig"
      }
    ]
  },

  "webhooks": [
    {
      "topic": "order.created",
      "address": "https://api.shippingexpert.com/webhooks/order-created",
      "format": "json"
    },
    {
      "topic": "product.deleted",
      "address": "https://api.shippingexpert.com/webhooks/product-cleanup"
    }
  ],

  "support": {
    "email": "support@shippingexpert.com",
    "docs_url": "https://docs.shippingexpert.com"
  }
}