If you’re moving Admin customisations off PaaS, the Admin UI SDK in ACCS is where they end up. On PaaS, a “small Admin page” meant a whole ritual. A menu.xml, an acl.xml, a routes.xml, an Admin controller, a layout file, a block or a ui_component XML file, and a system.xml if the merchant needed settings. I’ve written that stack more times than I can count.
On ACCS, none of that ships, because you can’t deploy custom PHP modules at all. I covered why in ACCS vs PaaS custom modules. The replacement is the Admin UI SDK: you build the screen as an App Builder app, and Commerce renders it inside the Admin.
This post is the practical version. What the SDK is, what it replaces, which extension points really exist today, how to enable it on ACCS, and a small menu page you can deploy. I built every claim from Adobe’s Admin UI SDK docs and App Management docs, as they read in November 2026. The code is illustrative and adapted from Adobe’s samples, so test it in a Stage workspace before you trust it.
What the Admin UI SDK in ACCS actually is
Adobe describes the SDK as the way an App Builder developer extends the Commerce Admin with custom menus and pages, work that used to live in a PHP module. It has two halves.
- The Commerce side: a PHP module called
CommerceBackendUix. Adobe ships and runs it, so you never touch it on ACCS. It’s what injects your menus, buttons and columns into the Admin. - Your side: a React app built with the UI Extensibility (
uix) tooling, deployed to App Builder. Commerce loads it in an iframe.
Authentication runs through Adobe IMS. The page your admin opens gets the signed-in user’s IMS token and org ID from the host, so your app can call Commerce or your own Runtime actions on their behalf.
So the mental model is simple. Commerce owns the frame. You own everything inside it.
V1 vs V2: commerce/backend-ui/1 or commerce/backend-ui/2?
This is the part most older tutorials get wrong now, so I’ll be upfront about it.
For a long time, an Admin UI SDK app was an App Builder extension on the commerce/backend-ui/1 extension point. You wrote an ExtensionRegistration component, a registration runtime action and an extension-manifest.json, then published the app through Adobe Exchange approval.
According to the release notes, Admin UI SDK 4.2.0 (July 28, 2026) added commerce/backend-ui/2, and it’s available on ACCS. V1 is now deprecated, kept for backward compatibility, and the V2 docs say it will be removed in a future release.
V2 sits on App Management. You declare everything in one app.commerce.config.ts file. There’s no ExtensionRegistration component and no hand-written registration action. A merchant then associates and installs the app from Apps > App Management in the Admin.
My advice: start new work on V2. I’ll still show the V1 shape later, because you’ll meet it in older repos and Marketplace apps.
PaaS vs ACCS: what replaces your old Admin code
Here’s how I map the usual PaaS pieces. Read the right-hand column as “closest equivalent”, not “drop-in replacement”.
| PaaS (PHP module) | ACCS with Admin UI SDK V2 | Notes |
|---|---|---|
etc/adminhtml/menu.xml | adminUi.menu | One menu item per app. It sits under Apps, or under a top-level menu via parentMenu. |
| Admin route, controller, layout, block or template | A React page in web-src/, opened in an iframe | No server-rendered PHP. Data comes from your Runtime actions or Commerce APIs. |
etc/acl.xml | aclProtected: true | Commerce generates an app-scoped ACL resource you can grant per role. |
Extra column in a ui_component listing | gridColumns plus a runtimeAction | Commerce POSTs the visible row IDs, and your action returns values. |
massaction in a listing XML | massActions, view or worker | view opens an iframe. worker calls an action with no UI. |
| Button on the order view page (layout or plugin) | order.viewButtons | Same view or worker split, with level and sortOrder. |
addSuccess() or addError() messages | notifications: { success, error } | Declared on the mass action or button itself. |
etc/adminhtml/system.xml | App Management business configuration | Not an Admin UI SDK feature. App Management renders config forms from a schema. See the hedge below. |
| Custom fee lines in order totals | A webhook, not the Admin UI SDK | The old customFees point was removed in 5.0.0. |
| Rewriting a native Admin form | nativeUi.replacedPages | Only order.create for now, and not yet on ACCS. See limitations. |
A quick hedge on system.xml. App Management’s overview says configuration forms are “rendered dynamically based on your schema”, with scopes. That’s the nearest thing to a config section. I haven’t compared it field by field with system.xml, so don’t assume every field type you used has a match.
Admin UI SDK extension points you can use today
I checked these against the V2 extension points page and the App Management Admin UI configuration. Availability on ACCS follows the release notes, which matter because SaaS sometimes gets features later than PaaS.
| Extension point | Config key | Entities | On ACCS? |
|---|---|---|---|
| Menu and page | adminUi.menu | App level | Yes (4.2.0+) |
| Grid columns | gridColumns | Order, product, customer | Yes (4.2.0+) |
| Grid columns | gridColumns | Invoice, credit memo, shipment | Added in 5.0.0. Adobe auto-updates SaaS, but I couldn’t confirm the exact ACCS rollout date. |
| Mass actions | massActions | Order, product, customer | Yes (4.2.0+) |
| View buttons | viewButtons | Order | Yes (4.2.0+) |
| View buttons | viewButtons | Invoice, credit memo | 5.1.0. PaaS now, SaaS “in the near future” |
| Grid columns | gridColumns | Newsletter subscribers | 5.1.0. PaaS now, SaaS “in the near future” |
| Native form replacement | nativeUi.replacedPages | order.create only | 5.1.0. PaaS now, SaaS “in the near future” |
Two things missing from that list are worth calling out. There’s no V2 equivalent of V1’s standalone bannerNotification point, because notifications moved onto the action or button. And invoices, credit memos and shipments get columns, not mass actions.
Setting up the Admin UI SDK in ACCS
1. Enable the SDK in the Admin
The installation page is clear on this: ACCS already includes the SDK and updates it for you. There’s no composer require. You only switch it on.
- Go to Stores > Settings > Configuration > Adobe Services > Admin UI SDK.
- Set Enable Admin UI SDK to Yes. It’s off by default.
- Leave Enable local testing on No. Adobe says local testing is PaaS-only, and on ACCS it must stay off.
- Optional but handy: under Database logging configuration, set Enable Logs to Yes. Logs then show up in System > Admin UI SDK > Admin UI SDK Logs.
Since you have no bin/magento on ACCS, that logs screen is your best friend later.
2. Give your admin role App Management access
Only roles with the App Management resource can associate apps. In System > User Roles, open the role, go to Role Resources, expand Admin UI SDK and tick App Management. This comes from the App Management troubleshooting page.
3. Prepare the App Builder project
If you followed my App Builder for ACCS first extension post, you already have most of this. Per the initialisation guide, add only the services you need:
- I/O Management API, for Runtime actions.
- Adobe Commerce as a Cloud Service, for ACCS instances.
- I/O Events and I/O Events for Adobe Commerce, only if the app also uses events.
Check your Node version too. Adobe’s build docs say the CLI needs Node.js 22 to 24, and the V2 menu sample asks for Node 24 or later. I’d just use 24.
Hands-on: a custom Admin page without PHP
Let’s build the classic first task: a menu item that opens a page. Mine is a small “Sync Monitor” page under Sales, the kind of screen I used to build with a controller and a template. It’s adapted from Adobe’s V2 custom-menu sample. Treat it as illustrative.
Scaffold the app
mkdir sync-monitor && cd sync-monitor
aio console org select
aio console project select
aio console workspace select # pick Stage first
aio app use
npx @adobe/aio-commerce-lib-app initThe init command creates app.commerce.config, installs @adobe/aio-commerce-lib-app and @adobe/aio-commerce-sdk, updates app.config.yaml and install.yaml, and adds a postinstall hook. Choose TypeScript if it asks. You’ll also want @adobe/aio-commerce-lib-admin-ui for the page hooks.
Declare the menu in app.commerce.config.ts
import { defineConfig } from "@adobe/aio-commerce-lib-app/config";
import { MENU_SALES } from "@adobe/aio-commerce-lib-admin-ui/menu";
export default defineConfig({
metadata: {
id: "syncmonitor",
displayName: "SB Sync Monitor",
version: "1.0.0",
description: "Shows the latest ERP sync status inside Commerce Admin.",
},
adminUi: {
menu: {
id: "SyncMonitor::dashboard",
label: "Sync Monitor",
description: "Review recent ERP sync runs.",
pageTitle: "ERP Sync Monitor",
parentMenu: MENU_SALES,
aclProtected: true,
},
},
});A few rules from the menu reference. The id allows letters, digits, /, : and _. description is required. parentMenu must be one of content, marketing, stores, system, catalog, customers, reports or sales, otherwise the registration is rejected. Commerce also creates a section named after your displayName, so the path here becomes Sales > SB Sync Monitor > Sync Monitor.
Check app.config.yaml and install.yaml
After init and a first build, these should declare both extension points. This is what Adobe’s sample uses:
# app.config.yaml
extensions:
commerce/backend-ui/2:
$include: src/commerce-backend-ui-2/ext.config.yaml
commerce/extensibility/1:
$include: src/commerce-extensibility-1/ext.config.yaml# install.yaml
extensions:
- extensionPointId: commerce/backend-ui/2
- extensionPointId: commerce/extensibility/1commerce/backend-ui/2 is the Admin UI. commerce/extensibility/1 is App Management, and it serves the generated app-config action that Commerce reads your registration from. Don’t hand-edit the generated hooks in the ext.config.yaml files.
Wire the page in app.tsx
// src/commerce-backend-ui-2/web-src/src/app.tsx
import { createExtensionApp } from "@adobe/aio-commerce-lib-admin-ui/web";
import "@react-spectrum/s2/page.css";
import config from "#app.commerce.config";
import { SyncMonitorPage } from "#web/pages/sync-monitor-page.tsx";
createExtensionApp({
menu: <SyncMonitorPage />,
metadata: { extensionId: config.metadata.id },
});Build the page
// src/commerce-backend-ui-2/web-src/src/pages/sync-monitor-page.tsx
import { useEffect, useState } from "react";
import { useIms } from "@adobe/aio-commerce-lib-admin-ui/web";
// Illustrative: replace with your deployed web action URL
const STATUS_URL = "https://<namespace>.adobeioruntime.net/api/v1/web/sync-monitor/status";
export function SyncMonitorPage() {
const { data, error } = useIms();
const [runs, setRuns] = useState<Array<{ id: string; status: string }>>([]);
useEffect(() => {
if (!data) return;
fetch(STATUS_URL, {
headers: {
Authorization: `Bearer ${data.imsToken}`,
"x-gw-ims-org-id": data.imsOrgId,
},
})
.then((r) => r.json())
.then((body) => setRuns(body.runs ?? []))
.catch(() => setRuns([]));
}, [data]);
if (error) return <p>Open this page from the Commerce Admin.</p>;
return (
<main>
<h1>Latest ERP sync runs</h1>
<ul>
{runs.map((run) => (
<li key={run.id}>{run.id}: {run.status}</li>
))}
</ul>
</main>
);
}useIms() is the documented way to get the admin’s imsToken and imsOrgId. It returns an error when the page runs standalone, because there’s no host to supply credentials. The status action, its URL and the header pattern are my placeholders. Secure that action with require-adobe-auth like any other App Builder web action.
Optional: add an order grid column
This is where I stopped missing ui_component XML. Add this under adminUi:
order: {
gridColumns: {
label: "ERP sync data",
description: "Adds ERP sync status to the order grid",
runtimeAction: "sync-monitor/order-grid-data",
columns: [
{ id: "erp_status", label: "ERP status", type: "string", align: "left" },
],
},
},Then write the action. Commerce sends the visible order IDs, and you return values keyed by those IDs and column IDs:
// actions/order-grid-data/index.js (illustrative)
import { okGridResponse, parseGridRequest } from "@adobe/aio-commerce-lib-admin-ui/grid-columns";
export async function main(params) {
const { ids } = parseGridRequest(params);
const statuses = await lookupErpStatus(ids); // placeholder: your ERP or cache
const data = {};
for (const id of ids) {
if (statuses[id]) data[id] = { erp_status: statuses[id] };
}
return okGridResponse(data, { erp_status: "unknown" });
}Declare that action in your runtime manifest under a sync-monitor package so the package/action path resolves. The generator then adds the matching workerProcess entry for you.
The second argument to okGridResponse is the default for missing rows. Watch the key type: Adobe notes product grid requests use SKUs, while customer grids use customer IDs.
Build, deploy and install the app
The build and deploy guide uses these two commands. The pre-app-build hook regenerates the files under .generated each time.
aio app build --force-build
aio app deploy --force-deploy --no-buildDeploying isn’t the same as installing. The merchant side happens in the Admin, as described in Experience League’s Manage your app guide:
- Go to Apps > App Management and click Associate App.
- Pick the Developer Console Project and Workspace, then click Associate.
- Open the install dialog, review the steps and click Install. Keep the page open until it says Successfully Installed.
- If you used
aclProtected, grant the new resource to the right roles under System > User Roles. - Reload the Admin and look for your menu.
For later changes, deploy again. App Management then flags an upgrade, which an admin starts manually by default. Adobe notes that a deploy can update Runtime action code before that upgrade runs, so be careful with breaking changes.
I couldn’t find V2 docs that require Adobe Exchange publishing approval before App Management association, the way V1’s publish guide does. Experience League lists a “deployed app” as the prerequisite. If your org has extra approval rules, follow those.
Local testing on ACCS: be realistic
This is the biggest workflow change for PaaS developers. On PaaS with V1, you could point Commerce at a local registry server and work against localhost. Per the configuration page, that feature is PaaS-only and V1-only.
App Management also doesn’t support local Commerce instances. So my loop on ACCS looks like this:
- Write the UI and actions locally, and unit test the actions with mocked requests.
- Run
aio app devoraio app runfor quick UI checks. Remember that IMS hooks such asuseIms()return errors outside the Admin, so stub them. - Deploy to the Stage workspace and associate it with a non-production ACCS environment for the real test.
- Only then deploy to Production and associate that workspace with the live instance.
I haven’t confirmed a documented way to run a V2 page inside the ACCS Admin from localhost. If one exists, I’ll update this section.
If you inherit a V1 app
You’ll still see V1 code, so here’s the shape from the V1 registration guide. It targets commerce/backend-ui/1:
# app.config.yaml (V1, deprecated)
extensions:
commerce/backend-ui/1:
$include: src/commerce-backend-ui-1/ext.config.yaml// ExtensionRegistration.jsx (V1, deprecated)
import { register } from "@adobe/uix-guest";
import { useEffect } from "react";
import { extensionId } from "./Constants";
export default function ExtensionRegistration() {
useEffect(() => {
(async () => {
await register({ id: extensionId, methods: {} });
})();
}, []);
return null;
}V1 also needs an extension-manifest.json whose id matches extensionId, and a runtime action that must live in a package named admin-ui-sdk with the action name registration. That action returns the menus, pages and buttons.
To move off it, read Migration from V1. The main changes: id replaces actionId and buttonId, type: 'view' | 'worker' replaces displayIframe, grid columns call a Runtime action instead of API Mesh, and the menu becomes a single object. Adobe also mentions a commerce-app-migrate skill that scaffolds the V2 version. I haven’t tried it yet.
That API Mesh point is interesting. If you built V1 grid columns on a mesh, see my API Mesh in ACCS post for where Mesh still fits.
Limitations to plan for
- It’s an iframe. Your page doesn’t share the Admin’s JavaScript, styles or session. Iframe sandbox extras are limited to
allow-downloads,allow-modalsandallow-popups. - One menu item per app. V2 dropped V1’s
menuItemsarray. Need two menus? Build two apps, or use routing inside one page. - Fixed parent menus. Only the eight top-level menus listed above are allowed.
- No arbitrary Admin rewrites. You get the listed extension points, not layout XML. Native form replacement covers only
order.create, and it hasn’t reached ACCS at the time of writing. - Feature lag on SaaS. 5.1.0 features shipped to PaaS first. Check the release notes before you promise a feature.
- Network reachability. App Management must reach your Commerce instance. If you use an IP allowlist, add the Runtime egress IPs from
aio runtime ip-list get. HTTP Basic Auth in front of Commerce isn’t supported. - No custom fees here. Totals changes are a webhook job now. My ACCS webhooks vs events post covers that model.
Troubleshooting
The menu doesn’t appear
Check, in order: the SDK is enabled, the app shows as Installed in App Management, and your role has the app’s ACL resource if you set aclProtected. Then check Admin UI SDK Logs if you enabled database logging.
“The selected application is not compatible with Adobe Commerce”
Adobe says this is about the App Management flow, not Commerce compatibility. The deployed app has to expose the manifest and App Management actions generated from app.commerce.config. A plain App Builder project isn’t enough, so run init, build and deploy.
The app isn’t listed under App Management
Run aio app get-url and look for the app-management actions. If they’re missing, redeploy with aio app deploy --force-build --force-deploy. Also confirm you deployed to the same IMS org the instance uses.
The page loads but shows an IMS error
You’re probably opening the app URL directly. useIms() only works inside a host such as the Commerce Admin.
Grid column cells are empty
Your response keys must match the column id and the row IDs Commerce sent. Product grids send SKUs. Without a default value, a missing cell stays empty.
Extensions time out
The troubleshooting page notes a 10-second timeout when Commerce fetches extensions from the App Registry. Refresh once, then check network and Adobe status before escalating to support.
Checklist before you call it done
- ☐ Each PaaS Admin feature mapped to menu, page, column, mass action, button or “not possible”.
- ☐ Admin UI SDK enabled, and local testing left on No.
- ☐ Database logging switched on for the test period.
- ☐ App Management permission granted to the right admin role.
- ☐ App built on
commerce/backend-ui/2, not the deprecated V1. - ☐ Every protected item uses
aclProtected, and roles are updated. - ☐ Runtime actions secured with
require-adobe-auth. - ☐ Tested on Stage against a non-production ACCS environment.
- ☐ Upgrade path tested once: deploy, then upgrade from App Management.
- ☐ Feature availability on ACCS checked in the release notes.
My take
I didn’t expect to like this. Losing ui_component XML felt like losing a superpower. In practice, a React page plus a few lines of config is quicker than the six-file PHP stack, and Adobe upgrades can’t break it the way a template override could.
The trade-off is control. You get the extension points Adobe ships and nothing else, and SaaS can trail PaaS by a release. So start every project by checking the extension points list, not by sketching the dream screen.
If you’re new to the series, start with Introduction to ACCS. And if your Admin looks different from what I described, tell me in the comments. These docs are moving fast.
Next in the ACCS series
This is part 10 of 11 in my ACCS series. Previous: API Mesh in ACCS: connecting ERP, PIM and CRM. Next: CI/CD and testing for App Builder apps on ACCS. The full series list is in the introduction.




