
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-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add adobe/skills.
Contents
Discovered from sourceSkills 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.tspresent in the project root, and- the project initialized — signalled by the generated
src/commerce-extensibility-1/directory and installednode_modules(the@adobe/aio-commerce-lib-appdependency).
- If
app.commerce.config.tsis missing, stop and invokecommerce-app-initfirst (it writes the config, then runs init). - If the config is present but the project is not initialized (no
src/commerce-extensibility-1/ornode_modules), runnpx @adobe/aio-commerce-lib-app initbefore 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+ roottsconfig.json) thatinitscaffolds for a TypeScript Commerce config — seecommerce-app-init. Otherwise, author actions in JavaScript.
Extension points at a glance
| Extension point | Entities | Variants | Server handler | Reference |
|---|---|---|---|---|
| Grid columns | order, product, customer, invoice, creditMemo, shipment, newsletter | worker only | yes | grid-columns |
| Mass actions | order, product, customer | view / worker | worker only | mass-actions |
| Order view buttons | order only | view / worker | worker only | order-view-buttons |
| Invoice view buttons | invoice only | view / worker | worker only | invoice-view-buttons |
| Credit memo view buttons | creditMemo only | view / worker | worker only | credit-memo-view-buttons |
| Return view buttons | rma only | view / worker | worker only | rma-view-buttons |
| Native UI forms | supported form targets (adminUi.nativeUi.replacedPages) | view (iframe) | no | native-ui-replaced-pages |
| Menu | single entry (adminUi.menu) | view (iframe) | no | menu |
| Custom ACL | list (adminUi.acl) | none | no | custom-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, ornewsletter; mass actions support onlyorder,product,customer, ornewsletter; view buttons supportorder,invoice,creditMemo, andrma; 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) orview(iframe intoweb-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:
| Field | Constraint |
|---|---|
runtimeAction | <package>/<action>; must resolve to a handler action you declare (Step 4) |
confirm | Optional { title?, message? } — confirmation dialog before the action runs |
notifications | Optional { success?, error? } — toast text Commerce shows on completion |
sandboxPermissions | Optional 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/.
- Put the handler source under
src/commerce-backend-ui-2/actions/. - Declare it in
src/commerce-backend-ui-2/ext.config.yamlunder your own package inruntimeManifest(any package name). The build manageshooksandoperationsin this file but preserves the packages you add underruntimeManifest, 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):
-
Check for the route. Look in
src/app.jsxfor aroutesentry whosepathequals the entry's configpath, and inweb-src/src/pages/for its page file. If a route for thatpathalready exists, leave it and its page untouched and move on. -
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 generatedmain-page/welcome(a<main>with a heading). Do not add a copyright header — the generatedweb-srcfiles carry none. Pre-wire the context hook for the entry type (table below). -
Register the route in
src/app.jsx(missing only). Import the page via the#web/pages/*alias and append a{ path, element }entry toroutes. Writepathas the exact same string as the configpath, 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 entry | Context hook | Also | Reference |
|---|---|---|---|
Mass action (view) | useMassActionContext() → { data, error }; use data.selectedIds | useHostConnection() → { actions, error }; use actions.close() | mass-actions |
| Order view button | useOrderViewButtonContext() → { data, error }; use data.orderId | useHostConnection() → { actions, error }; use actions.close() | order-view-buttons |
| Invoice view button | useInvoiceViewButtonContext() → { data, error }; use data.invoiceId | useHostConnection() → { actions, error }; use actions.close() | invoice-view-buttons |
| Credit memo view button | useCreditMemoViewButtonContext() → { data, error }; use data.creditMemoId | useHostConnection() → { actions, error }; use actions.close() | credit-memo-view-buttons |
| Return view button | useRmaViewButtonContext() → { data, error }; use data.rmaId | useHostConnection() → { actions, error }; use actions.close() | rma-view-buttons |
| Native UI form | none | none | native-ui-replaced-pages |
| Menu | none (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
viewvsworkermismatch: each variant is a strict object — aworkerentry requiresruntimeAction(and rejectspath/sandboxPermissions); aviewentry requirespath(and rejectsruntimeAction/timeout). They are discriminated bytype.- Grid columns are worker-only: there is no
viewgrid column.order,product,customer,invoice,creditMemo,shipment, andnewslettersupportgridColumns; onlyorder,product,customer, andnewslettersupportmassActions; onlyorder,invoice,creditMemo, andrmasupportviewButtons(rmasupportsviewButtonsonly). runtimeActionwith no handler: a worker entry whose<package>/<action>is not declared underruntimeManifestinsrc/commerce-backend-ui-2/ext.config.yamlleaves the generatedworkerProcessreference unresolved at deploy.- Wrong action location: handler sources and their
runtimeManifestentry belong in the Admin UI extension foldersrc/commerce-backend-ui-2/— notsrc/commerce-extensibility-1/(where webhook and event handlers live). Thefunctionpath is relative tosrc/commerce-backend-ui-2/. - Grid row keys must match column ids: keys in the
okGridResponserows must equal theids ingridColumns.columns, or cells render empty (or fall back to the defaults bag). - View route
path: register the{ path }insrc/app.jsxas the exact same string as the entry's configpath— copy it verbatim, hash included, so the two line up. - Menu
idcharset: the menuidallows only letters, digits,/,:, and_— no hyphens or spaces. defineConfignot found: importdefineConfigfrom@adobe/aio-commerce-lib-app/config.- Double renders/requests in development: local builds served by
aio app devandaio app runare development builds, wherecreateExtensionAppwraps 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 buildandaio app deployproduce production builds, which render without<StrictMode>(it is stripped from the bundle).
Quality Bar
aio app buildcompletes without errors- Every worker
runtimeActionhas a matching action declared underruntimeManifestinsrc/commerce-backend-ui-2/ext.config.yaml
Chaining
After aio app build passes:
- Add merchant settings — invoke
commerce-app-business-configto expose configurable settings in Commerce Admin - Add webhook interceptors — invoke
commerce-app-webhooksto intercept Commerce operations - Add event subscriptions — invoke
commerce-app-eventingto subscribe to Commerce or external events - Add persistent storage — invoke
commerce-app-storageto back worker actions with queryable DB storage
References
- references/grid-columns.md — Grid column config and handler contract
- references/mass-actions.md — Mass action config (view and worker) and handler contract
- references/order-view-buttons.md — Order view button config (view and worker) and handler contract
- references/native-ui-replaced-pages.md — Native UI form replacement targets and page configuration
- references/invoice-view-buttons.md — Invoice view button config (view and worker) and handler contract
- references/credit-memo-view-buttons.md — Credit memo view button config (view and worker) and handler contract
- references/rma-view-buttons.md — Return (RMA) view button config (view and worker) and handler contract
- references/menu.md — Menu config and parent-menu constants
- references/custom-acl.md — Custom ACL resource config and runtime permission checks
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-meshis 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'llcreate; otherwise you're editing an existingmesh.jsonand willupdate.
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'sgraphqlhandler is missingoperationHeaders. Checkmesh.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 usesresultwithoutsourceSelectionSet. 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 CORSallowedHeadersgap, not a schema/resolver bug; curl andaio api-mesh:statusskip 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), fixallowedHeadersfor 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:statusreports 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:statusandcurl.
Chaining
- The source doesn't exist yet as a runtime action — invoke
commerce-app-storage,commerce-app-webhooks, orcommerce-app-eventingto 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.jsonanatomy, 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.tspresent in the project root, and- the project initialized — signalled by the generated
src/commerce-extensibility-1/directory and installednode_modules(the@adobe/aio-commerce-lib-appdependency).
- If
app.commerce.config.tsis missing, stop and invokecommerce-app-initfirst (it writes the config, then runs init). - If the config is present but the project is not initialized (no
src/commerce-extensibility-1/ornode_modules), runnpx @adobe/aio-commerce-lib-app initbefore 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
listfields additionally:selectionMode("single"or"multiple") andoptions(each with alabelandvaluestring)
Step 2 — Derive config values
Apply the following per-type validation rules before writing. Surface any issues to the user before proceeding.
| Field | Constraint |
|---|---|
name | Required, non-empty string |
type | Required; one of list, text, password, email, url, tel, boolean |
label | Optional string |
description | Optional string |
list.selectionMode | Required for list fields: "single" or "multiple" |
list.options | Required for list fields; each option needs both label and value strings |
list/single default | Required; must match one of the option value strings (non-empty) |
list/multiple default | Optional array of strings (defaults to []); each element must match an option value |
text default | Optional string (defaults to "") |
password default | Must be "" — any non-empty default is rejected to prevent secrets in config |
email default | Optional; "" or a fully valid email address |
url default | Optional; "" or a fully valid absolute URL |
tel default | Optional; "" or matches /^\+?[0-9\s\-()]+$/ (digits, spaces, hyphens, parens, optional +) |
boolean default | Optional 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
| Selector | When 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/singledefault missing: Single-select list fields require adefault— it can't be omitted. It must exactly match one of the optionvaluestrings.Encryption key has not been given: A config call touched a storedpasswordvalue without theencryptionKeyoption, or the action does not declare theAIO_COMMERCE_CONFIG_ENCRYPTION_KEYinput, soparams.AIO_COMMERCE_CONFIG_ENCRYPTION_KEYisundefined.defineConfignot found: Ensure@adobe/aio-commerce-lib-appis installed anddefineConfigis imported from@adobe/aio-commerce-lib-app/config.
Quality Bar
aio app buildcompletes without errors
Chaining
After aio app build passes:
- Add webhook interceptors — invoke
commerce-app-webhooksto intercept Commerce operations before or after they execute - Add event subscriptions — invoke
commerce-app-eventingto subscribe to Commerce or external events - Extend the Admin UI — invoke
commerce-app-admin-uito add custom columns, mass actions, order view buttons, or menu entries in Commerce Admin
References
- assets/business-config.ts — Reference config showing all field types with inline constraint comments
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.tspresent in the project root, and- the project initialized — signalled by the generated
src/commerce-extensibility-1/directory and installednode_modules(the@adobe/aio-commerce-lib-appdependency).
- If
app.commerce.config.tsis missing, stop and invokecommerce-app-initfirst (it writes the config, then runs init). - If the config is present but the project is not initialized (no
src/commerce-extensibility-1/ornode_modules), runnpx @adobe/aio-commerce-lib-app initbefore 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+ roottsconfig.json) thatinitscaffolds for a TypeScript Commerce config — seecommerce-app-init. Otherwise, author actions in JavaScript. - Ensure
CloudIntegrationSDK(I/O Events) andcommerceeventing(Adobe I/O Events for Adobe Commerce) are subscribed in the Developer Console workspace:-
List currently subscribed services:
aio console workspace api list --projectName <project> --workspaceName <workspace> --json -
If either service is missing, re-subscribe with the full merged set of service codes (existing + missing).
aio console workspace api addreplaces 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 \ --jsonIf 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 followplugin.<segments>orobserver.<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.
| Field | Constraint |
|---|---|
| Commerce event name | Starts with plugin. or observer.; each segment matches [a-z_]+; max 180 chars |
| External event name | [\w\-_.]+; max 180 chars |
| Provider label | Max 100 chars |
| Provider description | Max 255 chars |
| Provider key | Optional; alphanumeric + hyphens only; max 50 chars |
| Event label | Max 100 chars |
| Event description | Max 255 chars |
| Field name | [a-zA-Z0-9_\-.[\]]+ or * |
| Rule operator | greaterThan, 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: Thefieldsproperty is only valid on Commerce events; external events don't support it. runtimeActionsformat error: Must be<package>/<action>. Both parts are lowercase alphanumeric + hyphens only.app-managementpackage name conflict: The framework generates this package inext.config.yamlon every build. Use any other name for your own actions.- Function path is relative to
src/commerce-extensibility-1/: Do not usesrc/...or project-root-relative paths.actions/handle-order-placed/index.jsresolves correctly;src/commerce-extensibility-1/actions/handle-order-placed/index.jsdoes not. defineConfignot found: Ensure@adobe/aio-commerce-lib-appis installed anddefineConfigis imported from@adobe/aio-commerce-lib-app/config.- Build fails on missing action: A runtime action referenced in
runtimeActionsmust exist in the project. Check the action files undersrc/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.envvariable or business config field. See Calling the Commerce REST API from a handler. - Event deployed but Commerce never subscribes it:
initwasn't re-run after adding the first install-requiring domain (Step 4) — noinstallationaction, 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 withNumber(...)and checkNumber.isFinitebefore using it.
Quality Bar
aio app buildcompletes without errorsinstallationaction present inext.config.yamlwhen 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-webhooksto intercept Commerce operations - Add merchant settings — invoke
commerce-app-business-configto expose configurable settings in Commerce Admin - Extend the Admin UI — invoke
commerce-app-admin-uito add custom columns, mass actions, or menu entries in Commerce Admin - Add persistent storage — invoke
commerce-app-storageto back event handlers with queryable DB storage
References
- assets/eventing-config.ts — Reference config showing both Commerce and external event source shapes
- Accessing the Associated Commerce Instance from Runtime Actions — how
getCommerceClientresolves the Commerce base URL and auth for REST calls made from a handler - Adobe Commerce events reference — payload shapes per event, needed to determine the correct field path when extracting fields
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 insrc/commerce-extensibility-1/ext.config.yamlunder a user-defined package name (any name exceptapp-management, which is reserved by the framework). These surviveaio app build— the generator only regenerates theapp-managementpackage.src/commerce-extensibility-1/.generated/— auto-generated byaio app build. Treat as read-only; any manual edits here will be overwritten.src/commerce-configuration-1/— managed byaio app build. Treat as read-only.- Root
tsconfig.json— checks the TypeScript Commerce config and generated Runtime actions while excluding Admin UIweb-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
idvalidation error:metadata.idaccepts 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.versionvalidation error: Only numeric semver is accepted (1.0.0). Pre-release identifiers (1.0.0-beta) are not supported.defineConfignot found: Ensure@adobe/aio-commerce-lib-appis installed and imported from@adobe/aio-commerce-lib-app/config.
Quality Bar
aio app buildcompletes without errors
Chaining
After aio app build passes:
-
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(fromadobe/skills). Tell it:- Skip the
aio app initsteps — 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-APImust also be subscribed: runaio console opento 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-initis not installed, ask the user to install it first:npx skills add adobe/skills --skill appbuilder-project-init -y - Skip the
-
Extend with domain skills — once the workspace is wired:
commerce-app-eventing— manage Commerce and external event sourcescommerce-app-webhooks— manage webhook interceptioncommerce-app-business-config— manage custom business configurationcommerce-app-admin-ui— extend the Commerce Admin UI with custom columns, mass actions, order view buttons, or menu entriescommerce-app-storage— back runtime actions with persistent, queryable DB storage
References
- assets/app.commerce.config.ts — Minimal config template
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 theresponseshelpers from@adobe/aio-commerce-lib-core. - Event/webhook action — invoked by a Commerce event or webhook; referenced from
app.commerce.config.tsviacommerce-app-eventing(runtimeActions) orcommerce-app-webhooks(runtimeAction).
Prerequisites
- Verify the app is scaffolded and initialized, not merely that the config exists. Require both:
app.commerce.config.tspresent in the project root, and- the project initialized — signalled by the generated
src/commerce-extensibility-1/directory and installednode_modules(the@adobe/aio-commerce-lib-appdependency).
- If
app.commerce.config.tsis missing, stop and invokecommerce-app-initfirst (it writes the config, then runs init). - If the config is present but the project is not initialized (no
src/commerce-extensibility-1/ornode_modules), runnpx @adobe/aio-commerce-lib-app initbefore 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+ roottsconfig.json) thatinitscaffolds for a TypeScript Commerce config — seecommerce-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
regionin the manifestdatabaseblock must match theregionpassed to everyinitDb({ region })call (orAIO_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, updatedatabase.regionin 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 toinit()or setAIO_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: trueis required on every DB action. Without it,aio-lib-dbhas 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
| Field | Constraint |
|---|---|
| Package name | Lowercase alphanumeric + hyphens; never app-management (reserved) |
function | Path relative to src/commerce-extensibility-1/ — not src/... or root-relative |
include-ims-credentials | Must 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 name | Non-empty string; created on first write if it doesn't exist |
| Region | Must 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 inparams.data.value.params.dataalso carries_metadata(Commerce instance metadata) andsource(the merchant/environment ID pair from the Commerce eventing configuration) — neither is handler input. - Webhook handler (wired via
commerce-app-webhooks): there is nodatawrapper — the Commerce operation payload arrives directly onparams(e.g.params.order), and the response must use the operation helpers from@adobe/aio-commerce-lib-webhooks/responses(seecommerce-app-webhooks), not the plainok/buildErrorResponseshape 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— nevermodule.exports. The installation action loads each step viaimport * as step from "<script>"and readsstep.default, so the script must default-export thedefineCustomInstallationStep(...)result. CommonJS breaks this:module.exports.defaultsurfaces asstep.default.defaultand validation fails. Thescriptpath must end in.jsor.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",
},
],
},
| Field | Constraint |
|---|---|
script | Path relative to the project root; must be an ES module (export default) ending in .js or .ts |
name | Non-empty string, ≤ 255 characters; unique across all installation steps |
description | Non-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
finallyblock — leaked connections exhaust resources. -
Match the region — the manifest
database.regionis the single source of truth; everyinit()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
_idby default;_id: 0is 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 oftoArray()to bound memory. -
Don't hardcode the region or secrets — prefer
AIO_DB_REGIONand the injected IMS token over inline values. -
Prefer the most specific Adobe I/O library in runtime actions over the
@adobe/aio-sdkumbrella — e.g.@adobe/aio-commerce-lib-authfor IMS auth and@adobe/aio-lib-core-loggingfor 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 Builderpost-app-deployhook 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 theaio appCLI plugin (notaio-lib-db) skips declarative auto-provision when theapplicationruntime manifest has no runtime action. Apply the extension-only workaround from Step 1 — addpackages: {}and apost-app-build: "mkdir -p dist/application/actions"hook underapplication— 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, updatedatabase.regionin the manifest, then re-provision (aio app deploy, or the CLI fallback for local dev). -
Querying by
_idfrom a string returns nothing: convert it first —new ObjectId(idString)frombson. A raw string never matches the storedObjectId. -
DbErrorvs unexpected error: errors thrown by the service havename === "DbError"; branch on it to separate database failures from application bugs. -
findOnethrows instead of returningnullon no match: unlike MongoDB, a miss is not a successfulnullresult — it throws aDbErrorwith a message containing"Document not found".name === "DbError"alone isn't enough to detect this, since everyDbError(including a genuine connection failure) has that name; checkerror.messagetoo: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.paramswithresolveImsAuthParams(context.params)— not fromconfig, which holds no credentials. Ensure the action is annotated withinclude-ims-credentials: true; manually wiredAIO_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 withexport default;module.exports(ormodule.exports.default) surfaces through the framework'simport * asloader as.default.defaultand fails validation. -
createIndexerrors 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 callcreateIndexon it. -
Custom installation step registered and deployed but never runs:
initwasn't re-run after registering the first install-requiring domain (Step 7) — noinstallationaction, no install endpoint.
Quality Bar
aio app buildcompletes without errors- Every user-authored DB action declares
include-ims-credentials: truein its annotations - The action closes the client in a
finallyblock and initializes the library in the region declared in the manifestdatabaseblock installationaction present inext.config.yamlwhen this custom installation step requires it
Chaining
- Wire the action to an event — invoke
commerce-app-eventingand reference this action in an event'sruntimeActions. - Wire the action to a webhook — invoke
commerce-app-webhooksand reference this action viaruntimeAction. - Trigger the action from Admin UI — invoke
commerce-app-admin-uito 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.paramsandcreateIndex-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.tspresent in the project root, and- the project initialized — signalled by the generated
src/commerce-extensibility-1/directory and installednode_modules(the@adobe/aio-commerce-lib-appdependency).
- If
app.commerce.config.tsis missing, stop and invokecommerce-app-initfirst (it writes the config, then runs init). - If the config is present but the project is not initialized (no
src/commerce-extensibility-1/ornode_modules), runnpx @adobe/aio-commerce-lib-app initbefore 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+ roottsconfig.json) thatinitscaffolds for a TypeScript Commerce config — seecommerce-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) andwebhook_type(beforeorafter) - 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), ormodification(alter data) — used for conflict detection - Batch and hook identifiers:
batch_namegroups related hooks;hook_nameuniquely 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.
| Field | Constraint |
|---|---|
batch_name | [a-zA-Z0-9_]+ only — no hyphens, dots, or spaces |
hook_name | [a-zA-Z0-9_]+ only — no hyphens, dots, or spaces |
category | Optional; must be validation, append, or modification |
runtimeAction | <package>/<action> format; mutually exclusive with webhook.url |
webhook.url | Must be a valid absolute URL (https://...); mutually exclusive with runtimeAction |
label | Required, non-empty |
description | Required, non-empty |
webhook_type | Required; must be before or after |
method | Required; must be POST, PUT, DELETE, or GET |
timeout / soft_timeout | Optional; positive integer (milliseconds) |
priority / batch_order | Optional; 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:
| Response | Effect |
|---|---|
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_nameorhook_namerejected: Use underscores as separators (my_app,validate_product_save) — hyphens, dots, and spaces are not accepted.- Both
runtimeActionandwebhook.urlset: These are mutually exclusive — useruntimeActionwhen the handler lives in this app;webhook.urlfor an external endpoint. urlat wrong level: For URL-based entries,urlmust be inside the nestedwebhookobject, not at the top level alongsidelabel.app-managementpackage name conflict: The framework generates this package inext.config.yamlon every build. Use any other name for your own actions.- Function path is relative to
src/commerce-extensibility-1/: Do not usesrc/...or project-root-relative paths.actions/validate-product/index.jsresolves correctly;src/commerce-extensibility-1/actions/validate-product/index.jsdoes not. defineConfignot found: Ensure@adobe/aio-commerce-lib-appis installed anddefineConfigis imported from@adobe/aio-commerce-lib-app/config.- Webhook deployed but Commerce never calls it:
initwasn't re-run after adding the first install-requiring domain (Step 4) — noinstallationaction, no install endpoint.
Quality Bar
aio app buildcompletes without errorsinstallationaction present inext.config.yamlwhen this webhook requires it
Chaining
After aio app build passes:
- Add merchant settings — invoke
commerce-app-business-configto expose configurable settings in Commerce Admin - Add event subscriptions — invoke
commerce-app-eventingto subscribe to Commerce or external events - Extend the Admin UI — invoke
commerce-app-admin-uito add custom columns, mass actions, order view buttons, or menu entries in Commerce Admin - Add persistent storage — invoke
commerce-app-storageto back webhook handlers with queryable DB storage
References
- assets/webhooks-config.ts — Reference config showing both runtime action and URL-based webhook entry shapes
Sponsors
Details
- Marketplace
- adobe/skills
- Source
- plugins/commerce/app-management
- Category
- Community
More from adobe/skills
All 19- commerce-app-migration
- commerce-app-reviewv1.0.0
- run-workflowv1.0.0
- semrushv1.0.0
- stardustv0.39.4
- webv1.0.0
- workfrontv2.0.0
- adobe-analyticsv1.0.0
- adobe-cjav1.0.1
- adobe-for-developersv1.0.0
- aem-6-5-ltsv1.0.0
- aem-cloud-servicev1.4.4
- aem-edge-delivery-servicesv1.3.2
- aem-eds-content-opsv1.3.1
- aem-eds-personalizationv1.0.0
- aem-forms-edge-delivery-servicesv1.0.1
- aem-project-managementv1.0.1
- app-builderv1.0.0