# 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="https://2911598027-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlQinVPnOffBiOp126ldR%2Fuploads%2Fgit-blob-4f3fa3ee5082fd1552fc78c94c98becfdf2a47c2%2Fimage.png?alt=media" 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="https://2911598027-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlQinVPnOffBiOp126ldR%2Fuploads%2Fgit-blob-f0031327495f23553a41ed4fb19ffca77ed907c4%2Fimage.png?alt=media" 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 %}