Migration from V1

data-variant=tip

data-slots=text

If you are porting an extension from the deprecated V1 extension points, note the following structural changes:

• Notifications are inline, not a separate extension point. V1 had a standalone bannerNotification extension point that referenced mass actions and order view buttons by ID. In V2, the success and error messages are declared directly on the mass action or view button that uses them, as notifications: { success, error }. This applies to mass actions and view buttons on orders, customers, and products. See Inline notifications.
• id replaces actionId, buttonId, and title. Every registration (menu, mass action, view button) now identifies itself with a single id field instead of extension-point-specific ID field names.
• type replaces displayIframe. Mass actions and order view buttons declare type: 'view' or type: 'worker' instead of a displayIframe boolean. See View vs. worker actions.
• sandboxPermissions replaces sandbox. Sandbox restrictions are now an array of values (for example, ['allow-modals', 'allow-popups']) instead of a single space-separated string.
• Grid columns call a runtime action instead of API Mesh. V1 grid columns fetched data through an API Mesh instance referenced by data.meshId. V2 grid columns declare a runtimeAction, and Commerce calls it directly. See Grid columns.
• The menu extension point is a single object, not an array. V1 registered an array of menuItems (allowing multiple items and a shared section item). V2 declares one menu object per app. The section is generated automatically from the app's display name. sortOrder is removed, and description is a new required field.
• Custom fees are not a V2 Admin UI SDK extension point. In V2, order total modifications are implemented as a webhook on plugin.magento.out_of_process_totals_collector.api.get_total_modifications.custom_fees. See Checkout Totals Collector.
• A no-framework (vanilla JS) menu variant is not supported. App Management always scaffolds a web-src App Builder frontend for extensions that render UI.

View vs. worker actions

Mass actions and order view buttons declare a type of either view or worker:

• view actions open the path you specify inside an iframe backed by your App Builder frontend. This is the equivalent of a V1 action with displayIframe: true.
• worker actions call the runtimeAction you specify directly, with no UI shown. This is the equivalent of a V1 action with displayIframe: false.

For worker actions, runtimeAction identifies the action using the <package>/<action> format from your app.config.yaml runtime manifest (for example, mass-actions/massAction). Commerce resolves this to the full deployed action URL at installation time.

Inline notifications

Instead of registering a separate bannerNotification extension point, declare a notifications object directly on a mass action or view button:

{
  id: 'order-mass-action-with-redirect',
  label: 'Mass Action With Redirect',
  type: 'view',
  path: '#/mass-action-with-redirect',
  notifications: {
    success: 'Order custom success message',
    error: 'Order custom error message',
  },
}

If notifications is omitted, Commerce displays a default success or error banner.

ACL protection

Any menu item, mass action, view button, or grid column can be gated behind a dedicated Commerce ACL resource by setting aclProtected: true:

{
  id: 'flag-orders',
  label: 'Flag for review',
  type: 'view',
  path: '#/flag-orders',
  aclProtected: true,
}

When aclProtected is true, Commerce generates a nested ACL resource scoped to your app (app → entity → extension-point type → item) so administrators can grant or restrict access to individual menu items, mass actions, view buttons, or grid columns per admin role. When aclProtected is omitted or false, the item uses the shared Magento_CommerceBackendUix::adminuisdk_extensions resource used by all unprotected V2 extension points.

Grid columns call your runtime action directly

Instead of an API Mesh source, a V2 gridColumns registration declares a runtimeAction. When a merchant opens the grid, Commerce sends a POST request to your action with the visible row IDs, and renders the values your action returns:

{ "requestId": "...", "gridType": "order", "ids": ["000000001", "000000002"] }

See Order grid columns, Product grid columns, and Customer grid columns for the full column schema and a sample runtime action.

customFees support is deprecated

The V2 Admin UI SDK does not support the customFees extension point. In V1, this extension point allowed apps to add custom fees to the order totals summary. In V2, order total modifications are implemented as a webhook on plugin.magento.out_of_process_totals_collector.api.get_total_modifications.custom_fees. See Checkout Totals Collector for details.