adobe avatar

commerce-app-management

Skills for Adobe Commerce App Management — scaffold and configure Commerce apps using the aio-commerce-sdk.

GitHub stars
332

Install

/plugin install commerce-app-management@adobe-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add adobe/skills.

Contents

Discovered from source

Skills 7

Configure Commerce App Admin UI

Adds or modifies the adminUi block in an existing app.commerce.config.ts. The Admin UI extension point (commerce/backend-ui/2) lets a Commerce app extend the Commerce Admin with custom grid columns, mass actions, order, invoice, credit memo, and return view buttons, native UI form replacements, a menu entry, and custom ACL resources. Other extensibility domains (webhooks, events, business config) are added separately via their own skills.

Prerequisites

  • Verify the app is scaffolded and initialized, not merely that the config exists. Require both:
    • app.commerce.config.ts present in the project root, and
    • the project initialized — signalled by the generated src/commerce-extensibility-1/ directory and installed node_modules (the @adobe/aio-commerce-lib-app dependency).
  • If app.commerce.config.ts is missing, stop and invoke commerce-app-init first (it writes the config, then runs init).
  • If the config is present but the project is not initialized (no src/commerce-extensibility-1/ or node_modules), run npx @adobe/aio-commerce-lib-app init before continuing. Init is idempotent — it finds the existing config, skips the interactive prompts, installs dependencies, and generates the project files.
  • Actions can be authored in TypeScript only once the project has the TypeScript build setup (webpack-config.cjs + root tsconfig.json) that init scaffolds for a TypeScript Commerce config — see commerce-app-init. Otherwise, author actions in JavaScript.

Extension points at a glance

Extension pointEntitiesVariantsServer handlerReference
Grid columnsorder, product, customer, invoice, creditMemo, shipment, newsletterworker onlyyesgrid-columns
Mass actionsorder, product, customerview / workerworker onlymass-actions
Order view buttonsorder onlyview / workerworker onlyorder-view-buttons
Invoice view buttonsinvoice onlyview / workerworker onlyinvoice-view-buttons
Credit memo view buttonscreditMemo onlyview / workerworker onlycredit-memo-view-buttons
Return view buttonsrma onlyview / workerworker onlyrma-view-buttons
Native UI formssupported form targets (adminUi.nativeUi.replacedPages)view (iframe)nonative-ui-replaced-pages
Menusingle entry (adminUi.menu)view (iframe)nomenu
Custom ACLlist (adminUi.acl)nonenocustom-acl

view renders an iframe into the app's web UI (web-src) at the entry's path; worker invokes a runtime action server-side. Native UI form replacement pages also render in an iframe at their path. Custom ACL resources have no variant and no handler: they are standalone permissions Commerce renders in the User Roles tree, and the app checks them itself (see custom-acl). Grid columns are always worker; native UI form replacements and the menu are always iframes.

Step 1 — Understand intent

For each thing the user wants to add, gather:

  • Which extension point — grid columns, mass actions, order, invoice, credit memo, or return view buttons, menu, native UI form replacements, or custom ACL resources
  • Which entity — grid columns support order, product, customer, invoice, creditMemo, shipment, or newsletter; mass actions support only order, product, customer, or newsletter; view buttons support order, invoice, creditMemo, and rma; native UI replacement targets are listed in native-ui-replaced-pages; menu and custom ACL resources have no entity
  • For mass actions and view buttons, the variant — worker (runtime action) or view (iframe into web-src)
  • The fields for that extension point (column definitions, button labels, menu parent, etc.) — see the reference file in the table above for the full field set

Step 2 — Declare in app.commerce.config.ts

Add (or merge into) the top-level adminUi block, preserving all other domains. If adminUi already exists, merge into it rather than replacing — keep existing entities, the menu, and existing array entries.

These fields are shared across the extension points:

FieldConstraint
runtimeAction<package>/<action>; must resolve to a handler action you declare (Step 4)
confirmOptional { title?, message? } — confirmation dialog before the action runs
notificationsOptional { success?, error? } — toast text Commerce shows on completion
sandboxPermissionsOptional array (view/iframe entries); non-empty, no duplicates; each one of allow-downloads, allow-modals, allow-popups

Minimal example covering each feature (use only the parts you need):

import { MENU_SALES } from "@adobe/aio-commerce-sdk/admin-ui/menu";

// inside defineConfig({ ... }):
adminUi: {
  order: {
    // Custom column on the order grid (worker only)
    gridColumns: {
      label: "Fulfillment data",
      description: "Fulfillment status from the warehouse system.",
      runtimeAction: "my-app/order-grid", // <package>/<action> — declare in Step 4
      columns: [
        { id: "fulfillment_status", label: "Fulfillment", type: "string", align: "left" },
      ],
    },
    // Bulk action on selected orders (worker variant shown)
    massActions: [
      { type: "worker", id: "archive-orders", label: "Archive",
        runtimeAction: "my-app/archive-orders", selectionLimit: 500 },
    ],
    // Button on the order view page (worker variant shown)
    viewButtons: [
      { type: "worker", id: "sync-inventory", label: "Sync inventory",
        runtimeAction: "my-app/sync-inventory" },
    ],
  },
  // Replace the native order creation form with an app page
  nativeUi: {
    replacedPages: [
      {
        target: "order.create",
        path: "#/create-order",
        title: "Create Order (App)",
      },
    ],
  },
  // Custom Admin menu entry (iframe into the app)
  menu: {
    id: "my_app_dashboard", // letters, digits, / : _ only
    label: "My Dashboard",
    description: "Custom dashboard for my app.",
    parentMenu: MENU_SALES,
  },
  // Custom ACL resources — standalone permissions the app checks itself (no handler)
  acl: [
    { id: "reports", label: "Reports", children: [
      { id: "export", label: "Export" },
    ]},
    { id: "approve_refunds", label: "Approve Refunds" },
  ],
}

For the view variants (iframe) and the complete field set and constraints of each extension point, read the matching reference file under References before writing.

Step 3 — Register the extension point

Run init so that commerce/backend-ui/2 is added to app.config.yaml and install.yaml, and the src/commerce-backend-ui-2/ extension folder is generated. This is idempotent — safe to run even if the extension is already registered.

npx @adobe/aio-commerce-lib-app init

The build derives the extension's ext.config.yaml from your adminUi config: each worker runtimeAction becomes a workerProcess operation, and when you declare a menu, native UI replaced page, or any view-type entry, a view operation plus an explicit web: web-src key are written. Those hooks, operations, and web sections are managed by the library — do not hand-edit them.

When a view operation is present, init/generate also scaffolds the web frontend automatically (skipped if web-src/index.html already exists). It generates src/commerce-backend-ui-2/web-src/ — index.html, src/app.jsx, src/pages/main-page.jsx, src/components/welcome.jsx (.tsx plus an independent tsconfig.json when the app config is TypeScript) — adds the #web/* import alias to package.json, and declares and installs pinned versions of react, react-dom, @react-spectrum/s2, and @adobe/aio-commerce-lib-admin-ui (React and Spectrum S2 are optional peer dependencies of the admin-ui library), plus some devDependencies for proper TypeScript and Babel support/config. A separate required-file phase runs on every generation to ensure a set of web source support files is present without replacing existing versions. The current set includes web-src/.babelrc, which selects React's automatic JSX transform for each environment so development builds retain JSX diagnostics while production builds do not emit jsxDEV calls. If BABEL_ENV is set, keep it synchronized with NODE_ENV, because Babel gives BABEL_ENV precedence when selecting the configuration environment. TypeScript scaffolds also add typecheck:web-src to the project’s composed typecheck script. Do not hand-pick different versions of these dependencies; the scaffold fails if incompatible versions are already installed.

If the scaffold is skipped because web-src already exists, check its package.json for classic React Spectrum (@adobe/react-spectrum or @react-spectrum/<component> without s2) instead of @react-spectrum/s2. The two are compatible, but S2 is the version Adobe recommends moving to and the one this scaffold targets — suggest upgrading. This skill only configures the Admin UI extension, it doesn't drive the upgrade itself, so point the user to the commerce-app-migrate skill for the actual migration:

npx skills add adobe/skills --skill commerce-app-migrate

Do not install it or perform the upgrade yourself unless the user asks.

Step 4 — Implement the handlers

What you implement depends on the variant. Examples below are in TypeScript; if the project uses JavaScript, omit type imports and annotations.

Worker variants (grid columns, worker mass actions, worker view buttons)

Each worker runtimeAction needs an action you declare and implement, inside the Admin UI extension folder src/commerce-backend-ui-2/.

  1. Put the handler source under src/commerce-backend-ui-2/actions/.
  2. Declare it in src/commerce-backend-ui-2/ext.config.yaml under your own package in runtimeManifest (any package name). The build manages hooks and operations in this file but preserves the packages you add under runtimeManifest, so your action survives rebuilds:
# src/commerce-backend-ui-2/ext.config.yaml
runtimeManifest:
  packages:
    my-app: # must match the <package> in runtimeAction
      actions:
        order-grid:
          function: actions/order-grid/index.js # relative to src/commerce-backend-ui-2/
          web: "yes"
          runtime: nodejs:26
          annotations:
            require-adobe-auth: true # Commerce calls the action with an IMS token — validate it
            final: true

The <package>/<action> in runtimeAction maps directly: my-app/order-grid → package my-app, action order-grid. Commerce invokes these worker actions with an Adobe IMS token, so they need require-adobe-auth: true (and final: true to lock the bound inputs).

