AI Commerce storefronts support a merchant-specific, customizable REST API that partners can develop around the merchant's needs. The same serverless storefront function that serves the online-store UI also provides a REST API under the /rest/* path. This article is an in-depth guide: we explain the architecture of the model, why it is useful, how a partner adds their own service, and everything you can build with it.

1. Background: Composable Commerce and why it matters

In the Composable Commerce way of thinking, each area (such as product management, customer management, order handling, search, etc.) can be implemented as separate building blocks, i.e. micro services. These micro services communicate with each other through APIs. Instead of a traditional monolithic architecture, the Composable Commerce model offers:

• Flexibility: New features can be created faster when each part can be developed and tested independently.
• Extensibility: You can add third-party services (e.g. new payment solutions, search or ERP integrations) more easily, without massive changes to the core system.
• Faster product development: Partners can develop and release their own extensions independently, while AI Commerce manages security and infrastructure.

2. The core of the solution: a customizable /rest/* API in the storefront

Each merchant has their own storefront function (an AWS Lambda) that renders the online store. The same function provides a REST API under the /rest/* path, which the partner customizes. The partner does not need to set up a separate service, their own AWS account, or their own deployment keys — the extension lives in the same storefront project.

2.1 What this means for partners

One function, two roles

• The same storefront Lambda serves both the online-store UI and the /rest/* API. No separate micro service or dedicated API Gateway is needed.

The partner only adds service files

• The partner writes their own logic as individual JavaScript files in the storefront project's src/rest/services/ folder. The file path maps to the URL path, so src/rest/services/orders.js corresponds to the route /rest/orders.

The core framework is maintained by AI Commerce

• The router and the GraphQL connection are maintained by AI Commerce and are updated automatically to all stores from the main branch. The partner never touches the core files, so framework updates do not cause compatibility or merge conflicts with the partner's own code.

Connection to AI Commerce through the GraphQL API

• Services call the AI Commerce GraphQL API on the server side. Authentication is handled on the server as part of the framework — no separate session or new login is needed or supported. This way, store data (products, orders, customers) is available through the official, stable API without a direct database connection.

Shared domain and CloudFront

• Behind the merchant's domain is CloudFront, which routes /rest/* requests directly to the storefront function. The route is not cached, so write requests (POST, PUT, DELETE) also work correctly.

3. Use cases: when does a partner need their own REST API?

• ERP integrations: A partner can synchronize orders or product data to the merchant's ERP system with their own /rest/* service, which reads and writes data through the AI Commerce GraphQL API.
• Search and filter services: If AI Commerce's native search is not enough, the partner can bring their own logic or an external service and offer it to the merchant through a /rest/* route.
• New features: A partner can extend order, customer, or product handling with merchant-specific routes (e.g. webhooks, validations, extra logic) while retaining full compatibility with the core data structures.

4. Technical implementation: a REST service in practice

The partner adds their service to the storefront project's src/rest/ structure. The core framework — the router and the GraphQL client — is ready, so the partner only adds service files.

4.1 Folder structure

src/
 └─ rest/
     ├─ router.js          # Core router (maintained by AI Commerce)
     ├─ safeGraphqlClient.js  # Public GraphQL client (maintained by AI Commerce)
     └─ services/          # The partner's own services
         ├─ example.js     # GET /rest/example
         └─ orders.js      # /rest/orders

4.2 Service file

Each service file exports one or more HTTP-method handlers. The file location determines the URL path, so a new route is created simply by adding a file to the services/ folder.

// src/rest/services/example.js
import { executePublicGraphQL } from "../safeGraphqlClient.js"

export const GET = async () => {
  const data = await executePublicGraphQL(
    `query { products(limit: 1, offset: 0) { id name price } }`,
    {}
  )
  return { statusCode: 200, body: data.products }
}

The same file can also export POST, PUT, PATCH, and DELETE handlers for write operations.

Approved public data only. Service files call executePublicGraphQL, which allows only an approved public subset of the GraphQL schema — public catalog and content data such as products, categories, brands, and availability. Queries are read-only: mutations, subscriptions, introspection, field aliases, and any field outside the approved subset are rejected with the error code REST_GRAPHQL_OPERATION_NOT_ALLOWED before the request reaches GraphQL. No customer, order, payment, administrator, secret, or other private data is available through this client. The approved subset is maintained by AI Commerce and expanded deliberately. Direct ERP and backend integrations that need the full GraphQL API continue to use their own tenant credentials.

4.3 Authentication and limits

• GraphQL authentication is handled on the server side as part of the framework. The partner does not need to handle credentials in the service code.
• The GraphQL credentials are pre-configured as server-side environment variables in the storefront (set in serverless.yml, maintained by AI Commerce). The framework's GraphQL client uses them automatically; if you call the GraphQL API directly, you read them on the server from process.env. The variables have no VITE_ prefix, so they never reach the browser. You do not need to request the values separately — they are already in the storefront environment:
  • AICC_GRAPHQL_ENDPOINT – the GraphQL API URL (default https://api.aicommerce.fi/graphql)
  • AICC_TENANT_ID – the merchant identifier
  • AICC_TENANT_SECRET – the merchant secret
  • AICC_GRAPHQL_SECRET – the GraphQL secret
• The API uses no session and no separate login.
• The request rate is limited per merchant to prevent overload; when the limit is exceeded, the API returns an HTTP 429 response.

5. Deployment

• Add the service file to the src/rest/services/ folder in the merchant's storefront branch.
• The storefront is built and released again, and the new route becomes available. No separate service or your own deployment keys are needed.
• Test the route, for example:

curl https://merchant-domain.example/rest/example

• If everything is in order, you get an HTTP 200 response or another configured return code.

6. Why is this model useful?

Partners get the freedom to develop

• The partner adds new functionality by adding service files, without the AI Commerce core team having to build an integration every time.

No merge conflicts

• The core framework lives in the main branch and updates automatically. Because the partner only touches their own service files, framework updates do not collide with the partner's code.

Security and control stay with the AI Commerce team

• The connection to store data goes through the official GraphQL API, not directly to the database. AI Commerce retains full control of the infrastructure.
• Authentication is handled on the server side, so credentials do not end up in the browser.

Consistent user experience

• Because /rest/* is served through the same domain and the same function as the online store, the partner's services appear as a unified part of the shop.

Scalability and cost efficiency

• The storefront function scales automatically according to the AWS serverless model, and you pay only for usage.

7. Summary

AI Commerce storefronts offer a merchant-specific, customizable /rest/* API that the partner develops around the merchant's needs. The model supports the Composable Commerce architecture, in which each area is separate yet securely connected to AI Commerce's core services:

• One storefront function serves both the online store and the /rest/* API — no separate service to maintain.
• Service files in src/rest/services/ give the partner freedom and autonomy.
• The AI Commerce-maintained core framework keeps updates conflict-free.
• The official GraphQL API guarantees a stable and secure connection to store data.

Thank you for reading this article. We hope it gives you a clear understanding of how AI Commerce can be extended and customized with a merchant-specific REST API. If you need further guidance, you can contact the AI Commerce support team directly. Good luck on your Composable Commerce journey!