App Manifest Reference

commercit.json is an exact app-manifest.v1 document. Unknown fields fail validation. App code runs only through reviewed managed_worker.v1 handlers; the browser never supplies capabilities, grants, runtime context, secrets, URLs, or canonical commerce state.

Universal shape

{
  "contractVersion": "app-manifest.v1",
  "slug": "example-app",
  "version": "1.0.0",
  "capabilities": [],
  "schemas": [],
  "handlers": [],
  "modules": [],
  "resources": [],
  "externalServices": [],
  "secretDeclarations": [],
  "surfaces": {
    "sections": [],
    "data_sources": [],
    "actions": [],
    "admin_extensions": []
  },
  "config_schema": {
    "contractVersion": "app-installation-settings.v1",
    "fields": []
  },
  "resourceMigrations": []
}

The retired surfaces.admin_panels, surfaces.checkout_decorations, and surfaces.checkout_extensions keys are rejected. Shipping checkout extensions are declared only inside the reviewed shipping domain module.

Admin extensions

Every surfaces.admin_extensions entry freezes:

• one target from the versioned Admin target registry;
• host_components or sandbox_iframe runtime;
• one presentation, exposure, safe context projection and bounded budget;
• reciprocal action/data-source references and exact managed handlers;
• admin-extension-protocol.v1 and a minimum host version.

App Home uses admin.app.home. Contextual definitions use the Order, Product, or Customer action/block targets. App output is a typed proposal; the platform rechecks the actor permission, shop/resource/version, current installation grant and command authority before any mutation.

Sandbox definitions require an immutable artifact:<source>@sha256:<digest> and an exact artifactOriginKey. The platform builds the artifact and serves it from x-<key>.admin-ext.commercit.com with an opaque origin. Browser code declares no remote frame, script, or network URL.

Checkout extensions

Checkout extensions belong to modules[].key = "shipping" under declaration.checkoutExtensions. The frozen targets are:

• shipping.destination.select
• shipping.service.select
• shipping.option.configure

The runtimes are declarative, sandbox_iframe, and approved external_redirect. All direct origin arrays are empty in checkout-extension-protocol.v1. network:app-backend is a logical, manifest-declared browser handler mediated by the host; it is never an iframe URL or bearer credential.

The browser proposes only an opaque selection reference. Commercit re-resolves the destination, offer, price, promise, payment compatibility, checkout version, cart hash, route, connection and mode before one idempotent commit.

Artifacts and packages

Apps must include package-lock.json v3 and exact dependencies. Platform SDKs are checksum-bound vendor/*.tgz files or exact registry versions with integrity. Install uses npm ci --ignore-scripts. Every local esbuild input participates in the source identity; imports from excluded roots fail instead of being omitted.