> For the complete documentation index, see [llms.txt](https://docs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.akinon.com/technical-guides/omnitron/multi-subdomain-configuration.md).

# Multi-Subdomain Configuration

This document outlines the steps required to implement and support **multi-subdomain setups** in a commerce architecture. It includes frontend configurations, authentication adjustments, domain mappings in the Omnitron, and subdomain-specific email template management.

## Implementation Checklist

* [x] **Set locale URL strategy to Subdomain**
* [x] **Update Auth handler for dynamic hostname and cookie domain**
* [x] **Configure Domain Name per Sales Channel**
* [x] **Assign Email Templates to Specific Subdomains**

## <mark style="color:red;">FRONTEND CONFIGURATION</mark>

### <mark style="color:red;">1. Setting the Locale URL Strategy to Subdomain</mark>

In order to enable locale handling via subdomains (e.g., `en.example.com`, `fr.example.com`), update the locale URL strategy in the frontend project settings.

**File:** `src/settings.js`

**Configuration:**

```js
localeUrlStrategy: LocaleUrlStrategy.Subdomain
```

<figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXeTKTJOkKur7bDXJhQ-9gjVJGbBoyWGF1QIw7LKcrRGw5qIqYCNM1TEM9hJfKXTYggiH8tHk0ME198-9QiNloLnrI11y_49hvvAoUQiVkQ1sotNYHdb_4IqZglJ8SBvT1NjBG5OjA?key=S91QmOslU6nq9_-hEI9iTg" alt="" width="563"><figcaption></figcaption></figure>

### <mark style="color:red;">2. Configuring Dynamic Hostname and Cookie Handling for Auth</mark>

To properly handle authentication cookies across multiple subdomains, you need to configure the authentication handler (`[...nextauth].ts`) to dynamically compute the `hostname` and apply the correct cookie `domain`.

**File:** `src/pages/api/auth/[...nextauth].ts`

```ts
import Auth from '@akinon/next/api/auth';
import getRootHostname from '@akinon/next/utils/get-root-hostname';
import type { NextApiRequest, NextApiResponse } from 'next';

const customOptions = (req: NextApiRequest) => {
  const fallbackHost = req.headers['x-forwarded-host'] || req.headers.host || '';
  const baseUrl = process.env.NEXT_PUBLIC_URL || `https://${fallbackHost}`;
  const hostname = getRootHostname(baseUrl);
  const isHttps = baseUrl.startsWith('https://') || process.env.NODE_ENV === 'production';

  if (!isHttps || !hostname) {
    return {};
  }

  process.env.NEXTAUTH_URL = `https://${fallbackHost}`;

  return {
    cookies: {
      sessionToken: {
        name: `${isHttps ? '__Secure-' : ''}next-auth.session-token`,
        options: {
          domain: hostname,
          httpOnly: true,
          sameSite: 'lax',
          path: '/',
          secure: isHttps,
        },
      },
    },
  };
};

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  return Auth(req, res, customOptions);
}
```

{% hint style="warning" %}
This setup ensures that the session cookie is properly scoped to the root domain (e.g., `.example.com`) and works across all subdomains securely.
{% endhint %}

## <mark style="color:red;">OMNITRON CONFIGURATION</mark>

### <mark style="color:red;">1. Domain Name Configuration per Sales Channel</mark>

In the Omnitron, navigate to: **Settings → Sales Channel Settings**

Under the corresponding sales channel, configure the **Domain Name Settings** to include all required subdomains (e.g., `ar-ae.example.com`, `ar-bh.example.com`, `ar-kw.example.com`, etc.).

<figure><img src="/files/Ozi3eJfAUn7h12bD3eHB" alt="" width="375"><figcaption></figcaption></figure>

This ensures that all subdomains are recognized and correctly handled in routing, content delivery, and environment-based logic.

### <mark style="color:red;">2. Subdomain-Specific Email Template Assignment</mark>

To send different email templates based on subdomain (e.g., locale or region-specific content), follow these steps:

Navigation: **Sales Channels → Content Management → Mailing Templates**

* Select the email template you wish to customize.
* Within the template configuration screen, locate the **Sites** field.
* Select the appropriate subdomains (sites) where this template should be active.

<figure><img src="/files/2rvd6corowdokHLuykYL" alt="" width="563"><figcaption></figcaption></figure>

This allows for targeted transactional or marketing emails tailored by region, locale, or brand variation via subdomain separation.

{% hint style="danger" %}
In multi-subdomain setups, attaching SSL certificates is currently handled **manually** on the ACC side.\
For such cases, please **open a ticket with Akinon Partner Support** to request certificate attachment.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.akinon.com/technical-guides/omnitron/multi-subdomain-configuration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.