DocumentationCommerceAdobe Commerce as a Cloud Service

Ratings extension tutorial

Last update: Tue Feb 24 2026 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Intermediate
  • Developer

This tutorial guides you through building a product ratings extension for Adobe Commerce as a Cloud Service using Adobe App Builder and AI-assisted development tools.

Before you begin, complete the prerequisites.

Verify prerequisites

Verify that the following prerequisites are installed:

# Check Node.js version (should be 22.x.x)
node --version

# Check npm version (should be 9.0.0 or higher)
npm --version

# Check Git installation
git --version

# Check Bash shell installation
bash --version

If any of the preceding commands do not return the expected results, refer to the prerequisites for guidance.

Extension development

This section guides you through developing a ratings extension for Adobe Commerce as a Cloud Service using AI-assisted development tools.

  1. Navigate to Cursor > Settings > Cursor Settings > Tools & MCP and verify that the commerce-extensibility toolset is enabled without errors. If you see errors, toggle the toolset off and on.

    Cursor IDE settings showing MCP commerce-extensibility toolset enabled {width="600" modal="regular"}

    note note
    NOTE
    When working with AI-assisted development tools, expect natural variations in the code and responses generated by the agent.
    If you encounter any issues with your code, you can always ask the agent to help you debug it.

  2. If you have any documentation added to Cursor’s context, disable it:

    • Navigate to Cursor > Settings > Cursor Settings > Indexing & Docs and delete any documentation listed.

    Cursor indexing and docs settings with documentation list empty {width="600" modal="regular"}

  3. Generate code for a product ratings extension:

    • From the Cursor chat window, select Agent mode.
    • Enter the following prompt:
    code language-shell-session 
    Implement an Adobe Commerce as a Cloud Service extension to handle Product Ratings.

Implement a REST API to handle GET ratings requests.

GET requests will have to support the following query parameters:

sku -> product SKU
    note note
    NOTE
    If the agent requests to search the documentation, allow it.

  4. Answer the agent’s questions precisely to help it generate the best code.

    Cursor chat window in Agent mode with extension prompt entered {width="600" modal="regular"} AI agent asking clarifying questions about extension requirements {width="600" modal="regular"}

  5. Use the following example text to answer the agent’s questions to set up randomized ratings data:

    code language-shell-session 
    Yes, this headless extension is for Adobe Commerce as a Cloud Service storefront,
but we do not need any authentication for the GET API because guest users should be able to use it on the storefront.

This extension is called directly from the storefront, no async invocation, such as events or webhooks, is required.

Start with just the GET API for now, we will implement other CRUD operations at a later time.

We do not need a DB or storage mechanism right now, just return random ratings data between 1 and 5 and a ratings count between 1 and 1000.

The API should only return the average rating for the product and the total number of ratings.
We do not need to add tests right now.

    The agent creates a requirements.md file that serves as the source of truth for the implementation.

    Requirements.md file created by AI agent with implementation details {width="600" modal="regular"}

  6. Review the requirements.md file and verify the plan.

    If everything looks correct, instruct the agent to move to Phase 2 - Architecture Planning.

  7. Review the architecture plan.

  8. Instruct the agent to proceed with code generation.

    The agent generates the necessary code and provides a detailed summary with your next steps.

    AI agent Phase 2 architecture plan for ratings API {width="600" modal="regular"} Summary of generated code files and structure {width="600" modal="regular"} AI agent providing next steps for testing and deployment {width="600" modal="regular"}

Local testing

  1. Ask the agent to help you test the code locally.

    code language-shell-session 
    Test the ratings API locally on a dev server using cURL.

  2. Follow the agent’s instructions and confirm that the API is working locally.

    AI agent instructions for local API testing {width="600" modal="regular"} Terminal showing successful local API test results with cURL {width="600" modal="regular"}

Deploy the extension

  1. After verifying the generated code, deploy the extension using the following prompt:

    code language-shell-session 
    Deploy the ratings API.

    The agent performs a pre-deployment readiness assessment before deploying.

    AI agent pre-deployment readiness assessment checklist {width="600" modal="regular"}

  2. When you are confident with the assessment results, instruct the agent to proceed with deployment.

    The agent uses the MCP toolkit to verify, build, and deploy automatically.

    MCP toolkit verification build and deployment process {width="600" modal="regular"}

Post deployment

You can test the API before integrating it into the storefront. The agent should provide the location of the new action and a testing strategy.

AI agent testing strategy with deployed action URL and test commands {width="600" modal="regular"}

You can also test the API manually using cURL in a terminal:

curl -s "https://<your-site>.adobeioruntime.net/api/v1/web/ratings/ratings?sku=TEST-SKU-123"

Terminal showing successful cURL test of deployed ratings API {width="600" modal="regular"}

Integrate with Edge Delivery Services

To integrate the ratings API with an Adobe Commerce storefront powered by Edge Delivery Services, ask the agent to create a service contract with requirements for the ratings API:

Create a service contract for the ratings api that I can pass on to the storefront agent. Name it RATINGS_API_CONTRACT.md

AI agent creating service contract file for storefront integration {width="600" modal="regular"}

Ratings API contract markdown file with endpoint and response details {width="600" modal="regular"}

Next steps

Now that you have the ratings API contract, you can begin building the storefront (frontend) portion of the ratings extension.

recommendation-more-help
5ecfe1a6-f74c-4745-a54a-99b24da024bb