---
schema_version: "1"
id: a21198262385cad06df8e2466164d52f67a1d3d4ebaf0b2d2060c7d48c0349df
title: CDN Routing Rules for Hybrid Implementations
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/commerce-api/guides/ecdn-rules-for-phased-headless-rollout.md
canonical_url: https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ecdn-rules-for-phased-headless-rollout.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 8cbd4cc2a2d1933338d3026f465d2758ac99ede14e1d535b35461835b85d6ff6
products:
  - Composable Storefront
  - Salesforce APIs
---
# CDN Routing Rules for Hybrid Implementations

A phased headless rollout is a technique for delivering a single shopping experience using multiple storefront technologies like Storefront Reference Architecture (SFRA) and Composable Storefront.

**note:** **Applies to:** Hybrid storefronts whose headless runtime is hosted on Managed Runtime (MRT)—both Storefront Next and PWA Kit (Composable Storefront). For a custom headless storefront hosted on a different origin, use your CDN's origin-routing equivalent with the same path split. The local-development hybrid proxy is a PWA Kit feature.

## Traffic Routing for Hybrid Apps with and without eCDN

An embedded CDN (eCDN) is available for Primary Instance Group (PIG) environments, such as production or staging, and for on-demand sandbox (ODS) instances. eCDN can route traffic to both SFRA and Managed Runtime (MRT) at the same time, allowing you to gradually roll out a Composable Storefront. Local development servers don't have an eCDN; in that case, use the hybrid proxy to route traffic to SFRA.