Implement the handler with the wire-contract builders from the @adobe/aio-commerce-sdk/admin-ui/* entrypoints. The builders differ per extension point — the reference file gives the exact request shape and response builders. Grid columns example:

// src/commerce-backend-ui-2/actions/order-grid/index.ts
import {
  parseGridRequest,
  okGridResponse,
  errorGridResponse,
} from "@adobe/aio-commerce-sdk/admin-ui/grid-columns";
import type { RuntimeActionParams } from "@adobe/aio-commerce-sdk/core/params";

export async function main(params: RuntimeActionParams) {
  const { gridType, ids } = parseGridRequest(params);
  try {
    const rows = await fetchRows(gridType, ids);
    // row keys must match the column ids declared in config
    return okGridResponse(rows, { fulfillment_status: "unknown" });
  } catch (error) {
    return errorGridResponse(
      500,
      error instanceof Error ? error.message : String(error),
    );
  }
}

View variants (view mass actions, view buttons, native UI forms, menu)

No server handler. Commerce opens an iframe into the app's web-src at the entry's path — and that frontend was generated for you in Step 3 (index.html, src/app.jsx, src/pages/main-page.jsx, src/components/welcome.jsx). The generated src/app.jsx mounts the commerce/backend-ui/2 iframe app with createExtensionApp from @adobe/aio-commerce-lib-admin-ui/web, and its routes array must start with the index route:

// src/commerce-backend-ui-2/web-src/src/app.jsx (generated)
import { createExtensionApp } from "@adobe/aio-commerce-lib-admin-ui/web";
import "@react-spectrum/s2/page.css";

import config from "#app.commerce.config";
import { MainPage } from "#web/pages/main-page.jsx";

createExtensionApp({
  metadata: { extensionId: config.metadata.id },
  routes: [{ index: true, element: <MainPage /> }],
});

Just as the worker variants wire a runtimeAction to an action, each view entry's path must be wired to a page and a route. Scaffold that wiring per entry — but only create what is missing. Never overwrite or modify an existing page or route.

The menu has no path: it renders at the index route (src/pages/main-page.jsx), which the scaffold already created as a plain page. There is nothing to scaffold for the menu — leave main-page.jsx in place (customize its content if you like). It needs only the MENU_* constant for parentMenu in the config (see menu).

For each view-type mass action and order, invoice, credit memo, or return view button, and native UI form replacement (all carry a path):

  1. Check for the route. Look in src/app.jsx for a routes entry whose path equals the entry's config path, and in web-src/src/pages/ for its page file. If a route for that path already exists, leave it and its page untouched and move on.

  2. Create the placeholder page (missing only). Add web-src/src/pages/<name>.jsx — use .tsx (and TypeScript) when the app config is TypeScript. Keep it minimal, matching the look of the generated main-page/welcome (a <main> with a heading). Do not add a copyright header — the generated web-src files carry none. Pre-wire the context hook for the entry type (table below).

  3. Register the route in src/app.jsx (missing only). Import the page via the #web/pages/* alias and append a { path, element } entry to routes. Write path as the exact same string as the config path, including the leading #/ — copy it verbatim so the route and the config entry visibly line up. Keep the index route first.

Pre-wire the hook by view type — all from @adobe/aio-commerce-lib-admin-ui/web:

View entryContext hookAlsoReference
Mass action (view)useMassActionContext() → { data, error }; use data.selectedIdsuseHostConnection() → { actions, error }; use actions.close()mass-actions
Order view buttonuseOrderViewButtonContext() → { data, error }; use data.orderIduseHostConnection() → { actions, error }; use actions.close()order-view-buttons
Invoice view buttonuseInvoiceViewButtonContext() → { data, error }; use data.invoiceIduseHostConnection() → { actions, error }; use actions.close()invoice-view-buttons
Credit memo view buttonuseCreditMemoViewButtonContext() → { data, error }; use data.creditMemoIduseHostConnection() → { actions, error }; use actions.close()credit-memo-view-buttons
Return view buttonuseRmaViewButtonContext() → { data, error }; use data.rmaIduseHostConnection() → { actions, error }; use actions.close()rma-view-buttons
Native UI formnonenonenative-ui-replaced-pages
Menunone (plain index page)—menu

These hooks return errors instead of throwing them. A route can throw a returned error during render to send it to the SDK's error boundary, which replaces the extension content with its fallback UI. If the route must stay mounted, handle the error locally by rendering a message, offering a retry, disabling the affected feature, or providing another degraded state. The placeholder examples below throw because they don't define custom recovery UI.

A route component may also call useIms() and useCommerce() to reach the Commerce REST API or retrieve data directly from the host, respectively. Both return { data, error }; after handling error, read data.imsToken and data.imsOrgId from useIms(), and data.commerceHost from useCommerce(). The generated Welcome component demonstrates this result handling for useIms(). Add those hooks only when the page actually needs them.

Example — a view mass action placeholder page and its route registration:

// src/commerce-backend-ui-2/web-src/src/pages/export-customers.jsx
import {
  useHostConnection,
  useMassActionContext,
} from "@adobe/aio-commerce-lib-admin-ui/web";

export function ExportCustomersPage() {
  const { data, error: contextError } = useMassActionContext();
  const { actions, error: hostError } = useHostConnection();
  if (contextError) throw contextError;
  if (hostError) throw hostError;

  const { selectedIds } = data; // non-empty string[] — the selected record ids
  const { close } = actions; // await close() (or actions.closeWithError()) when done

  return (
    <main>
      <h1>Export customers</h1>
      <p>{selectedIds.length} selected</p>
    </main>
  );
}
// src/commerce-backend-ui-2/web-src/src/app.jsx
import { createExtensionApp } from "@adobe/aio-commerce-lib-admin-ui/web";
import "@react-spectrum/s2/page.css";

import config from "#app.commerce.config";
import { MainPage } from "#web/pages/main-page.jsx";
import { ExportCustomersPage } from "#web/pages/export-customers.jsx";

createExtensionApp({
  metadata: { extensionId: config.metadata.id },
  routes: [
    { index: true, element: <MainPage /> }, // keep the index route first
    { path: "#/export-customers", element: <ExportCustomersPage /> }, // path === config `path`
  ],
});

For an order view button, swap the hook for useOrderViewButtonContext() and read data.orderId after handling error — see order-view-buttons.

Calling your own action from a menu/view page

A menu or view page sometimes needs to fetch its own data — a custom menu page rendering a table, for example — instead of receiving it from Commerce. For that, it calls one of the app's own actions directly from web-src.

Whenever an extension declares both actions and web-src, aio app build/aio app dev auto-generate web-src/src/config.json (config.web.injectedConfig) with every action's live URL — gitignored, regenerated on every build, nothing to scaffold by hand:

// src/commerce-backend-ui-2/web-src/src/hooks/use-config.js
import { useCallback } from "react";
import actionUrls from "../config.json";

export function useConfig() {
  return { getActionUrl: useCallback((action) => actionUrls[action], []) };
}

// Usage — combine with useIms() for the auth headers:
import { useIms } from "@adobe/aio-commerce-lib-admin-ui/web";

const { data, error } = useIms();
if (error) throw error;

const response = await fetch(getActionUrl("my-app/order-grid"), {
  headers: {
    authorization: `Bearer ${data.imsToken}`,
    "x-gw-ims-org-id": data.imsOrgId, // required for require-adobe-auth: true actions, or the request fails
  },
});

Step 5 — Validate

Build the project to confirm the updated config is valid:

aio app build

A build failure with a validation error points directly to the offending adminUi field.

Common Issues

  • view vs worker mismatch: each variant is a strict object — a worker entry requires runtimeAction (and rejects path/sandboxPermissions); a view entry requires path (and rejects runtimeAction/timeout). They are discriminated by type.
  • Grid columns are worker-only: there is no view grid column. order, product, customer, invoice, creditMemo, shipment, and newsletter support gridColumns; only order, product, customer, and newsletter support massActions; only order, invoice, creditMemo, and rma support viewButtons (rma supports viewButtons only).
  • runtimeAction with no handler: a worker entry whose <package>/<action> is not declared under runtimeManifest in src/commerce-backend-ui-2/ext.config.yaml leaves the generated workerProcess reference unresolved at deploy.
  • Wrong action location: handler sources and their runtimeManifest entry belong in the Admin UI extension folder src/commerce-backend-ui-2/ — not src/commerce-extensibility-1/ (where webhook and event handlers live). The function path is relative to src/commerce-backend-ui-2/.
  • Grid row keys must match column ids: keys in the okGridResponse rows must equal the ids in gridColumns.columns, or cells render empty (or fall back to the defaults bag).
  • View route path: register the { path } in src/app.jsx as the exact same string as the entry's config path — copy it verbatim, hash included, so the two line up.
  • Menu id charset: the menu id allows only letters, digits, /, :, and _ — no hyphens or spaces.
  • defineConfig not found: import defineConfig from @adobe/aio-commerce-lib-app/config.
  • Double renders/requests in development: local builds served by aio app dev and aio app run are development builds, where createExtensionApp wraps the app in React <StrictMode> — so components render twice and effects run an extra setup + cleanup cycle on mount. Duplicate renders or effect-triggered requests during local development are expected StrictMode behavior, not a bug to fix. aio app build and aio app deploy produce production builds, which render without <StrictMode> (it is stripped from the bundle).

Quality Bar

  • aio app build completes without errors
  • Every worker runtimeAction has a matching action declared under runtimeManifest in src/commerce-backend-ui-2/ext.config.yaml

Chaining

After aio app build passes:

  • Add merchant settings — invoke commerce-app-business-config to expose configurable settings in Commerce Admin
  • Add webhook interceptors — invoke commerce-app-webhooks to intercept Commerce operations
  • Add event subscriptions — invoke commerce-app-eventing to subscribe to Commerce or external events
  • Add persistent storage — invoke commerce-app-storage to back worker actions with queryable DB storage

References

Wire API Mesh in Front of a Commerce App

Composes Commerce's own GraphQL API and this app's runtime actions into a single mesh schema. Two moves this skill covers: exposing a runtime action as a mesh source, and extending an existing Commerce type with a field resolved by delegating to that source.

This skill assumes general API Mesh knowledge (mesh.json anatomy, handler types, transforms, hooks, secrets, CORS, generic declarative/programmatic resolvers). If any of that is unfamiliar, load it from Adobe's own material first — see References — rather than guessing at syntax. None of that material covers extending an existing Commerce type via additionalResolvers (targetTypeName/sourceTypeName/requiredSelectionSet/sourceSelectionSet) or wrapping an aio-commerce-sdk runtime action as a mesh source — that's what follows.

Prerequisites

  • aio plugins install @adobe/aio-cli-plugin-api-mesh is installed.
  • If exposing a runtime action as a source, it's already built and deployed with a real, reachable HTTPS endpoint — a source pointing at an undeployed action fails opaquely.
  • Check whether a mesh already exists for this workspace: aio api-mesh:get. "No mesh found" → you'll create; otherwise you're editing an existing mesh.json and will update.

Step 1 — Confirm schema shapes via introspection

Before writing additionalTypeDefs or additionalResolvers, introspect the Commerce (or other) GraphQL source you're extending. Don't assume a type/field name from memory or a similar-sounding convention — near-miss names produce a mesh that builds successfully but whose resolver never fires.

curl -s -X POST "<graphql-endpoint>" -H "Content-Type: application/json" \
  -d '{"query":"{ __type(name: \"<TargetType>\") { fields { name } } }"}'

Step 2 — Scaffold sources

{
  "name": "Commerce",
  "handler": {
    "graphql": {
      "endpoint": "<commerce-graphql-endpoint>",
      "operationHeaders": { "Authorization": "{context.headers.authorization}" }
    }
  }
}

Include operationHeaders by default on any source whose schema has customer-, cart-, or session-scoped fields — API Mesh does not forward the caller's Authorization header automatically. Omitting it makes every authenticated query fail with the backend's own generic "not authorized" error, indistinguishable from an invalid token.

To wrap a runtime action, write a small static OpenAPI document describing just its endpoint and reference it by relative path:

{
  "name": "<SourceName>",
  "handler": { "openapi": { "source": "./mesh/<source>.json" } }
}

The OpenAPI document itself needs enough shape for the mesh to generate a Query field from it — not just the pointer above. Minimal example for a single-endpoint runtime action:

{
  "openapi": "3.0.0",
  "info": { "title": "<SourceName>", "version": "1.0.0" },
  "servers": [{ "url": "<runtime-action-base-url>" }],
  "paths": {
    "/<action-path>": {
      "get": {
        "operationId": "<sourceField>",
        "parameters": [
          {
            "name": "<arg>",
            "in": "query",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": { "<resultField>": { "type": "string" } }
                }
              }
            }
          }
        }
      }
    }
  }
}

operationId becomes the Query field name — it must match sourceFieldName in Step 3's resolver exactly, or the resolver builds successfully but never fires.

The declared response schema must match what the action actually returns — the mesh parses according to what you declare, it doesn't reshape data.

Step 3 — Extend a type and wire the resolver

"additionalTypeDefs": "extend type <TargetType> { <newField>: String }",
"additionalResolvers": [
  {
    "targetTypeName": "<TargetType>",
    "targetFieldName": "<newField>",
    "sourceName": "<SourceName>",
    "sourceTypeName": "Query",
    "sourceFieldName": "<sourceField>",
    "requiredSelectionSet": "{ <keyField> }",
    "sourceArgs": { "<arg>": "{root.<keyField>}" },
    "sourceSelectionSet": "{ <resultField> }",
    "result": "<resultField>"
  }
]

Always pair sourceSelectionSet with result when extracting a scalar from an object-returning source field — never use result alone. The result-only path builds its selection set by hand instead of via the GraphQL parser, and breaks with "No type was found for field node ... __typename" specifically when the target field resolves inside a list (e.g. a parent's items[].<newField>). A direct root-query call to the same source field succeeds even when this bug is present, so that test alone isn't sufficient proof the resolver works.

Step 4 — Deploy and verify

If you already know a browser-based app will call this mesh, decide responseConfig.CORS now, before your first deploy — the browser-verification tier below exists to catch a missed CORS config, but deciding upfront avoids a second deploy cycle.

responseConfig.CORS has (at least) two independent dimensions that both need to be right — origin and allowedHeaders — and a correct origin entry says nothing about whether allowedHeaders is complete. Don't decide allowedHeaders by guessing or by copying ["Content-Type", "Authorization"] from an example: read the consuming storefront's own config first and allowlist every custom header sent by whichever GraphQL client(s) actually point at this endpoint, not just the ones a first failed request happens to reveal. In an AEM/EDS storefront built on aem-boilerplate-commerce, header sets are scoped per fetch client in config.json's headers block (e.g. headers.all for the core commerce client, headers.cs for a separate Catalog Service client) — check the scope(s) that correspond to whichever client(s) you're repointing at this mesh, not every scope in the file regardless of relevance. Adding one rejected header at a time from live CORS errors is a multi-round-trip trap — each fix only surfaces the next missing header, and it reads as repeated basic failures to whoever is watching, especially mid-demo.

Before widening allowedHeaders for a header like Store, check whether it's redundant: if the graphql source already hardcodes an equivalent value via operationHeaders (e.g. "Store": "default"), the mesh doesn't need the client to send it at all, and the leaner fix is dropping that header from the storefront's outgoing request config instead of exposing it through CORS. Omitting allowedHeaders entirely is also a valid option in some CORS middleware (headers get reflected from the request instead of allowlisted) — worth checking against the current handler's docs rather than assuming an explicit list is required.

The first aio api-mesh:* call in a session opens an interactive browser login (Waiting for browser login...). An agent without browser access can't complete this itself — hand the printed login URI to the human and wait.

aio api-mesh:create mesh.json -c   # first time
aio api-mesh:update mesh.json -c   # subsequent edits

-c/--autoConfirmAction skips the interactive Are you sure you want to update the mesh: <id>? prompt. That prompt is the only checkpoint before mutating a mesh other people or systems may already depend on — reserve -c for a workspace-scoped mesh you just created yourself (e.g. in CI, or a throwaway dev workspace). When updating an existing, shared, or already-deployed mesh, omit -c and have a human confirm the prompt, or at minimum get explicit human sign-off on the diff before running the command — treat this like any other live-infrastructure change, not a routine CLI call.

Provisioning is asynchronous — poll rather than assume completion:

until aio api-mesh:status 2>&1 | grep -qi success; do sleep 20; done

Verify in two tiers: first the source's root field directly, then the field in its real nested/authenticated shape (a list-nested query with a real caller credential, not a flat root-field call). Tier 1 passing does not prove tier 2 works — the bug above is invisible in tier 1.

If the consuming app will call this mesh directly from a browser (not just server-to-server), add a third tier: a real request from that app's actual origin. The two tiers above only prove server-side reachability — a mesh with no responseConfig.CORS entry for that origin passes both while still failing every browser call through it, not just the new field (see the CORS section of the api-mesh-starter-kit reference below).

Common Issues

  • "not authorized" on an authenticated query, even with a valid token — the source's graphql handler is missing operationHeaders. Check mesh.json, not the token.
  • "No type was found for field node ... __typename" on a nested/list field, but the source works fine at root — the resolver uses result without sourceSelectionSet. Add it.
  • Browser console shows Request header field <X> is not allowed by Access-Control-Allow-Headers in preflight response, but a server-side curl/CLI call to the same mesh works fine — this is a CORS allowedHeaders gap, not a schema/resolver bug; curl and aio api-mesh:status skip the browser preflight entirely, so they can't catch it. Read the storefront's own config for the full header set sent by whichever client is calling this endpoint (see Step 4), fix allowedHeaders for all of them at once, and check first whether the header is redundant before just appending it to the list.

Quality Bar

  • aio api-mesh:status reports success, and the new field resolves correctly in its real nested/authenticated shape, not just at the source's root field.
  • If a browser-based app will call this mesh, that app can complete a real request against it — not just aio api-mesh:status and curl.

Chaining

  • The source doesn't exist yet as a runtime action — invoke commerce-app-storage, commerce-app-webhooks, or commerce-app-eventing to scaffold and deploy it first.

References

  • API Mesh prompting guide — Adobe's own guidance for prompting an agent to write mesh configs; general workflow and expectations
  • api-mesh-starter-kit llm.txt — reference knowledge base covering mesh.json anatomy, all three handler types, transforms, hooks, secrets, context state, CORS, and the CLI command set

Configure Commerce App Business Config

Adds or modifies the businessConfig.schema array in an existing app.commerce.config.ts. Each entry in the schema defines one merchant-configurable setting that Commerce Admin will render as a UI field. Other extensibility domains (webhooks, events) are added separately via their own skills.

Prerequisites

  • Verify the app is scaffolded and initialized, not merely that the config exists. Require both:
    • app.commerce.config.ts present in the project root, and
    • the project initialized — signalled by the generated src/commerce-extensibility-1/ directory and installed node_modules (the @adobe/aio-commerce-lib-app dependency).
  • If app.commerce.config.ts is missing, stop and invoke commerce-app-init first (it writes the config, then runs init).
  • If the config is present but the project is not initialized (no src/commerce-extensibility-1/ or node_modules), run npx @adobe/aio-commerce-lib-app init before continuing. Init is idempotent — it finds the existing config, skips the interactive prompts, installs dependencies, and generates the project files.

Step 1 — Understand intent

For each setting the user wants to expose, gather:

  • Name — machine identifier for the field (used as the config key read by the app at runtime)
  • Type — one of: list, text, password, email, url, tel, boolean
  • Label (optional) — human-readable label shown in Admin
  • Description (optional) — help text shown alongside the field in Admin
  • Default value (optional, type-dependent — see constraints in Step 2)
  • For list fields additionally: selectionMode ("single" or "multiple") and options (each with a label and value string)

Step 2 — Derive config values

Apply the following per-type validation rules before writing. Surface any issues to the user before proceeding.

FieldConstraint
nameRequired, non-empty string
typeRequired; one of list, text, password, email, url, tel, boolean
labelOptional string
descriptionOptional string
list.selectionModeRequired for list fields: "single" or "multiple"
list.optionsRequired for list fields; each option needs both label and value strings
list/single defaultRequired; must match one of the option value strings (non-empty)
list/multiple defaultOptional array of strings (defaults to []); each element must match an option value
text defaultOptional string (defaults to "")
password defaultMust be "" — any non-empty default is rejected to prevent secrets in config
email defaultOptional; "" or a fully valid email address
url defaultOptional; "" or a fully valid absolute URL
tel defaultOptional; "" or matches /^\+?[0-9\s\-()]+$/ (digits, spaces, hyphens, parens, optional +)
boolean defaultOptional boolean (defaults to false)

businessConfig.schema must contain at least one field — an empty array is rejected at build time.

Step 3 — Update app.commerce.config.ts

Add (or merge into) the top-level businessConfig.schema array, preserving all other domains. If the config already has a businessConfig key, append to businessConfig.schema rather than replacing it.

Minimal examples:

businessConfig: {
  schema: [
    // Password (masked input — API keys, secrets)
    { name: "api_key", type: "password", label: "API Key", default: "" },

    // Single-select list
    {
      name: "region", type: "list", selectionMode: "single",
      label: "Region",
      options: [{ label: "EU", value: "eu" }, { label: "US", value: "us" }],
      default: "eu",   // required; must match an option value
    },

    // Boolean toggle
    { name: "debug_mode", type: "boolean", label: "Enable Debug Mode", default: false },

    // Dynamic list — options resolved at runtime via a factory that receives the action's params.
    // Required `default` factory for single-select; optional for multiple (falls back to []).
    {
      name: "paymentMethod", type: "dynamicList", selectionMode: "single",
      label: "Default Payment Method",
      options: async (params) => {
        const methods = await fetchPaymentMethods(params.SOME_API_KEY);
        return methods.map((m) => ({ label: m.title, value: m.code }));
      },
      default: (resolvedOptions) => resolvedOptions[0].value,
    },
  ],
}

See assets/business-config.ts for the full reference showing all field types.

Step 4 — Register the extension point

Run init so that commerce/configuration/1 is added to app.config.yaml and install.yaml, and the required @adobe/aio-commerce-lib-config dependency is installed. This is idempotent — safe to run even if the extension is already registered.

npx @adobe/aio-commerce-lib-app init

Step 5 — Validate

Build the project to confirm the updated config is valid:

aio app build

A build failure with a validation error points directly to the offending field.

Reading config in runtime actions

Use @adobe/aio-commerce-lib-config to read the values merchants set in Commerce Admin. The library must be initialized with the generated schema on every action invocation before any config call.

Basic pattern

import {
  initialize,
  getConfigurationByKey,
  getConfiguration,
  byCodeAndLevel,
} from "@adobe/aio-commerce-lib-config";
// Schema is generated by `aio app build` into .generated/configuration-schema.json
// under the commerce-configuration-1 extension; adjust the relative path for your action.
import schema from "../../.generated/configuration-schema.json" with { type: "json" };

export async function main(params) {
  await initialize({ schema });

  // Required to decrypt `password` fields — see "Password fields" below
  const options = { encryptionKey: params.AIO_COMMERCE_CONFIG_ENCRYPTION_KEY };

  // Read a single field — config is null if the key has never been set
  const { config } = await getConfigurationByKey(
    "api_key", // the `name` from your schema
    byCodeAndLevel("global", "global"), // scope
    options,
  );
  const apiKey = config?.value ?? "";

  // Read all fields for a scope
  const { config: allConfig } = await getConfiguration(
    byCodeAndLevel("global", "global"),
    options,
  );
  // allConfig is an array of { name, value, origin } entries

  return { statusCode: 200, body: { success: true } };
}

Scope selectors

SelectorWhen to use
byCodeAndLevel("global", "global")App-wide settings — applies to all stores
byCodeAndLevel(storeCode, "store_view")Per store view (most specific)
byCode(storeCode)Resolves using the default level for the scope
byScopeId(scopeId)When you have the scope's numeric ID from Commerce

Values inherit from parent scopes — a field not set on store_view falls back to store, website, then global.

Password fields

aio app build generates AIO_COMMERCE_CONFIG_ENCRYPTION_KEY automatically into .env the first time it encounters a password field (and validates it on subsequent builds). No manual setup needed.

The library does not read the key from the environment. Pass it as the encryptionKey option on every getConfigurationByKey, getConfiguration, and setConfiguration call, as in the example above. A call that reads or writes a non-empty password value without it throws Encryption key has not been given.

The key reaches params only if the action declares it as an input. Add it to the inputs of every action that makes these calls in ext.config.yaml — declaring it on one action does not make it available to the others:

inputs:
  AIO_COMMERCE_CONFIG_ENCRYPTION_KEY: $AIO_COMMERCE_CONFIG_ENCRYPTION_KEY

With the option and the input in place, password values are returned as plaintext.

Common Issues

  • list/single default missing: Single-select list fields require a default — it can't be omitted. It must exactly match one of the option value strings.
  • Encryption key has not been given: A config call touched a stored password value without the encryptionKey option, or the action does not declare the AIO_COMMERCE_CONFIG_ENCRYPTION_KEY input, so params.AIO_COMMERCE_CONFIG_ENCRYPTION_KEY is undefined.
  • defineConfig not found: Ensure @adobe/aio-commerce-lib-app is installed and defineConfig is imported from @adobe/aio-commerce-lib-app/config.

Quality Bar

  • aio app build completes without errors

Chaining

After aio app build passes:

  • Add webhook interceptors — invoke commerce-app-webhooks to intercept Commerce operations before or after they execute
  • Add event subscriptions — invoke commerce-app-eventing to subscribe to Commerce or external events
  • Extend the Admin UI — invoke commerce-app-admin-ui to add custom columns, mass actions, order view buttons, or menu entries in Commerce Admin

References

Configure Commerce App Eventing

Adds or modifies event sources — Commerce-native events or external events — in an existing app.commerce.config.ts. Extensibility domains other than eventing (webhooks, business config) are added separately via their own skills.

Prerequisites

  • Verify the app is scaffolded and initialized, not merely that the config exists. Require both:
    • app.commerce.config.ts present in the project root, and
    • the project initialized — signalled by the generated src/commerce-extensibility-1/ directory and installed node_modules (the @adobe/aio-commerce-lib-app dependency).
  • If app.commerce.config.ts is missing, stop and invoke commerce-app-init first (it writes the config, then runs init).
  • If the config is present but the project is not initialized (no src/commerce-extensibility-1/ or node_modules), run npx @adobe/aio-commerce-lib-app init before continuing. Init is idempotent — it finds the existing config, skips the interactive prompts, installs dependencies, and generates the project files.
  • Actions can be authored in TypeScript only once the project has the TypeScript build setup (webpack-config.cjs + root tsconfig.json) that init scaffolds for a TypeScript Commerce config — see commerce-app-init. Otherwise, author actions in JavaScript.
  • Ensure CloudIntegrationSDK (I/O Events) and commerceeventing (Adobe I/O Events for Adobe Commerce) are subscribed in the Developer Console workspace:
    1. List currently subscribed services:

      aio console workspace api list --projectName <project> --workspaceName <workspace> --json
      
    2. If either service is missing, re-subscribe with the full merged set of service codes (existing + missing). aio console workspace api add replaces the subscription list — omitting a currently-subscribed service will remove it.

      aio console workspace api add \
        --projectName <project> \
        --workspaceName <workspace> \
        --service-code <existing-codes>,CloudIntegrationSDK,commerceeventing \
        --json
      

      If the command fails with "product profile required" for commerceeventing, ask the user for the profile name and retry with --license-config commerceeventing=<profile>.

Step 1 — Understand intent

Ask whether the user wants to configure Commerce events, external events, or both:

  • Commerce events (eventing.commerce): native Commerce events. Names follow plugin.<segments> or observer.<segments>.
  • External events (eventing.external): events from third-party systems (e.g., ERP, CRM). Names are free-form ([\w\-_.]+).

For each event source, gather:

  • Provider label, description, and optional key
  • For each event: name, label, description, and which runtime action(s) should handle it (format: <package>/<action>)
  • For Commerce events only: fields to extract from the event payload (empty array captures the full payload), and any optional filter rules
  • Optionally, which Commerce environments the event applies to (env)

Step 2 — Derive config values

Apply the following validation rules before writing the config. Surface any issues to the user before proceeding.

FieldConstraint
Commerce event nameStarts with plugin. or observer.; each segment matches [a-z_]+; max 180 chars
External event name[\w\-_.]+; max 180 chars
Provider labelMax 100 chars
Provider descriptionMax 255 chars
Provider keyOptional; alphanumeric + hyphens only; max 50 chars
Event labelMax 100 chars
Event descriptionMax 255 chars
Field name[a-zA-Z0-9_\-.[\]]+ or *
Rule operatorgreaterThan, lessThan, equal, regex, in, or onChange
Runtime action<package>/<action> (e.g., my-package/handle-order-placed)
Event env (optional)Non-empty array of "paas" / "saas"; omitted = all environments

Step 3 — Update app.commerce.config.ts

Add or merge eventing.commerce and/or eventing.external into the existing config, preserving all other domains. If the config already has an eventing key, extend it rather than replacing it.

Minimal example (Commerce event):

eventing: {
  commerce: [{
    provider: { label: "Commerce Events Provider", description: "..." },
    events: [{
      name: "plugin.order_placed",          // plugin.<segments> or observer.<segments>
      label: "Order Placed",
      description: "Triggered when a customer places an order.",
      fields: [{ name: "order_id" }],       // empty array = full payload; Commerce events only
      runtimeActions: ["my-package/handle-order-placed"], // <package>/<action>
    }],
  }],
}

See assets/eventing-config.ts for the full reference including external event sources.

Creating the handler action

For events that reference runtime actions via runtimeActions, create the action file under src/actions/ and register it in app.config.yaml.

Register the action

Add a user-defined package to src/commerce-extensibility-1/ext.config.yaml alongside the existing app-management package. Use any name except app-management (reserved by the framework):

# src/commerce-extensibility-1/ext.config.yaml
# (add below the auto-generated app-management package)
runtimeManifest:
  packages:
    app-management:
      # ... auto-generated — do not edit
    my-app: # your package name — any name except "app-management"
      actions:
        handle-order-placed:
          function: actions/handle-order-placed/index.js # relative to src/commerce-extensibility-1/
          web: "no"
          runtime: nodejs:26
          annotations:
            require-adobe-auth: false

The <package>/<action> format in runtimeActions maps directly: my-app/handle-order-placed → package my-app, action handle-order-placed.

Handler skeleton

Event handlers receive a CloudEvents-shaped payload. params.data bundles the event payload together with metadata, so don't read fields directly off params.data: params.data.value is the event payload — the fields declared in the event's fields array (or the full payload if fields is empty); params.data._metadata is Commerce instance metadata; params.data.source is the merchant/environment ID pair configured in the Commerce eventing configuration.

Payload shape varies by event — check the Adobe Commerce events reference for the specific event name before deciding on a fields path. Some events nest the payload in a sub-object (e.g. value.order.entity_id); others put the fields flat on value (e.g. value.order_id), as in the example below.

// src/commerce-extensibility-1/actions/handle-order-placed/index.ts
export async function main(params: Record<string, unknown>) {
  const data = params.data as Record<string, unknown>;
  const value = data.value as Record<string, unknown>;
  // value contains the fields declared in the event's `fields` array
  // (or the full payload if fields is empty)

  const orderId = value.order_id;

  // process the event ...

  return { statusCode: 200, body: { processed: true } };
}

Numeric-looking fields aren't guaranteed to be numbers — Commerce serializes some as strings inconsistently, even within the same event (e.g. an id field delivered as "3" while a total on that same payload stays a number). Validate and coerce before comparing or forwarding a field, and skip (don't throw) when it doesn't coerce cleanly:

function toFiniteNumber(value: unknown): number {
  if (typeof value === "number" && Number.isFinite(value)) {
    return value;
  }

  if (typeof value === "string" && value.trim() !== "") {
    const parsed = Number(value);
    if (Number.isFinite(parsed)) {
      return parsed;
    }
  }

  throw new Error(`Could not convert "${value}" to a finite number`);
}

Calling the Commerce REST API from a handler

If the handler needs to call the Commerce REST API (e.g. to fetch additional order data), use getCommerceClient from @adobe/aio-commerce-lib-app instead of reinventing config or env-based access to the Commerce instance (e.g. a custom .env variable such as AIO_COMMERCE_API_BASE_URL, or a business config field for the base URL). The SDK already stores the Commerce base URL and deployment type from the app's association, so getCommerceClient resolves them for you:

// src/commerce-extensibility-1/actions/handle-order-placed/index.ts
import { getCommerceClient } from "@adobe/aio-commerce-lib-app";
import { resolveImsAuthParams } from "@adobe/aio-commerce-lib-auth";

export async function main(params: Record<string, unknown>) {
  const data = params.data as Record<string, unknown>;
  const value = data.value as Record<string, unknown>;
  const orderId = value.order_id;

  const client = await getCommerceClient(resolveImsAuthParams(params));
  const order = await client.get(`orders/${orderId}`).json();

  // process the event using order details ...

  return { statusCode: 200, body: { processed: true } };
}

The client's base URL already includes the REST prefix and API version (rest/<store>/V1 for PaaS, V1 for SaaS) — pass only the resource path (orders/${orderId}, not V1/orders/${orderId} or rest/all/V1/orders/${orderId}).

See Accessing the Associated Commerce Instance from Runtime Actions for the full pattern, including handling the unassociated state (AssociationRecordNotFoundError).

Step 4 — Regenerate the installation action

If eventing is the first install-requiring domain in the config (the others are webhooks, adminUi, installation.customInstallationSteps), re-run:

npx @adobe/aio-commerce-lib-app init

This is what adds the installation action to ext.config.yaml's app-management package — aio app build/aio app deploy only read the existing file, they never regenerate it. Skip this and Commerce has no endpoint to call, so the event source builds and deploys fine but never actually gets subscribed. Safe to re-run even when the action already exists.

Step 5 — Validate

Build the project to confirm the updated config is valid:

aio app build

A build failure with a validation error points directly to the offending config field. If this event source needed Step 4, also check that ext.config.yaml now has actions.installation under app-management.

Common Issues

  • External event has fields: The fields property is only valid on Commerce events; external events don't support it.
  • runtimeActions format error: Must be <package>/<action>. Both parts are lowercase alphanumeric + hyphens only.
  • app-management package name conflict: The framework generates this package in ext.config.yaml on every build. Use any other name for your own actions.
  • Function path is relative to src/commerce-extensibility-1/: Do not use src/... or project-root-relative paths. actions/handle-order-placed/index.js resolves correctly; src/commerce-extensibility-1/actions/handle-order-placed/index.js does not.
  • defineConfig not found: Ensure @adobe/aio-commerce-lib-app is installed and defineConfig is imported from @adobe/aio-commerce-lib-app/config.
  • Build fails on missing action: A runtime action referenced in runtimeActions must exist in the project. Check the action files under src/commerce-extensibility-1/actions/ and create any missing stubs.
  • Handler needs the Commerce base URL: Use getCommerceClient (@adobe/aio-commerce-lib-app), not a custom .env variable or business config field. See Calling the Commerce REST API from a handler.
  • Event deployed but Commerce never subscribes it: init wasn't re-run after adding the first install-requiring domain (Step 4) — no installation action, no install endpoint.
  • Numeric field arrives as a string: don't assume typeof value.field === "number" — an id/qty/total field can be serialized as a string even when other fields on the same event stay numeric. Coerce with Number(...) and check Number.isFinite before using it.

Quality Bar

  • aio app build completes without errors
  • installation action present in ext.config.yaml when this event source requires it
  • Numeric fields extracted from the event payload are coerced/validated before use, not assumed to already be numbers

Chaining

After aio app build passes:

  • Add webhook interception — invoke commerce-app-webhooks to intercept Commerce operations
  • Add merchant settings — invoke commerce-app-business-config to expose configurable settings in Commerce Admin
  • Extend the Admin UI — invoke commerce-app-admin-ui to add custom columns, mass actions, or menu entries in Commerce Admin
  • Add persistent storage — invoke commerce-app-storage to back event handlers with queryable DB storage

References

Initialize a new Commerce App

Scaffolds a bare Adobe Commerce app: creates app.commerce.config.ts with metadata, then runs init to install dependencies and generate all required project files. Extensibility domains (events, webhooks, business config) are added separately via domain skills.

Step 1 — Create the config

If app.commerce.config.ts already exists in the project root, do not overwrite it — skip straight to Step 2 (this skill is safe to re-invoke on an app that already has a config). Otherwise, derive values for the following fields from the user's intent, confirm, and write the file to the project root:

// app.commerce.config.ts
import { defineConfig } from "@adobe/aio-commerce-lib-app/config";

export default defineConfig({
  metadata: {
    id: "my-commerce-app", // alphanumeric + hyphens only, max 100 chars
    displayName: "My Commerce App", // shown in App Management UI, max 50 chars
    description: "...", // max 255 chars
    upgradeMode: "manual", // optional; currently defaults to "manual" while upgrade execution stabilizes (will default to "auto" once ready); "auto" (experimental) runs upgrades after deploy and waits for completion, "manual" returns plans without executing them
    version: "1.0.0", // Major.Minor.Patch only, no pre-release identifiers
  },
});

See assets/app.commerce.config.ts for the full annotated template.

Step 2 — Initialize the project

Always run init — it finds the existing config, validates it, and handles project setup:

npx @adobe/aio-commerce-lib-app init

Since app.commerce.config.ts already exists, init skips the interactive prompts. Re-running is safe: when a config is present it installs dependencies and (re)generates the project files — the app-management package is regenerated, while user packages under src/commerce-extensibility-1/actions/ are preserved (see Project structure below).

For a TypeScript Commerce config, init also creates missing webpack-config.cjs and root tsconfig.json files, installs compatible typescript, ts-loader, @tsconfig/bases, and @types/node development dependencies, and adds typecheck:actions to the project's composed typecheck script. Generated Runtime actions remain JavaScript. Once this scaffolding is in place, user-authored runtime actions (added via the domain skills below) and custom installation scripts (commerce-app-storage) can be written in .ts — see the aio-commerce-lib-app usage guide for the full migration steps if converting an existing JavaScript project.

Project structure

After init, the project has two types of directories under src/:

  • src/commerce-extensibility-1/actions/ — custom runtime actions for webhooks and events. Register them in src/commerce-extensibility-1/ext.config.yaml under a user-defined package name (any name except app-management, which is reserved by the framework). These survive aio app build — the generator only regenerates the app-management package.
  • src/commerce-extensibility-1/.generated/ — auto-generated by aio app build. Treat as read-only; any manual edits here will be overwritten.
  • src/commerce-configuration-1/ — managed by aio app build. Treat as read-only.
  • Root tsconfig.json — checks the TypeScript Commerce config and generated Runtime actions while excluding Admin UI web-src, which has its own TypeScript configuration.

Step 3 — Verify the config

Build the project to confirm everything is valid:

aio app build

If the config is invalid, the build fails with a detailed validation error pointing to the offending field.

Common Issues

  • id validation error: metadata.id accepts alphanumeric characters and hyphens only — no dots, underscores, or spaces. It cannot change during an upgrade; uninstall and reinstall the app to use a different ID.
  • version validation error: Only numeric semver is accepted (1.0.0). Pre-release identifiers (1.0.0-beta) are not supported.
  • defineConfig not found: Ensure @adobe/aio-commerce-lib-app is installed and imported from @adobe/aio-commerce-lib-app/config.

Quality Bar

  • aio app build completes without errors

Chaining

After aio app build passes:

  1. Bootstrap the Developer Console — for any follow-up topic related to App Builder setup (Console project/workspace, API subscriptions, deploy, run, workspace wiring), invoke skill appbuilder-project-init (from adobe/skills). Tell it:

    • Skip the aio app init steps — the Commerce scaffold already exists
    • Subscribe AdobeIOManagementAPISDK (I/O Management API) as part of the workspace bootstrap — required for IMS credential syncing at runtime
    • Once the workspace is created, ask the user whether their Commerce backend is ACCS (Adobe Commerce as Cloud Service) or PaaS. If ACCS, ACCS-REST-API must also be subscribed: run aio console open to open the workspace in the browser, then add it manually through the Developer Console UI. Do not proceed until the user confirms it has been added.

    If appbuilder-project-init is not installed, ask the user to install it first:

    npx skills add adobe/skills --skill appbuilder-project-init -y
    
  2. Extend with domain skills — once the workspace is wired:

    • commerce-app-eventing — manage Commerce and external event sources
    • commerce-app-webhooks — manage webhook interception
    • commerce-app-business-config — manage custom business configuration
    • commerce-app-admin-ui — extend the Commerce Admin UI with custom columns, mass actions, order view buttons, or menu entries
    • commerce-app-storage — back runtime actions with persistent, queryable DB storage

References

Add Database Storage to a Commerce App

Integrates App Builder Database Storage into an existing Commerce app and scaffolds a runtime action that uses @adobe/aio-lib-db to read and write documents. The library is MongoDB-like: data lives in collections of documents, queried with familiar filters.

The db-access code is identical regardless of action type — what differs is how the action is registered and what its handler returns:

  • Web action — HTTP-invokable (web: "yes"); returns a response built with the responses helpers from @adobe/aio-commerce-lib-core.
  • Event/webhook action — invoked by a Commerce event or webhook; referenced from app.commerce.config.ts via commerce-app-eventing (runtimeActions) or commerce-app-webhooks (runtimeAction).

Prerequisites

  • Verify the app is scaffolded and initialized, not merely that the config exists. Require both:
    • app.commerce.config.ts present in the project root, and
    • the project initialized — signalled by the generated src/commerce-extensibility-1/ directory and installed node_modules (the @adobe/aio-commerce-lib-app dependency).
  • If app.commerce.config.ts is missing, stop and invoke commerce-app-init first (it writes the config, then runs init).
  • If the config is present but the project is not initialized (no src/commerce-extensibility-1/ or node_modules), run npx @adobe/aio-commerce-lib-app init before continuing. Init is idempotent — it finds the existing config, skips the interactive prompts, installs dependencies, and generates the project files.
  • Actions and custom installation scripts can be authored in TypeScript only once the project has the TypeScript build setup (webpack-config.cjs + root tsconfig.json) that init scaffolds for a TypeScript Commerce config — see commerce-app-init. Otherwise, author them in JavaScript.
  • The App Builder Data Services API (API code AppBuilderDataServicesSDK) must be added to the project in the Adobe Developer Console — in every workspace that uses the database (no special license beyond App Builder). Without it, runtime actions cannot authenticate to the database service.

Step 1 — Provision the workspace database

There is a strict one-to-one relationship between an AIO project workspace and a workspace database. The recommended way to provision it is declaratively in app.config.yaml — the database is provisioned (if not already present) on aio app deploy:

application:
  runtimeManifest:
    database:
      auto-provision: true
      region: emea # amer | apac | emea | aus — the single source of truth for the region

Extension-only apps need a workaround. Due to a bug in the aio app CLI plugin (not aio-lib-db), aio app deploy only runs declarative auto-provision when the application runtime manifest has at least one package with a runtime action. Apps built purely with extensions (the recommended layout per the submission guidelines) have no application actions, so deploy silently skips provisioning. Make the application block "real enough" for provisioning to run by adding an empty packages map and a post-app-build hook that creates the directory the provisioning step expects:

application:
  hooks:
    post-app-build: "mkdir -p dist/application/actions" # provisioning expects this dir to exist
  runtimeManifest:
    packages: {} # empty map — required by the config schema so the application block validates with no actions
    database:
      auto-provision: true
      region: emea # single source of truth — see the region callout below

For local development, declarative auto-provisioning does not run during aio app run / aio app dev. Provision once up front with the CLI fallback (self-service, no special permissions). The aio app db … commands are only available once the storage CLI plugin is installed:

aio plugins install @adobe/aio-cli-plugin-app-storage
aio app db provision --region <amer|apac|emea|aus>

Region is a single source of truth. The region in the manifest database block must match the region passed to every initDb({ region }) call (or AIO_DB_REGION) — in every action and in the install step (Step 6). A mismatch fails the connection. Changing region is destructive: aio app db delete, update database.region in the manifest, then re-provision.

Step 2 — Install the library

npm install @adobe/aio-lib-db

For existing apps, inspect the dependency, lockfile and installed package before installing; preserve ranges and pins.

For TypeScript or checked JavaScript, check actual declaration resolution, not just the version (package types first appeared in 1.1.0):

  • Types resolve: prefer package declarations, otherwise reuse compatible application declarations. Report conflicts without silently changing application declarations.
  • No types resolve: recommend a typed release, but require approval before dependency or lockfile changes. To keep the installed version, add this comment immediately above each DB import reporting TS7016, including copied asset imports:
// @ts-expect-error -- Installed aio-lib-db has no resolvable TypeScript declarations.
import { init as initDb } from "@adobe/aio-lib-db";

The fallback leaves DB APIs untyped. Keep strict checking; do not add ambient DB bridges, downgrade dependencies, or suppress unrelated errors. Compilation does not prove runtime compatibility.

Step 3 — Understand intent

Gather from the user:

  • Action type: web action or event/webhook action (see the two shapes above).
  • Collection name and the operations needed (insert / find / update / delete).
  • Region: must match the manifest database.region (see the region callout in Step 1). Pass it to init() or set AIO_DB_REGION.

Step 4 — Register the action

Add the action to a user-defined package in src/commerce-extensibility-1/ext.config.yaml (any name except app-management, which is reserved).

include-ims-credentials: true is required on every DB action. Without it, aio-lib-db has no IMS token to authenticate with and the connection fails at runtime (and the app installation fails if the action runs during install). Do not omit this annotation.

Do not manually wire OAuth Server-to-Server credentials with AIO_COMMERCE_AUTH_IMS_* inputs. That legacy fallback is deprecated and planned for removal in a future major release.

# src/commerce-extensibility-1/ext.config.yaml
runtimeManifest:
  packages:
    app-management:
      # ... auto-generated — do not edit
    my-app: # any name except "app-management"
      actions:
        store-record:
          function: actions/store-record/index.js # relative to src/commerce-extensibility-1/
          runtime: nodejs:26
          web: "yes" # "yes" for a web action; "no" for an event/webhook action
          annotations:
            include-ims-credentials: true # REQUIRED for aio-lib-db auth
FieldConstraint
Package nameLowercase alphanumeric + hyphens; never app-management (reserved)
functionPath relative to src/commerce-extensibility-1/ — not src/... or root-relative
include-ims-credentialsMust be true — without it init() has no IMS token and the connection fails
web"yes" for HTTP-invokable web actions; "no" for event/webhook handlers
Collection nameNon-empty string; created on first write if it doesn't exist
RegionMust match the manifest database.region (amer | apac | emea | aus)

Step 5 — Implement the handler

Every handler follows the same lifecycle: resolve IMS auth → mint token → init → connect → use a collection → always close in finally.

// Web action — src/commerce-extensibility-1/actions/store-record/index.ts
import { buildErrorResponse, ok } from "@adobe/aio-commerce-lib-core/responses";
import {
  getImsAuthProvider,
  resolveImsAuthParams,
} from "@adobe/aio-commerce-lib-auth";
import { init as initDb } from "@adobe/aio-lib-db";

export async function main(params: Record<string, unknown>) {
  let client;
  try {
    // Resolve credentials injected by include-ims-credentials, then mint a raw token string.
    const authProvider = getImsAuthProvider(resolveImsAuthParams(params));
    const token = await authProvider.getAccessToken();
    const db = await initDb({ token, region: "emea" }); // must match the manifest database.region
    client = await db.connect();
    const records = client.collection("records");

    const result = await records.insertOne({
      ...(params.document as object),
      createdAt: new Date().toISOString(),
    });
    return ok({ body: { result } });
  } catch (error: any) {
    return buildErrorResponse(error.statusCode || 500, {
      body: { message: error.message },
    });
  } finally {
    if (client) await client.close(); // always close — avoids connection leaks
  }
}

Event and webhook actions both register with web: "no", but their payloads have different shapes — do not treat them as the same:

  • Event handler (wired via commerce-app-eventing): the extracted fields arrive in params.data.value. params.data also carries _metadata (Commerce instance metadata) and source (the merchant/environment ID pair from the Commerce eventing configuration) — neither is handler input.
  • Webhook handler (wired via commerce-app-webhooks): there is no data wrapper — the Commerce operation payload arrives directly on params (e.g. params.order), and the response must use the operation helpers from @adobe/aio-commerce-lib-webhooks/responses (see commerce-app-webhooks), not the plain ok/buildErrorResponse shape used above.
// Event handler — src/commerce-extensibility-1/actions/store-order/index.ts
export async function main(params: Record<string, unknown>) {
  const data = params.data as Record<string, unknown>;
  const value = data.value as Record<string, unknown>;
  let client;
  try {
    const authProvider = getImsAuthProvider(resolveImsAuthParams(params));
    const token = await authProvider.getAccessToken();
    const db = await initDb({ token, region: "emea" });
    client = await db.connect();
    await client
      .collection("orders")
      .insertOne({ orderId: value.order_id, receivedAt: new Date() });
    return ok({ body: { processed: true } });
  } finally {
    if (client) await client.close();
  }
}
// Webhook handler — src/commerce-extensibility-1/actions/log-order/index.ts
import {
  ok,
  successOperation,
} from "@adobe/aio-commerce-lib-webhooks/responses";

export async function main(params: Record<string, unknown>) {
  const order = params.order as Record<string, unknown>; // Commerce operation payload, directly on params
  let client;
  try {
    const authProvider = getImsAuthProvider(resolveImsAuthParams(params));
    const token = await authProvider.getAccessToken();
    const db = await initDb({ token, region: "emea" });
    client = await db.connect();
    await client
      .collection("orders")
      .insertOne({ orderId: order.entity_id, receivedAt: new Date() });
    return ok(successOperation());
  } finally {
    if (client) await client.close();
  }
}

See assets/db-action.ts for the full annotated reference covering all CRUD operations and cursor iteration.

Step 6 — Set up collections and indexes on install

For an App Management app, create collections and indexes with a custom installation step — a script that runs once when the app is installed from the Commerce Admin, and can be reversed on uninstall. Prefer this over creating them ad-hoc on the first request.

Author the step with defineCustomInstallationStep (an install handler plus an optional uninstall). Inside it, resolve the IMS auth params from context.params — not config — then follow the same init → connect → close lifecycle as Step 5, and call createIndex on the collection object:

// ./scripts/setup-database.ts — referenced from config as ./scripts/setup-database.ts
import { defineCustomInstallationStep } from "@adobe/aio-commerce-lib-app/management";
import {
  getImsAuthProvider,
  resolveImsAuthParams,
} from "@adobe/aio-commerce-lib-auth";
import { init as initDb } from "@adobe/aio-lib-db";

export default defineCustomInstallationStep({
  install: async (config, context) => {
    let client;
    try {
      // context.params carries the injected IMS credentials — NOT config.
      const authProvider = getImsAuthProvider(
        resolveImsAuthParams(context.params),
      );
      const token = await authProvider.getAccessToken();
      const db = await initDb({ token, region: "emea" }); // must match the manifest database.region
      client = await db.connect();

      const orders = client.collection("held_orders"); // get the collection object first
      await orders.createIndex({ order_id: 1 }, { unique: true }); // createIndex on the collection, not a name string
      return { status: "success" };
    } finally {
      if (client) await client.close(); // always close — avoids connection leaks
    }
  },
  uninstall: async (config, context) => {
    // Tear down your database state here.
    // Leave empty to preserve data across reinstalls.
  },
});

Author the install script as an ES module with export default — never module.exports. The installation action loads each step via import * as step from "<script>" and reads step.default, so the script must default-export the defineCustomInstallationStep(...) result. CommonJS breaks this: module.exports.default surfaces as step.default.default and validation fails. The script path must end in .js or .ts — author it directly in TypeScript, no separate compile step needed.

Register the step in app.commerce.config.ts under installation.customInstallationSteps. The script path points directly at your .ts file:

// app.commerce.config.ts
installation: {
  customInstallationSteps: [
    {
      script: "./scripts/setup-database.ts",
      name: "Set up held-orders collection",
      description: "Creates the held_orders collection and a unique index on order_id",
    },
  ],
},
FieldConstraint
scriptPath relative to the project root; must be an ES module (export default) ending in .js or .ts
nameNon-empty string, ≤ 255 characters; unique across all installation steps
descriptionNon-empty string, ≤ 255 characters

See assets/setup-database.ts for the full annotated install/uninstall reference.

Step 7 — Regenerate the installation action

If this custom installation step is the first install-requiring domain in the config (the others are webhooks, eventing.commerce, eventing.external, adminUi), re-run:

npx @adobe/aio-commerce-lib-app init

This is what adds the installation action to ext.config.yaml's app-management package — aio app build/aio app deploy only read the existing file, they never regenerate it. Skip this and the script never runs, even though it's registered in code and the DB action is deployed. Safe to re-run even when the action already exists.

Step 8 — Validate

Run the project's strict typecheck, including the storage runtime action. If adding a custom installation step, verify its root installation.customInstallationSteps registration produces a generated import of the configured script and that the actual compiler file list includes it. Preserve existing compiler includes and exclusions; do not add scripts/**/*.ts to compensate for missing registration.

