Documentation Commerce Adobe Commerce as a Cloud Service

Tutorial prerequisites

Last update: Thu Mar 19 2026 00:00:00 GMT+0000 (Coordinated Universal Time)

Topics:
App Builder
Cloud

CREATED FOR:

Intermediate
Developer

This page lists the prerequisites and setup steps for Adobe Commerce as a Cloud Service tutorials, such as the ratings extension tutorial and the shipping method extension tutorial.

General prerequisites

The following tools are required for both extension and storefront development in this tutorial.

Node.js (version 22.x.x) and npm (9.0.0 or higher): Verify your installation using the following command:

code language-bash
`node --version npm --version`

Install Git - Verify your installation:

code language-bash
`git --version`

Bash shell
- macOS/Linux: No installation required
- Windows: Use Git Bash or Windows Subsystem for Linux (WSL)
Download an AI-assisted IDE, such as Cursor (recommended). Other IDEs, such as Claude Code, Gemini CLI, or Copilot are also supported, but could require modifications to the prompts and other steps in the tutorial.

Adobe Commerce as a Cloud Service prerequisites

Install the Adobe I/O CLI

code language-bash
`npm install -g @adobe/aio-cli`

Install the Adobe I/O CLI Commerce, Adobe I/O CLI Runtime, and App Builder CLI plugins:

code language-bash
`aio plugins:install https://github.com/adobe-commerce/aio-cli-plugin-commerce @adobe/aio-cli-plugin-app-dev @adobe/aio-cli-plugin-runtime`

After installing the Adobe I/O CLI and the required plugins, set up your extensibility workspace. Adobe recommends using the automated setup for the fastest experience.

Automated setup (Recommended) — Run a single command to configure your workspace automatically.
Manual setup — Follow step-by-step instructions to configure each component individually.

Automated setup (Recommended) automated-setup

TIP

If you encounter issues with the automated setup, follow the manual setup steps below.

The app-setup command automates the workspace setup process, including creating an Adobe Developer Console project, adding the required APIs, configuring the Adobe I/O CLI, cloning the starter kit, connecting your local workspace, and installing the extensibility AI tools.

The app-setup command guides you through the following steps:

Selecting or creating an Adobe Developer Console project with the required APIs
Configuring the Adobe I/O CLI with your organization, project, and workspace
Cloning the appropriate starter kit and setting up the project
Configuring the environment and connecting the local workspace to the remote workspace
Installing the Commerce extensibility tools and coding agent skills

Run the following command and follow the interactive prompts:

aio commerce extensibility app-setup

After the command completes, navigate to your project directory and restart your coding agent to load the new MCP tools and skills. If your tutorial requires a storefront, rerun the command and select the AEM Boilerplate Commerce starter kit.

The following example installation shows the interactive prompts and output for the checkout starter kit.

Example installation (checkout starter kit)

code language-shell-session

code language-shell-session
aio commerce extensibility app-setup 🚀 Adobe Commerce Extensibility App Setup ✔ Logged in 📁 Working directory: /Users/username/projects/my-commerce-project ✔ Which starter kit would you like to use? Checkout Starter Kit ✔ Enter a name for your project directory: my-extension ✔ Which coding agent would you like to install the skills for? Cursor 📦 Cloning Checkout Starter Kit... ✔ Repository cloned Using npm (package-lock.json found) ✔ Dependencies installed 📋 Current Adobe I/O Console configuration: Org: My Organization (1234567) Project: My Commerce Project (1234567890123456789) Workspace: Stage (9876543210987654321) ✔ Do you want to continue with this configuration? (Answer "No" to select a different org/project/workspace) No 🔧 Selecting Adobe I/O Console org, project, and workspace... ? Select Org: My Organization Org selected My Organization You are currently in: 1. Org: My Organization 2. Project: <no project selected> 3. Workspace: <no workspace selected> ? Select Project: My Commerce Project Project selected : My Commerce Project You are currently in: 1. Org: My Organization 2. Project: My Commerce Project 3. Workspace: <no workspace selected> ? Select Workspace: Stage Workspace selected Stage You are currently in: 1. Org: My Organization 2. Project: My Commerce Project 3. Workspace: Stage ✅ Console configured: Org: My Organization Project: My Commerce Project Workspace: Stage 🔐 Configuring workspace credentials and services... ✔ Workspace configuration loaded ✔ OAuth server-to-server credentials already configured ✔ All required services available in organization ✔ Subscribed to: Adobe Commerce as a Cloud Service 📋 Configuring Checkout Starter Kit... Creating .env from env.dist... ✔ Select tenant (type to search) My Commerce Instance: https://<region>.api.commerce.adobe.com/<tenant-id>/graphql ✔ Commerce instance configured ✔ Enter the event prefix for your workspace: my-prefix ✔ Workspace IDs configured ✔ OAuth credentials configured ✔ Checkout Starter Kit configured 🔧 Installing Commerce Extensibility tools and agent skills... ✔ Commerce Extensibility tools installed 🎉 App setup complete! 📁 Project directory: /Users/username/projects/my-commerce-project/my-extension Next steps: 1. cd into your project directory 2. Restart your coding agent to load the Commerce Extensibility tools and skills

