Plugin Manifest Specification

Every plugin and theme ships with a manifest.json at the package root. The installer reads it to know what to register, which migrations to run, and what admin UI to expose.

Schema

{
  "id": "stripe-payment",
  "marketplace_id": "@carphacom/stripe-payment",
  "name": "Stripe Payment",
  "version": "1.2.0",
  "type": "payment",
  "carphacom_min_version": "1.0.0",
  "description": "Accept cards, SEPA, iDEAL, Klarna via Stripe.",
  "author": "CarphaCom",
  "author_url": "https://carphacom.com",
  "icon_url": "https://carphacom.com/marketplace-icons/stripe-payment.png",
  "screenshots": ["https://.../1.png", "https://.../2.png"],
  "price_eur": 0,
  "entry": "./index.js",
  "migrations": true,
  "auto_restart": true,
  "config_schema": {
    "publishable_key": {
      "type": "string",
      "label": "Stripe publishable key",
      "required": true,
      "placeholder": "pk_live_..."
    },
    "secret_key": {
      "type": "string",
      "label": "Stripe secret key",
      "required": true,
      "secret": true
    },
    "webhook_secret": {
      "type": "string",
      "label": "Webhook signing secret",
      "required": true,
      "secret": true
    }
  },
  "menu_items": [
    { "label": "Stripe Settings", "path": "/cms/plugins/stripe", "icon": "CreditCard" }
  ],
  "medusa_provider": {
    "module": "payment",
    "resolve": "./providers/stripe",
    "id": "stripe"
  }
}

Field reference

| Field | Required | Notes | |---|---|---| | id | yes | Unique identifier, lowercase + hyphens. | | marketplace_id | yes | Format @vendor/package-name. Must be unique on carphacom.com. | | name | yes | Display name. | | version | yes | Semver. | | type | yes | One of: payment, fulfillment, b2b-api, storefront-template, admin-extension, marketing. | | carphacom_min_version | yes | Minimum platform version. Installer refuses if instance is older. | | description | yes | One-line summary. Long form goes in marketplace listing. | | author, author_url | yes | Vendor name + URL. | | icon_url, screenshots | optional | Marketplace listing assets. | | price_eur | yes | 0 for free, otherwise EUR price. | | entry | yes | Path to compiled JS entrypoint. Relative to package root. | | migrations | yes | true if ships database migrations. | | auto_restart | optional | If true, installer reloads backend after install. Default true. | | config_schema | optional | JSON-Schema-like object that drives auto-generated settings UI. | | menu_items | optional | Items added to admin sidebar after install. | | medusa_provider | optional | For payment/fulfillment types — registers a Medusa provider automatically. |

config_schema field types

• string — single-line text input.
• text — multi-line textarea.
• number — numeric input.
• boolean — toggle.
• select — dropdown, requires options: [{label, value}].
• Add secret: true to mask the value in the UI and encrypt at rest.

Validation

Run npx carphacom-cli validate manifest.json before publishing. The validator checks schema, semver, ID uniqueness against the marketplace, and required field presence.