aio app build

A build failure points directly to the offending config field. To exercise the action against the real database, deploy and invoke it (aio app deploy). If this step needed Step 7, also check that ext.config.yaml now has actions.installation under app-management.

Best practices

  • Always close connections in a finally block — leaked connections exhaust resources.

  • Match the region — the manifest database.region is the single source of truth; every init() call and the install step must use it (see the region callout in Step 1). A mismatch fails the connection silently from the caller's view.

  • Use projections (.project({ field: 1 })) and indexes (createIndex) for frequently queried fields; index fields must total ≤ 2048 bytes. For public responses, prefer inclusion projections.

    Filters select documents; projections select fields. Inclusion returns selected fields and _id by default; _id: 0 is the only exclusion allowed alongside included fields. Otherwise, do not mix inclusion and exclusion.

    const cursor = client
      .collection("records")
      .find({ status: "active" })
      .project({ _id: 0, title: 1, status: 1 });
    
  • Iterate large result sets with cursors (for await (const doc of collection.find(...))) instead of toArray() to bound memory.

  • Don't hardcode the region or secrets — prefer AIO_DB_REGION and the injected IMS token over inline values.

  • Prefer the most specific Adobe I/O library in runtime actions over the @adobe/aio-sdk umbrella — e.g. @adobe/aio-commerce-lib-auth for IMS auth and @adobe/aio-lib-core-logging for the logger — to keep action bundles small.

  • Set up collections and indexes during installation with a custom installation step (defineCustomInstallationStep, see Step 6) rather than ad-hoc on the first request — it runs once when the app is installed from the Commerce Admin and is reversible on uninstall. A generic App Builder post-app-deploy hook is only an alternative when the app is not installed through App Management.

