Documentation

Everything you need to map custom domains to WordPress pages from a single install — from your first domain to wildcard routing and the REST API.

Installation

Install Branchly the same way you would any WordPress plugin. The free tier activates instantly; a license key unlocks Pro and Agency features.

• Upload the plugin In your dashboard, go to Plugins → Add New → Upload Plugin and select the Branchly .zip.
• Activate Click Activate. Branchly adds a new Domains menu item under Settings.
• Add your license Open Settings → Branchly → License and paste the key from your account email.

Prefer the CLI? Run wp plugin install branchly --activate — see the WP-CLI section.

Requirements

Branchly runs on a standard single-site WordPress install. Multisite is not required.

Quick start

Map your first custom domain to an existing page in under five minutes.

• Point your DNS Create an A record for your domain that points at your server’s IP, or a CNAME to your WordPress host.

• Add the mapping In Settings → Branchly → Domains, click Add domain, enter the hostname, and choose the page it should serve.

• Verify & go live Branchly runs a DNS check, provisions SSL, and flips the status to live.

    dns · zone file
    # Point launch.acme.com at your WordPress server
    launch    IN  A      203.0.113.42
    # …or CNAME to your managed host
    launch    IN  CNAME  app.acme-hosting.com.

Adding a domain

Each mapping connects one hostname to one published WordPress page. A page can answer to several domains, but a domain only ever resolves to a single page.

• Hostname — the exact domain or subdomain, e.g. summer-launch.com or book.thereef.co.
• Target page — any published page, post, or custom post type.
• Redirect www — optionally fold www. into the bare domain.

Subdomains are free. Mapping a brand-new custom domain like acme-client.io requires a Pro or Agency license.

Domain verification

Before a domain goes live, Branchly confirms you control it. Verification runs automatically, but you can re-trigger it any time from the domain’s row.

If the automatic A/CNAME check can’t resolve, add the TXT record below and click Re-check.

dns · txt record
_branchly    IN  TXT  "branchly-verify=8f3c2a91d4e7"

SSL certificates

Once a domain verifies, Branchly requests a free Let’s Encrypt certificate and installs it automatically. Certificates renew in the background ahead of expiry — no cron entry required.

Behind a proxy or CDN? If Cloudflare or a load balancer terminates SSL, set BRANCHLY_SSL_MODE to passthrough so Branchly doesn’t request a duplicate certificate.

Wildcard routing

On the Agency plan, map an entire subdomain space to a single page or a dynamic template. Ideal for provisioning client subdomains at scale.

wp-cli
# Route every *.clients.acme.com to the onboarding page
wp branchly map "*.clients.acme.com" --page=428 --wildcard

Catch-all fallback

Designate one page as the destination for any domain that points at your server but has no explicit mapping. Use it for a holding page while DNS propagates, or a friendly 404.

• Set it under Settings → Branchly → Routing → Catch-all page.
• Exact and wildcard matches always take priority over the catch-all.

REST API

Automate domain onboarding from your own tooling. All endpoints live under /wp-json/branchly/v1 and authenticate with an application password or API key.

bash · curl
curl -X POST https://acme.com/wp-json/branchly/v1/domains \
-u "admin:application-password" \
-H "Content-Type: application/json" \
-d '{ "host": "launch.acme.com", "page_id": 428 }'

WP-CLI

Every dashboard action has a command-line equivalent under wp branchly. Great for scripting migrations and CI.

wp-cli
wp branchly map "launch.acme.com" --page=428   # add a mapping
wp branchly list --format=table              # list mappings
wp branchly verify "launch.acme.com"          # re-run verification
wp branchly import domains.csv               # bulk import

Diagnostics

When a domain won’t go live, the built-in diagnostics panel walks the full resolution path — DNS, verification, SSL, and routing — and tells you exactly which step failed.

• Find it at Settings → Branchly → Diagnostics, or run wp branchly doctor.
• Each check links to the relevant section of these docs for the fix.