Back to Docs

Custom domains

Attach a domain, the DNS records to create, and www redirects.

This is the guide the PageHub MCP server gives an AI agent for get_style_reference({ topic: "domains" }). Names like set_theme are its tools (connect one), and the liquid topic is the HTML + Liquid reference.
  1. check_domain (or get_domain_status with check) preflights a candidate without changing anything.
  2. set_domain attaches it and returns THE DNS RECORDS THE USER MUST CREATE at their registrar. Hand them back verbatim — targets are per-project (d3adb33f.vercel-dns-017.com, not a generic value you may remember) and a wrong one fails exactly like slow propagation.
    • Apex + www pair: both are registered. The apex needs an A record at @, www a CNAME.
    • A deeper subdomain (ads.example.com) is attached alone and needs one CNAME at its label.
    • redirectMode: to-apex (default, www → apex 308), to-www (apex → www 308), none (both serve). Change later with set_domain_redirect_mode.
  3. Attaching does not publish — call publish_site too. Nothing serves until the user creates the records; re-check with get_domain_status.

Errors:

  • 409: a variant is attached to another Vercel project. The user must detach it there, then retry.
  • 403 with upgrade: true: past the plan's domain count (Free 1, Pro 1 per site on the subscription, Business/Agency unlimited).

Detach with clear_domain (removes both variants, resets redirectMode). set_domain never takes an empty domain. Attaching triggers a rebuild when the site is published.