Custom Domain Setup and Routing

What This Feature Does

Custom Domain lets you use your own domain on yLnk instead of only using the primary yLnk hosts. Example:

• Default short link: https://ylnk.cc/abc123
• Branded short link: https://go.yourbrand.com/abc123
• Branded LinkFolio root: https://links.yourbrand.com/
• Branded yShop root: https://shop.yourbrand.com/

The implementation stores every custom domain as a BRANDED domain. A newly added domain starts as PENDING, becomes ACTIVE only after DNS verification and Cloudflare hostname provisioning succeed, and can move to FAILED when verification does not pass.

Only ACTIVE domains are routed publicly. Pending or failed domains stay registered in your account, but they are not treated as usable public origins or root mappings.

Who It Is For

• Teams that want branded short links for campaigns, QR codes, and support flows.
• Creators who want a LinkFolio profile on their own domain.
• Merchants who want a yShop storefront on a branded host.
• Teams that need domain-specific SEO files, app links, or survey routing.

Before You Start

Required Access

You need access to the yLnk account or organization that owns the domain. In organization mode, domain registration and verification require manager-level access, while mapping and configuration changes require owner or editor access.

You also need access to your DNS provider. yLnk verifies that your domain points to the expected CNAME target before activating it.

Domain Format

Enter the domain only, without protocol or path:

go.yourbrand.com

Do not enter:

https://go.yourbrand.com/abc123

The backend rejects invalid and internal-looking hosts such as localhost, .local, .internal, and .test.

DNS Target

The configured CNAME target is:

host.ylnk.cc

For a subdomain like go.yourbrand.com, create a CNAME record in your DNS provider:

DNS propagation can take time. Verification may fail until your DNS provider returns the new record consistently.

Active Domain Rules

• A domain must be ACTIVE before it can be attached to LinkFolio or yShop.
• A domain can be attached to either LinkFolio or yShop, not both.
• A domain already attached to one LinkFolio or one yShop store cannot be attached to another target without detaching it first.
• Only ACTIVE domains can be marked canonical.
• Domain-specific robots.txt and sitemap.xml overrides are allowed only for ACTIVE domains.

Step-by-Step

Add The Domain

🧭 1. Navigate: App > Domains. 2. Click Add Domain. 3. Enter the domain without https://, for example go.yourbrand.com. 4. Save the domain.

The domain is registered as PENDING. At this point, yLnk has reserved the domain in the system so another account or organization cannot claim the same host.

Add The DNS Record

1. Open your DNS provider.
2. Create a CNAME record pointing your domain to host.ylnk.cc.
3. Save the DNS record.
4. Wait for DNS propagation.

Example:

go.yourbrand.com CNAME host.ylnk.cc

If your DNS provider shows a trailing dot, that is normal:

host.ylnk.cc.

Verify The Domain

1. Return to App > Domains.
2. Open the domain you added.
3. Click Verify.

yLnk checks DNS in layers:

• First, it checks whether the domain has a CNAME that exactly points to host.ylnk.cc.
• If Cloudflare proxying or CNAME flattening hides the CNAME, it checks whether the domain reaches the public verification probe.
• If the probe responds with the yLnk verification marker, the backend can activate the domain.

When verification succeeds, yLnk provisions the Cloudflare Custom Hostname, stores the Cloudflare hostname id, marks DNS and SSL as active, changes the domain status to ACTIVE, and refreshes the CORS and SEO caches.

Map The Root Page

After a domain is ACTIVE, choose what should appear at the root path:

• LinkFolio root: https://links.yourbrand.com/
• yShop root: https://shop.yourbrand.com/

For LinkFolio:

1. Navigate: App > LinkFolio.
2. Open the profile settings.
3. Attach the active custom domain.
4. Verify the root domain in a new browser tab.

For yShop:

1. Navigate: App > yShop.
2. Open the store settings.
3. Attach the active custom domain.
4. Verify the root domain in a new browser tab.

Root rendering is masked. The browser stays on your custom domain while Nginx internally sends the request to the correct frontend route.

Use Short Links

Short-link paths are supported on custom domains. Example:

https://go.yourbrand.com/abc123

On a custom domain, a single-segment path like /abc123 is sent to the backend first. If the backend resolves it as a short link, it redirects according to the short-link configuration. If it cannot resolve the path, Nginx falls back to the frontend.

⚠️ If a short code is moved to an active custom domain, the same code on ylnk.cc may return 404 while the custom-domain mapping is active.

Set The Canonical Domain

If multiple active domains point to the same LinkFolio or yShop store, choose one canonical domain.

1. Open the active domain.
2. Mark it as canonical.
3. Save the change.
4. Test another mapped domain.

When a non-canonical mapped domain receives a root request, the backend redirects it permanently to the canonical host while preserving the path and query string.

Example:

https://old.yourbrand.com/?ref=launch

redirects to:

https://links.yourbrand.com/?ref=launch

Configure SEO Files

For active domains, yLnk can serve host-aware SEO files:

• https://yourdomain.com/robots.txt
• https://yourdomain.com/sitemap.xml
• https://yourdomain.com/sitemaps.xml