![Hybrid app sequence of requests and responses for a SIG instance](https://developer.salesforce.com/docs/media/commerce-api/hybrid-app-traffic-routing2.png '{"class": "image-lg"}')

## Traffic Routing for Local Development without eCDN

For local development servers, which don't have an eCDN, develop and test hybrid shopper apps that use PWA Kit and SFRA or SiteGenesis by enabling the hybrid proxy feature in the `pwa-kit-runtime` package in PWA Kit v3.14.0 and later. On ODS instances, use eCDN instead of the hybrid proxy.

For more information, see [Configure a Hybrid Storefront with Hybrid Auth (PWA Kit)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/hybrid-auth.md).

## Traffic Routing for PIG Instances with eCDN

For PIG instances, an eCDN zone can route traffic to both SFRA and MRT at the same time, allowing you to gradually roll out a Composable Storefront.

This diagram shows the sequence of requests and responses when an eCDN routes an incoming page request for a hybrid app for a PIG instance. If the request matches MRT rules, it is forwarded to MRT. Otherwise, if the request doesn't match MRT rules, it is sent to the B2C Commerce instance, and then a response is returned.

![Hybrid app sequence of requests and responses for a SIG instance](https://developer.salesforce.com/docs/media/commerce-api/hybrid-app-with-cdn.png '{"class": "image-lg"}')

You can configure hybrid routing rules in two ways. We recommend using the Business Manager eCDN UI for most implementations. Use the [B2C CLI](#route-traffic-to-managed-runtime) or [CDN Zones API](#configure-routing-rules-with-the-cdn-zones-api) when you need to automate or script rule management.

## Configure Routing Rules in the Business Manager UI

The embedded CDN (eCDN) UI in Business Manager is the recommended way to add and manage hybrid routing rules. It lets you configure rules without writing API payloads.

1. In Business Manager, go to **Administration > Sites > Embedded CDN Settings**.
2. Locate the zone that contains your storefront hostname (typically the default zone).
3. Click the caret on the right side of the zone title, then select **Configure Routing Rules**.

   ![Embedded CDN settings zone actions for configuring routing rules](https://developer.salesforce.com/docs/media/commerce-api/ecdn-configure-routing-rules.png '{"class": "image-xl"}')

4. Locate the routing rule for your hostname and click **Edit**.
5. Confirm that the **Hostnames** and **MRT Origin** fields are prefilled and match your setup. Find your MRT Origin (the Managed Runtime environment domain) in **Environment Settings** in Runtime Admin.
6. In **Rule expression**, enter the Cloudflare expression that matches the routes you want to serve from Managed Runtime.
7. Click **Save**.

For architecture-specific, copy-ready rule expressions, see:

- Storefront Next: [Set Up Hybrid Storefront with On-Demand Sandbox (ODS) Instances Using eCDN](https://developer.salesforce.com/docs/commerce/sfnext/guides/sfnext-hybrid-ods.md) and [Hybrid Storefront Routing Matrix](https://developer.salesforce.com/docs/commerce/sfnext/guides/sfnext-hybrid-routing-matrix.md).
- PWA Kit / Composable Storefront: [Configure a Hybrid Storefront with Hybrid Auth (PWA Kit)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/hybrid-auth.md).

**note:** The eCDN UI is available for Primary Instance Group (PIG) and on-demand sandbox (ODS) instances. For local development, use the hybrid proxy instead of eCDN routing rules.

## Configure Routing Rules with the CDN Zones API

If you need to automate or script routing-rule management, use the [Commerce API CDN Zones](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=Summary) API to route traffic to Managed Runtime.

Before running the commands in this section, replace any placeholders with actual values. Placeholders are formatted like this: `$PLACEHOLDER`. Throughout this section, we use an example storefront with the production URL `https://www.example.com`.

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


### Prerequisites

1. Familiarize yourself with [Authorization for Admin APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html)
2. You must have an Account Manager API Client with the scope `sfcc.cdn-zones.rw`.
3. You must know the zone ID of the eCDN zone to be used with Managed Runtime. To get this info, use the [getZonesInfo](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=getZonesInfo) endpoint of the CDN Zones API.
4. Use [updateSecuritySettings](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=updateSecuritySettings) to enable `alwaysUseHttps` on the zone. _Managed Runtime only supports traffic over HTTPS._
5. Set your SLAS API Client’s `redirect_uri` to include the zone.
6. If you have [restricted the set of IPs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html#edit-environment-settings) allowed to access your Managed Runtime environment, add the [CloudFlare IPs](https://www.cloudflare.com/ips/) used by eCDN to the set of allowed IPs.

### Route Traffic to Managed Runtime

With the [createMrtRules](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=createMrtRules) endpoint, create rules that route traffic to a Managed Runtime environment:

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
# Required scopes: sfcc.cdn-zones, sfcc.cdn-zones.rw
export SFCC_CLIENT_ID='your-account-manager-client-id'
export SFCC_CLIENT_SECRET='your-account-manager-client-secret'
export SFCC_SHORTCODE='your-short-code'

npx @salesforce/b2c-cli ecdn zones list --tenant-id abcd_stg

npx @salesforce/b2c-cli ecdn mrt-rules create \
  --tenant-id abcd_stg --zone stg-abcd-example-com.cc-ecdn.net \
  --mrt-hostname example-production.mobify-storefront.com \
  --expressions 'http.host eq "www.example.com" and http.request.uri.path matches "^/products"'
```

Alternatively, use the API:

```bash
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/mrtrules" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "mrtHostname": "example-production.mobify-storefront.com",
    "expressions": [
      "http.host eq \"www.example.com\" and http.request.uri.path matches \"^/products\""
    ]
  }'
```

Let’s examine the data provided in the request body.

The value of `mrtHostname` is the domain of the Managed Runtime environment for traffic routing. It must refer to a Managed Runtime environment hosted on the `mobify-storefront.com` or `exp-delivery.com` domain. If the provided value is used by an existing rule, the request fails.

**note:** Managed Runtime is the only supported routing destination.

The value of `expressions` is an array of [Cloudflare rule expressions](https://developers.cloudflare.com/ruleset-engine/rules-language/expressions/) that controls which requests are routed to Managed Runtime. For most implementations, a single routing expression is sufficient.

In addition to the provided expressions, the following default routing rules are used:

```text
(
  http.request.uri.path matches "^/callback.*" or
  http.request.uri.path matches "^/mobify.*" or
  http.request.uri.path matches "^/worker\.js.*"
)
```

Routing changes are applied immediately, and navigating to a URL that matches an expression returns content retrieved from Managed Runtime.

#### Routing Scenarios

- The following routing scenarios are supported:

  - A single hostname mapped to a single MRT environment:

    - For example, `http.host eq \"www.example.com\"` → `example-production.mobify-storefront.com`

  - Multiple hostnames mapped to a single MRT environment:

    - For example, `http.host in {\"www.example.com\" \"prod.example.com\" \"us.example.com\"}`→ `example-production.mobify-storefront.com`

- The following routing scenario is currently **not** supported:
  - A single hostname mapped to multiple MRT environments based on different paths

#### Expression Constraints

Expressions are validated against the following criteria:

- `http.host` must occur exactly once and must be followed by either the `eq` or `in` operator. See above for usage examples.
- The hostname(s) must match the zone. Or in other words, the eCDN zone must have a valid certificate that covers the provided hostname(s).
- The following fields are supported:
  - `http.host`
  - `http.request.uri.path`
  - `http.request.uri`
  - `http.cookie`
- The maximum length of an expression is 3072 characters.
- A maximum of 300 expressions can be associated with a zone.

### Modify Routing Configuration

As you continue your phased rollout, route more requests to Managed Runtime.

To modify a routing expression, use [getMrtRules](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=getMrtRules) to get the IDs of the ruleset and rule associated with the expression you want to update:

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/mrtrules" \
--header "Authorization: Bearer $TOKEN"
```

Next, use [updateMrtRule](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=updateMrtRule) to update the expression:

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
npx @salesforce/b2c-cli ecdn mrt-rules rules update \
  --tenant-id abcd_stg --zone stg-abcd-example-com.cc-ecdn.net \
  --ruleset-id your-ruleset-id --rule-id your-rule-id \
  --expression 'http.host eq "www.example.com" and (http.request.uri.path matches "^/products" or http.request.uri.path matches "^/categories")'
```

Alternatively, use the API:

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/mrtrules/$RULESET/rules/$RULE" \
--request 'PATCH' \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json' \
--data '{
    "expression": "http.host eq \"www.example.com\" and (http.request.uri.path matches \"^/products\" or http.request.uri.path matches \"^/categories\")"
  }'
```

#### Add More Routing Configurations

To add more routing rules to **an existing** Managed Runtime environment, use [updateMrtRuleset](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=updateMrtRuleset) and provide the `mrtHostname` and additional routing expressions:

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/mrtrules" \
  --request 'PATCH' \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "mrtHostname": "example-production.mobify-storefront.com",
    "expressions": ["http.host eq \"www.example.com\" and http.request.uri.path matches \"^/home\""]
  }'
```

To add routing rules for a **new** Managed Runtime environment, use the [createMrtRules](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=createMrtRules) endpoint and provide a new `mrtHostname` value:

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/mrtrules" \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json' \
--data '{
    "mrtHostname": "example-development.mobify-storefront.com",
    "expressions": [
      "http.host eq \"dev.example.com\" and http.request.uri.path matches \"^/products\""
    ]
  }'
```

#### Modify Managed Runtime Environment

To update existing rules to route to a different Managed Runtime environment, use [updateMrtRuleset](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=updateMrtRuleset) and provide the `oldMrtHostname` and the (new) `mrtHostname` that you want to route to:

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/mrtrules" \
  --request 'PATCH' \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "oldMrtHostname": "example-old.mobify-storefront.com",
    "mrtHostname": "example-new.mobify-storefront.com"
  }'
```

### Disable Routing

If you're switching to a third-party CDN or you no longer want to route a particular path from eCDN to MRT, disable routing.

To disable routing, use [getMrtRules](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=getMrtRules) to get the IDs of the configuration that you want to delete:

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/mrtrules" \
--header "Authorization: Bearer $TOKEN"
```

Then, to remove the Managed Runtime routing rule, use [deleteMrtRule](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=deleteMrtRule) and pass in the applicable IDs returned by [getMrtRules](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=getMrtRules):

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/mrtrules/$RULESET/rules/$RULE" \
--request 'DELETE' \
--header "Authorization: Bearer $TOKEN"
```

If you want to remove all Managed Runtime routing rules, use [deleteMrtRuleset](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=deleteMrtRuleset):

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/mrtrules/$RULESET" \
--request 'DELETE' \
--header "Authorization: Bearer $TOKEN"
```

### Route All Traffic to Managed Runtime

When you complete your phased rollout or if you are launching a new site, route all traffic for a zone to Managed Runtime using a single expression:

```text
http.host eq \"www.example.com\"
```

## See Also

- [Hybrid Implementation Guidance](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-storefront-baskets.md)
- [Hybrid Authentication](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-authentication.md)