Common Issues

  • Connection fails despite a valid token: the action is missing include-ims-credentials: true, or the App Builder Data Services API has not been added to the project in the Adobe Developer Console (see Prerequisites).

  • DB not provisioned after aio app deploy (extension-only app): a bug in the aio app CLI plugin (not aio-lib-db) skips declarative auto-provision when the application runtime manifest has no runtime action. Apply the extension-only workaround from Step 1 — add packages: {} and a post-app-build: "mkdir -p dist/application/actions" hook under application — or provision once with the CLI fallback for local dev.

  • Connection fails after a region change: the library region doesn't match the manifest database.region. Moving regions is destructive — aio app db delete, update database.region in the manifest, then re-provision (aio app deploy, or the CLI fallback for local dev).

  • Querying by _id from a string returns nothing: convert it first — new ObjectId(idString) from bson. A raw string never matches the stored ObjectId.

  • DbError vs unexpected error: errors thrown by the service have name === "DbError"; branch on it to separate database failures from application bugs.

  • findOne throws instead of returning null on no match: unlike MongoDB, a miss is not a successful null result — it throws a DbError with a message containing "Document not found". name === "DbError" alone isn't enough to detect this, since every DbError (including a genuine connection failure) has that name; check error.message too:

    function isDocumentNotFoundError(error: unknown) {
      const e = error as { name?: string; message?: string };
      return e.name === "DbError" && e.message?.includes("Document not found");
    }
    
    let existing;
    try {
      existing = await records.findOne({ order_id: orderId });
    } catch (error) {
      if (!isDocumentNotFoundError(error)) {
        throw error;
      }
    }
    

    See assets/db-action.ts for the full reference.

  • Auth fails inside an installation step: resolve the injected IMS auth params from context.params with resolveImsAuthParams(context.params) — not from config, which holds no credentials. Ensure the action is annotated with include-ims-credentials: true; manually wired AIO_COMMERCE_AUTH_IMS_* credentials are deprecated.

  • Installation step fails to load (must export a default function or object): the script was authored as CommonJS. Author it as an ES module with export default; module.exports (or module.exports.default) surfaces through the framework's import * as loader as .default.default and fails validation.

  • createIndex errors or has no effect: it must be called on a collection object (client.collection("name").createIndex({ field: 1 })), not with a collection-name string. Get the collection first, then call createIndex on it.

  • Custom installation step registered and deployed but never runs: init wasn't re-run after registering the first install-requiring domain (Step 7) — no installation action, no install endpoint.