By default, robots.txt allows crawling and points to the domain's sitemap. The default sitemap includes the root URL. If the domain is mapped to LinkFolio, it can also include the explicit @username URL.

Use custom overrides only when you need domain-specific robots or sitemap content. The backend clears the SEO cache when these settings change.

Verify Routing

✅ After setup, check these URLs:

1. https://yourdomain.com/v2/domains/public/verify-probe
2. https://yourdomain.com/
3. https://yourdomain.com/robots.txt
4. https://yourdomain.com/sitemap.xml
5. A known short link path, such as https://yourdomain.com/abc123

If the domain is mapped to yShop, also check storefront paths like /featured, /categories, /products, /cart, /checkout, /order, and /policy.

Common Issues

Domain Format Is Rejected

Use only the host name. Do not include protocol, path, query string, or fragments.

Correct:

links.yourbrand.com

Incorrect:

https://links.yourbrand.com/profile?ref=test

Verification Fails

The most common reason is DNS mismatch. Confirm that the domain points to host.ylnk.cc.

If the response says no CNAME was found, your DNS provider may not have propagated the record yet. If it says the target is different, update the record and retry.

For Cloudflare-proxied or flattened records, yLnk can also verify reachability through the public verification probe. That still requires the domain to route to the yLnk backend.

Domain Stays Pending

PENDING means the domain is registered but not active. Add or fix the DNS record, wait for propagation, and run verification again.

Domain Becomes Failed

FAILED means verification ran but did not pass. The domain is still in your account, but yLnk removes it from the allowed CORS cache and does not route it as an active custom domain.

Fix DNS and verify again.

Root Page Shows 404

An active domain can still show 404 if it has no valid root mapping.

Check whether it is attached to a published yShop store or an active LinkFolio profile. If neither root mapping exists, the custom-domain root is treated as unresolved.

Cannot Attach To LinkFolio

The domain must be ACTIVE, must belong to the current user or organization context, and must not already be attached to a yShop store or another LinkFolio profile.

Cannot Attach To yShop

The domain must be ACTIVE, must belong to the current user or organization context, and must not already be attached to a LinkFolio profile or another yShop store.

Custom Domain Short Link Works But yLnk Fails

This can be expected. When a short code is active on a custom domain, the same short code on the primary ylnk.cc host may return 404 until the domain mapping changes.

Social Preview Looks Old

Many platforms cache previews. After updating SEO data, test with the platform's preview debugger or validator and wait for their cache to refresh.

FAQs

Can I Add An Apex Domain

The backend expects a normal domain format and can verify CNAME records or Cloudflare-proxied reachability. In practice, subdomains like go.yourbrand.com are the simplest setup because they support a direct CNAME to host.ylnk.cc.

For apex domains like yourbrand.com, your DNS provider must support flattening or proxying that still reaches yLnk.

Can One Domain Point To Multiple Products

One domain can host path-based features, such as short links and surveys, but the root path can be mapped to only one primary root owner at a time: LinkFolio or yShop.

If stale data ever contains both root mappings, public route resolution gives yShop priority before LinkFolio.

What Routes Work On Custom Domains

Custom domains support root pages, short-link paths, survey paths under /s/, deep-link paths under /dl/ and /d/, SEO files, app-link files under /.well-known/, and yShop public paths when the domain is mapped to a store.

Does Deleting A Domain Remove Cloudflare Setup

Yes. When a domain is deleted, yLnk attempts to remove the Cloudflare Custom Hostname by its stored Cloudflare id, deletes the database record, and evicts CORS and SEO cache entries.

Can I Use The Domain As An API Origin

Only active custom domains are loaded into the CORS cache. Pending, failed, and deleted domains are blocked as trusted origins.

Does Verification Work In Development

In development mode, the backend can activate a domain without real DNS or Cloudflare provisioning so the UI and routing flow can be tested locally.

Security Notes

🔒 Domain ownership is enforced by registration uniqueness and DNS verification. A domain already registered in yLnk cannot be claimed again by another user or organization.

The backend resolves the effective host using trusted proxy headers first, then the request host. Primary yLnk domains are excluded from custom-domain lookup so the core app does not accidentally resolve as a tenant domain.

Custom domains are added to the allowed CORS cache only after successful activation. Failed and deleted domains are removed from the cache.

Analytics and Tracking

Custom domains keep the branded host in the visitor-facing URL. Short-link analytics, routing, UTM behavior, and retargeting behavior continue to come from the linked yLnk feature configuration.

For root pages, LinkFolio and yShop analytics should be viewed in their own analytics areas. The domain controls the host and route ownership; it does not replace the product-specific analytics screens.

Limits by Plan

Custom domains count against the account or organization's branded-domain limit. If the current plan has reached its limit, yLnk rejects new domain registration with a payment-required response.

The limit is checked before the domain record is created.

API Notes

The implementation exposes these domain APIs:

Minimal register request:

{ "domain": "go.yourbrand.com" }

Minimal LinkFolio mapping request:

{ "linkFolioId": "linkfolio-id", "attachDomainIds": ["domain-id"], "detachDomainIds": [] }

Minimal yShop mapping request:

{ "storeId": "store-id", "attachDomainIds": ["domain-id"], "detachDomainIds": [] }