Account subdomains

An account subdomain lets one label in front of your store’s domain resolve to that store. Set Subdomain name to ambassador on an account, and ambassador.example.com serves your store instead of returning an error.

Use this when a partner, reseller, location, or customer group needs a URL of their own, sometimes called a vanity subdomain. For example, ambassador.example.com for a partner program, or downtown.example.com for a store location. Use the troubleshooting section when an account subdomain does not load.

What an account subdomain does and does not do

An account subdomain is a routing gate. It decides whether a host reaches your store, and nothing else.

It does:

• Resolve <label>.<store domain> to your store.
• Keep visitors on the branded URL. StoreConnect redirects traffic from your other connected hosts to your primary domain, but leaves a valid account subdomain alone.
• Keep generated links on the host the visitor arrived on, rather than rewriting them to the store domain.
• Expose account.subdomain to your theme and to POS templates.

It does not:

• Sign the visitor in, or associate them with that account. The account record is used to decide whether the host is valid and is then discarded. Anyone can visit the URL.
• Switch the price book, catalog, pricing, or theme.
• Grant API access. That is a separate api subdomain.
• Grant POS access. That is the pos_subdomain store variable. See Configure your POS access URL.

:::warning The description of the Subdomain name field, shown in Setup and in the Account object reference, suggests using the subdomain to apply a different price book. That describes something you could build, not behavior StoreConnect provides. Visiting an account subdomain changes no pricing on its own. See Build behavior behind the host. :::

Before you start

• Connect your domain and set it as the store domain. See Set your store domain and go live.
• You must own the domain, or have permission to manage its DNS settings.

Connect the subdomain

Each account subdomain is a host of its own. Connect it the same way as any other subdomain, so that DNS resolves it and SSL is provisioned for it.

1. Create a Web Domain record with Domain Name set to the full host, for example ambassador.example.com.
2. At your DNS provider, add a CNAME record for the host pointing at the record’s generated Target value.
3. Select Active on the Web Domain record and save. Wait until Status reads Success.

For the full procedure, including the status values, see Connect a domain to StoreConnect.

Create one Web Domain record per account subdomain. Leave Store Domain Name on the Store record as it is; the parent domain already identifies the store.

Set the subdomain on an account

1. Open the Account record.
2. Enter the label in Subdomain name (s_c__Subdomain__c). Enter the label only, not the full host: ambassador, not ambassador.example.com.
3. Click Save.

The field holds up to 18 characters and must be unique across your whole org. Two accounts cannot share a label, even when they trade with different stores, because subdomain labels share one namespace.

Diagnose an account subdomain that does not load

An account subdomain has to clear four checks in order, and the symptom tells you which check failed.

Symptom	Failing check	Fix
The browser cannot find the address at all	DNS does not resolve the host	Check the CNAME record points at the Target on the Web Domain record, and that the record’s Status is Success.
A certificate warning appears before the page loads	SSL has not been provisioned for the host	Confirm the Web Domain record reached Success. If it did and the warning persists, contact support.
The page reads “No store could be found at that URL”	Either the parent domain does not match the store, or no account holds that label	Open your store domain on its own. If it loads, the parent domain is correct and the label is the problem. Check the spelling of Subdomain name on the account. The lookup ignores case, so capitalization is not the cause.
The browser lands on your store domain instead of staying on the subdomain	A host-level redirect on your deployment catches the request before StoreConnect sees it	Contact support to have account subdomains excluded from the redirect.

A wrong parent domain and a missing label produce the same message, because both leave StoreConnect with no store to serve. The store domain test above tells them apart.

Build behavior behind the host

Because the account is only used to validate the host, your theme has to work out what to do with it. Three values are available:

Liquid	Returns
account.subdomain	The subdomain label held by an account
current_request.host	The hostname the visitor arrived on
current_account	The signed-in customer’s account, or blank when nobody is signed in

Read the label off the host with a filter:

```liquid

{%- assign label = current_request.host | split: “.” | first %} ```

For anything that affects pricing or entitlement, drive the branch from the signed-in customer’s account rather than the host. The host is public, so treating it as proof of identity would let anyone claim a partner’s pricing by typing their URL.

```liquid

{%- if current_account != blank and current_account.subdomain == label %}

Welcome back to the {{ current_account.name }} store.

{%- endif %} ```

Use the host for presentation, such as a partner logo or a welcome message, and the signed-in account for anything that changes what a customer pays or sees.

Once the Web Domain record reads Success and the account label is saved, the account subdomain serves your store, visitors stay on it rather than being redirected, and account.subdomain is available to your theme.