App Builder Extension Compatibility

When developing and configuring App Builder extensions, it is important to ensure that they work seamlessly with both SaaS and PaaS versions of Adobe Commerce. The following guide describes how to ensure that extensions are fully compatible, deployable, and functional across both environments.

A key difference between SaaS and PaaS is how modules are installed on a Commerce instance. PaaS modules require installation, while SaaS modules are pre-installed.

For a better understanding of the differences between SaaS and PaaS, refer to the Feature Comparison.

IMS authentication

You should use IMS authentication to connect to Commerce.

PaaS Only IMS is necessary to utilize the Admin UI SDK. Adobe encourages adopting IMS authentication to ease migration to SaaS.
SaaS Only IMS authentication is used and Commerce integration authentication is not available.

For more information on enabling IMS authentication for your actions, see IMS Authentication.

API integration

Verify that your Commerce APIs are compatible with both environments by checking the following specifications.

GraphQL API:

PaaS Only For PaaS, there are separate core and catalog services GraphQL endpoints.
SaaS Only For SaaS, a single GraphQL URL is used, see the GraphQL API specification.

REST API:

PaaS Only PaaS REST API specification - The I/O Management API is required to connect a PaaS instance with your app builder application.
SaaS Only SaaS REST API specification - The Adobe Commerce as a Cloud Service API is required to connect a SaaS instance with your app builder application.

For more information on REST API access, refer to the Developer Console configuration in the integration starter kit, or the CLI configuration in the checkout starter kit.

Adapt REST endpoint for older starter kit versions:

For older versions of the starter kit, check if your code is adapted as follows:

To support both PaaS and SaaS, modify the COMMERCE_BASE_URL environment variable according to the Commerce integration guide.
Ensure that your adobe-commerce HTTP client removes the rest/all prefix for compatibility with both deployment flavors. For example:
```
- commerceGot(`rest/all/V1/oope_payment_method/`, {
+ commerceGot(`V1/oope_payment_method/`, {
```
Ensure that store view codes are no longer included in URLs. Instead, you must specify store views in the Store header of the request.

data-variant=info

data-slots=text

Refer to URL structure for more information.

Commerce webhook

PaaS Only Webhooks are created with XML files.
SaaS Only SaaS supports a predefined list of webhooks that you can configure in the Admin interface or create through REST endpoints.

Commerce eventing

PaaS Only You can register events through XML files or REST endpoints. However, for plugin-type events, you may need to redeploy to generate plugins.
SaaS Only SaaS supports a predefined list of events. You can manage events through the Admin interface or REST endpoints.

Admin UI SDK

PaaS Only Use the Admin UI SDK version 3.0 or higher to enable IMS authentication tokens from the shared context. Refer to troubleshooting if you encounter version restrictions:
```
"magento/commerce-backend-sdk": "3.0.0 as 2.0.0"
```
SaaS Only The Admin UI SDK and IMS modules are already configured. The Admin interface works the same as it does in PaaS.

To enable Adobe authentication for actions called by the SPA, you can obtain IMS tokens that work in both PaaS and SaaS by using the following:

if (props.ims?.token) {
    // When running inside Experience Cloud Shell, IMS token and orgId can be accessed via props.ims.
    setImsToken(props.ims.token);
    setImsOrgId(props.ims.org);
} else {
    // Commerce PaaS & SaaS retrieves IMS token via sharedContext from Admin UI SDK v3.0+
    // See https://developer.adobe.com/commerce/extensibility/admin-ui-sdk/extension-points/#shared-contexts
    const guestConnection = await attach({ id: extensionId });
    const context = guestConnection?.sharedContext;
    setImsToken(context?.get('imsToken'));
    setImsOrgId(context?.get('imsOrgId'));
}

For more information, see the full example.

Out-of-process extensibility modules

PaaS Only Requires composer installation.
SaaS Only Modules are pre-installed.
APIs function the same way in both environments:

Storefront integration and testing

PaaS Only EDS Storefronts require additional configuration, such as the Catalog and Storefront Compatibility Package. PaaS also provides the Luma Storefront, which is not available in SaaS.
SaaS Only You can use the EDS Storefront to connect to your Commerce instance without installing any modules. SaaS environments do not have access to the Luma Storefront.