aio commerce extensibility app-setup

🚀 Adobe Commerce Extensibility App Setup

✔ Logged in
📁 Working directory: /Users/username/projects/my-commerce-project

✔ Which starter kit would you like to use? Checkout Starter Kit
✔ Enter a name for your project directory: my-extension
✔ Which coding agent would you like to install the skills for? Cursor

📦 Cloning Checkout Starter Kit...
   ✔ Repository cloned
   Using npm (package-lock.json found)
   ✔ Dependencies installed

📋 Current Adobe I/O Console configuration:
   Org: My Organization (1234567)
   Project: My Commerce Project (1234567890123456789)
   Workspace: Stage (9876543210987654321)
✔ Do you want to continue with this configuration? (Answer "No" to select a different org/project/workspace)
No

🔧 Selecting Adobe I/O Console org, project, and workspace...

? Select Org: My Organization
Org selected My Organization
You are currently in:
1. Org: My Organization
2. Project: <no project selected>
3. Workspace: <no workspace selected>

? Select Project: My Commerce Project
Project selected : My Commerce Project
You are currently in:
1. Org: My Organization
2. Project: My Commerce Project
3. Workspace: <no workspace selected>

? Select Workspace: Stage
Workspace selected Stage
You are currently in:
1. Org: My Organization
2. Project: My Commerce Project
3. Workspace: Stage

✅ Console configured:
   Org: My Organization
   Project: My Commerce Project
   Workspace: Stage

🔐 Configuring workspace credentials and services...
   ✔ Workspace configuration loaded
   ✔ OAuth server-to-server credentials already configured
   ✔ All required services available in organization
   ✔ Subscribed to: Adobe Commerce as a Cloud Service

📋 Configuring Checkout Starter Kit...
   Creating .env from env.dist...
✔ Select tenant (type to search) My Commerce Instance:
https://<region>.api.commerce.adobe.com/<tenant-id>/graphql
   ✔ Commerce instance configured
✔ Enter the event prefix for your workspace: my-prefix
   ✔ Workspace IDs configured
   ✔ OAuth credentials configured
   ✔ Checkout Starter Kit configured

🔧 Installing Commerce Extensibility tools and agent skills...
   ✔ Commerce Extensibility tools installed

🎉 App setup complete!

📁 Project directory: /Users/username/projects/my-commerce-project/my-extension

Next steps:
   1. cd into your project directory
   2. Restart your coding agent to load the Commerce Extensibility tools and skills

Manual setup manual-setup

The following sections describe how to manually set up each component of your extensibility workspace. Follow these steps if you prefer manual configuration, or if you encounter issues with the automated setup.

Adobe Developer Console prerequisites

Set up a project in the Adobe Developer Console with the required APIs and credentials.

Navigate to the Adobe Developer Console.
Log in using your email and password.

Create a new project

Create an App Builder project in the Adobe Developer Console to host your extension.

Navigate to Adobe Developer Console.
Click Create project from a template.
Select the App Builder template.
Enter a Project Title and App Name.
Ensure the Include Runtime checkbox is marked.

{width="600" modal="regular"}
Click Save.

Add APIs to the workspace

Add the required APIs to your Stage workspace for event management and Commerce integration.

Click the Stage workspace and then repeat the following steps for each API.

{width="600" modal="regular"}
Click Add Service and select API.
Select one of the following APIs. Repeat this process for each API listed below:
- Adobe Services filter:
  - I/O Management API
  - I/O Events API
- Experience Cloud filter:
  - Adobe I/O Events for Adobe Commerce API
Click Next.
Click Save configured API.
Repeat the previous steps until you add all APIs to the workspace.

{width="600" modal="regular"}

Configure the Adobe I/O CLI

Connect the Adobe I/O CLI to your organization, project, and workspace.

Clear any existing configuration:

code language-bash
`aio config clear`

code language-bash
`aio auth login -f`

Select your organization, project, and workspace using each of the following commands:

code language-bash
`aio console org select`

code language-bash
`aio console project select`

code language-bash
`aio console workspace select`

Terminal showing Adobe I/O CLI organization project and workspace selection {width="600" modal="regular"}

Clone the starter kits