Quality Bar

  • aio app build completes without errors
  • Every user-authored DB action declares include-ims-credentials: true in its annotations
  • The action closes the client in a finally block and initializes the library in the region declared in the manifest database block
  • installation action present in ext.config.yaml when this custom installation step requires it

Chaining

  • Wire the action to an event — invoke commerce-app-eventing and reference this action in an event's runtimeActions.
  • Wire the action to a webhook — invoke commerce-app-webhooks and reference this action via runtimeAction.
  • Trigger the action from Admin UI — invoke commerce-app-admin-ui to add a mass action, order view button, or grid column that invokes this runtime action.

References

  • assets/db-action.ts — Full annotated handler: init/connect, CRUD, cursor iteration, and the close lifecycle
  • assets/setup-database.ts — Full annotated custom installation step: install creates a collection and a unique index, uninstall drops it, with the context.params and createIndex-on-collection patterns

Configure Commerce App Webhooks

Adds or modifies webhook interceptors in an existing app.commerce.config.ts. Webhooks intercept Commerce operations — you can validate input, append data, or modify behavior before or after an operation executes. Other extensibility domains (events, business config) are added separately via their own skills.

Prerequisites

  • Verify the app is scaffolded and initialized, not merely that the config exists. Require both:
    • app.commerce.config.ts present in the project root, and
    • the project initialized — signalled by the generated src/commerce-extensibility-1/ directory and installed node_modules (the @adobe/aio-commerce-lib-app dependency).
  • If app.commerce.config.ts is missing, stop and invoke commerce-app-init first (it writes the config, then runs init).
  • If the config is present but the project is not initialized (no src/commerce-extensibility-1/ or node_modules), run npx @adobe/aio-commerce-lib-app init before continuing. Init is idempotent — it finds the existing config, skips the interactive prompts, installs dependencies, and generates the project files.
  • Actions can be authored in TypeScript only once the project has the TypeScript build setup (webpack-config.cjs + root tsconfig.json) that init scaffolds for a TypeScript Commerce config — see commerce-app-init. Otherwise, author actions in JavaScript.