Clone one of the following Commerce starter kit repositories for the extension you are building and prepare your project:

Integration starter kit:

git clone https://github.com/adobe/commerce-integration-starter-kit.git extension
cd extension

Checkout starter kit:

git clone https://github.com/adobe/commerce-checkout-starter-kit.git extension
cd extension

Integration starter kit

Create an .env file

Create your environment configuration file:

code language-bash
`cp env.dist .env`

Open the .env file in a text editor and add the following OAuth credentials:

code language-bash
`OAUTH_CLIENT_ID= OAUTH_CLIENT_SECRET= OAUTH_TECHNICAL_ACCOUNT_ID= OAUTH_TECHNICAL_ACCOUNT_EMAIL= OAUTH_ORG_ID=`

Copy these values from the Credential details page in Developer Console by clicking the OAuth Server-to-Server tab on your workspace.

OAuth Server-to-Server credentials page in Adobe Developer Console {width="600" modal="regular"}

Add the Commerce configuration

Add the following Commerce instance details to your .env file:

code language-bash
`COMMERCE_BASE_URL= COMMERCE_GRAPHQL_ENDPOINT=`

To find these values:

Navigate to Commerce Cloud Service instances.
Click the information icon next to your instance.
Copy the REST endpoint as COMMERCE_BASE_URL.
Copy the GraphQL endpoint as COMMERCE_GRAPHQL_ENDPOINT.

Set the event prefix

Set a temporary value for the event prefix:

code language-bash
`EVENT_PREFIX=test`

Download the workspace configuration

Run the following command to download the workspace configuration file:

code language-bash
`aio console workspace download workspace.json`

Copy the workspace configuration file to the scripts directory:

code language-bash
`cp workspace.json scripts/`

Connect the local workspace to the remote workspace

Link your local project to the remote workspace:

code language-bash
`aio app use workspace.json -m`

Terminal showing successful workspace connection with aio app use command {width="600" modal="regular"}

Checkout starter kit

Connect local workspace to remote workspace

Link your local project to the remote workspace. From the project root (the extension folder), run:

code language-bash
`aio app use --merge`

When prompted, choose the option that uses the organization, project, and workspace you selected when configuring the Adobe I/O CLI. This writes the workspace configuration into your app so that deploy and local development use that workspace.

Terminal showing successful workspace connection with aio app use command {width="600" modal="regular"}

Install the extensibility AI tools

This process creates the MCP configuration (.<agent>/mcp.json), the skills directory (.<agent>/skills/), and adds AGENTS.md to the project root. You will be prompted to choose a starter kit, coding agent, and package manager.

Set up the AI-assisted development tools in the extension folder using the following commands:

code language-bash
`cd extension`

code language-bash
`aio commerce extensibility tools-setup`

Terminal showing AI extensibility tools setup command output {width="600" modal="regular"}

After the setup completes, restart your coding agent to allow it to load the new MCP tools and skills. The Commerce App Builder tools are now available in your environment.

note note
NOTE
If you see a warning that no skills were found for the starter kit, something went wrong—often because the setup was run in a folder other than where the starter kit was cloned. Run `aio commerce extensibility tools-setup` from the `extension` folder (the starter kit project root) and select the appropriate starter kit when prompted.

Terminal showing AI extensibility tools setup with checkout starter kit selected {width="600" modal="regular"}

Storefront manual setup

This section describes how to manually configure your storefront for the Ratings extension tutorial and other storefront tutorials.

To automatically configure your storefront, run the app-setup command described in the Automated setup section and select the AEM Boilerplate Commerce starter kit.

Prerequisites

The following items are required to complete the storefront section of the Ratings extension tutorial and display product ratings in your store.

Google Chrome - Required for testing the storefront
A storefront project connected to your Commerce instance. If you do not have a storefront project, follow the steps in Create a storefront, including the Link repo to commerce data section.

Clone the storefront repository

Open your terminal and clone the repository:

git clone https://github.com/hlxsites/aem-boilerplate-commerce.git storefront
cd storefront

Install the dependencies

Install the project dependencies:

npm install

Install the storefront AI tools

Set up the AI-assisted development tools in the storefront folder.

Run the following command from the root of your boilerplate project. The command installs the @adobe-commerce/commerce-extensibility-tools package as a dev dependency, copies the skill files into your agent’s skills directory, and configures MCP (Model Context Protocol) so your agent can access Commerce documentation search tools.

aio commerce extensibility tools-setup

The command walks you through two prompts:

Select a starter kit — Choose AEM Boilerplate Commerce.
Select your coding agent — Choose your agent from the list of supported agents.

recommendation-more-help

5ecfe1a6-f74c-4745-a54a-99b24da024bb