Step 1 — Understand intent

Ask the user what they want to intercept and how:

  • What operation: the webhook_method (the Commerce operation, e.g., plugin.magento.catalog_product.save) and webhook_type (before or after)
  • How the handler is reached: either a runtime action in this app (runtimeAction: "<package>/<action>") or an explicit external URL (webhook.url) — these are mutually exclusive
  • Category (optional): validation (block if invalid), append (add data), or modification (alter data) — used for conflict detection
  • Batch and hook identifiers: batch_name groups related hooks; hook_name uniquely identifies this hook within the batch

Step 2 — Derive config values

Apply the following validation rules before writing. Surface any issues to the user before proceeding.

FieldConstraint
batch_name[a-zA-Z0-9_]+ only — no hyphens, dots, or spaces
hook_name[a-zA-Z0-9_]+ only — no hyphens, dots, or spaces
categoryOptional; must be validation, append, or modification
runtimeAction<package>/<action> format; mutually exclusive with webhook.url
webhook.urlMust be a valid absolute URL (https://...); mutually exclusive with runtimeAction
labelRequired, non-empty
descriptionRequired, non-empty
webhook_typeRequired; must be before or after
methodRequired; must be POST, PUT, DELETE, or GET
timeout / soft_timeoutOptional; positive integer (milliseconds)
priority / batch_orderOptional; positive integer

Step 3 — Update app.commerce.config.ts

Add entries to the top-level webhooks array (or create it), preserving all other domains. If the config already has a webhooks key, append to it rather than replacing it.

Minimal examples:

// Runtime action handler (handler lives in this app)
webhooks: [
  {
    label: "Validate Product Save",
    description: "Validates product data before saving.",
    category: "validation", // optional
    runtimeAction: "my-package/validate-product", // <package>/<action>
    webhook: {
      webhook_method: "plugin.magento.catalog_product.save",
      webhook_type: "before",
      batch_name: "my_app", // [a-zA-Z0-9_]+ only
      hook_name: "validate_product", // [a-zA-Z0-9_]+ only
      method: "POST",
    },
  },
];

// URL handler (external endpoint)
webhooks: [
  {
    label: "Fraud Check",
    description: "Calls external fraud service before order placement.",
    webhook: {
      webhook_method: "plugin.magento.sales_order.place",
      webhook_type: "before",
      batch_name: "my_app",
      hook_name: "fraud_check",
      method: "POST",
      url: "https://fraud.example.com/check", // inside webhook object, not top level
    },
  },
];

Each entry also accepts an optional env array ("paas" / "saas") to scope it to specific Commerce environments. When omitted, the webhook applies to all environments; when set, it is only subscribed at install time on the listed environments.

See assets/webhooks-config.ts for the full annotated reference.

Creating the handler action

For webhook entries that use runtimeAction, create the action file under src/actions/ and register it in app.config.yaml.

Register the action

Add a user-defined package to src/commerce-extensibility-1/ext.config.yaml alongside the existing app-management package. Use any name except app-management (reserved by the framework):

# src/commerce-extensibility-1/ext.config.yaml
# (add below the auto-generated app-management package)
runtimeManifest:
  packages:
    app-management:
      # ... auto-generated — do not edit
    my-app: # your package name — any name except "app-management"
      actions:
        validate-product:
          function: actions/validate-product/index.js # relative to src/commerce-extensibility-1/
          web: "yes"
          runtime: nodejs:26
          annotations:
            require-adobe-auth: true

The <package>/<action> format in runtimeAction maps directly: my-app/validate-product → package my-app, action validate-product.

Handler skeleton

// src/commerce-extensibility-1/actions/validate-product/index.ts
import {
  ok,
  successOperation,
  exceptionOperation,
  addOperation,
  replaceOperation,
  removeOperation,
} from "@adobe/aio-commerce-lib-webhooks/responses";

export async function main(params: Record<string, unknown>) {
  // params contains the Commerce operation payload

  // Allow the operation to proceed
  return ok(successOperation());

  // Block the operation (validation failure)
  // return ok(exceptionOperation("Product SKU is required"));

  // Append data to the operation result
  // return ok(addOperation("result/custom_field", { value: "appended" }));

  // Modify a field in the result
  // return ok(replaceOperation("result/price", 99.99));

  // Remove a field from the result
  // return ok(removeOperation("result/unwanted_field"));
}

Operation types:

ResponseEffect
successOperation()Allow — operation proceeds unchanged
exceptionOperation(message)Block — operation is rejected with this message
addOperation(path, value)Append data at path in the result
replaceOperation(path, value)Replace the value at path in the result
removeOperation(path)Remove the field at path from the result

Step 4 — Regenerate the installation action

If webhooks is the first install-requiring domain in the config (the others are eventing.commerce, eventing.external, adminUi, installation.customInstallationSteps), re-run:

npx @adobe/aio-commerce-lib-app init

This is what adds the installation action to ext.config.yaml's app-management package — aio app build/aio app deploy only read the existing file, they never regenerate it. Skip this and Commerce has no endpoint to call, so the webhook builds and deploys fine but never actually gets installed. Safe to re-run even when the action already exists.

Step 5 — Validate

Build the project to confirm the updated config is valid:

aio app build

A build failure with a validation error points directly to the offending config field. If this webhook needed Step 4, also check that ext.config.yaml now has actions.installation under app-management.

Common Issues

  • batch_name or hook_name rejected: Use underscores as separators (my_app, validate_product_save) — hyphens, dots, and spaces are not accepted.
  • Both runtimeAction and webhook.url set: These are mutually exclusive — use runtimeAction when the handler lives in this app; webhook.url for an external endpoint.
  • url at wrong level: For URL-based entries, url must be inside the nested webhook object, not at the top level alongside label.
  • app-management package name conflict: The framework generates this package in ext.config.yaml on every build. Use any other name for your own actions.
  • Function path is relative to src/commerce-extensibility-1/: Do not use src/... or project-root-relative paths. actions/validate-product/index.js resolves correctly; src/commerce-extensibility-1/actions/validate-product/index.js does not.
  • defineConfig not found: Ensure @adobe/aio-commerce-lib-app is installed and defineConfig is imported from @adobe/aio-commerce-lib-app/config.
  • Webhook deployed but Commerce never calls it: init wasn't re-run after adding the first install-requiring domain (Step 4) — no installation action, no install endpoint.

Quality Bar

  • aio app build completes without errors
  • installation action present in ext.config.yaml when this webhook requires it

Chaining

After aio app build passes:

  • Add merchant settings — invoke commerce-app-business-config to expose configurable settings in Commerce Admin
  • Add event subscriptions — invoke commerce-app-eventing to subscribe to Commerce or external events
  • Extend the Admin UI — invoke commerce-app-admin-ui to add custom columns, mass actions, order view buttons, or menu entries in Commerce Admin
  • Add persistent storage — invoke commerce-app-storage to back webhook handlers with queryable DB storage

References

Sponsors

Details

Marketplace
adobe/skills
Source
plugins/commerce/app-management
Category
Community

More from adobe/skills

All 19