PlanewardPlaneward Docs
PlanewardPlaneward Docs
Welcome
Sites overviewHeader and footerDark modeDomainsCollectionsRedirectsCrawlers and agentsLinked domainsExternal sites

Developers

REST APIAuthenticationWebhooksMCPEmbedded projectsTask description contentDeveloper hub

API

Sites

Linked domains

Keep visitor tracking when people click from your site to your app or checkout on another domain.

Site analytics follow a visitor with a first-party cookie on your site's domain. When someone clicks through to a different domain, such as app.example.com or a checkout, that cookie does not go with them. Linked domains hand the visit over on the link itself.

Set it up

Open Settings → Tracking → Linked Domains and add up to 10 domains, such as app.example.com. A bare hostname becomes https://app.example.com. Only https origins are allowed, and each subdomain is listed separately.

Changes go live on the next publish.

To track visits on a site you host elsewhere and hand them over the same way, see External sites.

Your workspace's community checkout is always linked; you don't need to add it. The community keeps the first visit it sees in a __Host-pw_visit cookie for 30 days, so product, checkout, and join pages still credit the site when the buyer opens them later without pw_site and pw_vid, from a new tab, a bookmark, or a cleaned-up link.

What the link carries

When a visitor clicks a link to a linked domain, Planeward adds two query parameters at click time:

ParameterValue
pw_siteThe site's id
pw_vidThe visitor's anonymous id, a UUID from the pw_vid cookie
https://app.example.com/signup?plan=pro&pw_site=cm3k9x2ab0001&pw_vid=3f1c2a9e-7b4d-4e8a-9c21-5d6e7f8a9b0c

Links that already have either parameter are left alone. Links to other domains never get them.

Read them in your app

Your app reads the parameters on landing, keeps them until the visitor buys, and sends them back with the purchase. A typical flow:

  1. On the first page load, read pw_site and pw_vid from the URL.
  2. Check pw_vid is a UUID and pw_site is a short id (64 characters or fewer). Ignore anything else.
  3. Store them in a first-party cookie or localStorage on your domain. Keep the first pair you see, and don't overwrite it on later visits.
  4. Remove them from the address bar so they aren't shared when someone copies the URL.
  5. On signup, save them on the user record.
  6. When that user pays, send them as siteVisit when you record the purchase.
const UUID =
  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;

export function captureSiteVisit() {
  const url = new URL(window.location.href);
  const siteId = url.searchParams.get("pw_site")?.trim() ?? "";
  const visitorId = url.searchParams.get("pw_vid")?.trim() ?? "";

  if (siteId && siteId.length <= 64 && UUID.test(visitorId)) {
    if (!localStorage.getItem("pw_visit")) {
      localStorage.setItem("pw_visit", JSON.stringify({ siteId, visitorId }));
    }
    url.searchParams.delete("pw_site");
    url.searchParams.delete("pw_vid");
    history.replaceState(null, "", url);
  }
}

export function storedSiteVisit(): {
  siteId: string;
  visitorId: string;
} | null {
  try {
    return JSON.parse(localStorage.getItem("pw_visit") ?? "null");
  } catch {
    return null;
  }
}

Send storedSiteVisit() with your signup request and store it on the user.

Send it with the purchase

Record the sale with POST /purchases or the MCP tool planeward-purchase-record, and pass the stored pair as siteVisit:

{
  "externalRef": "order_1042",
  "amount": 4900,
  "currency": "USD",
  "buyer": { "email": "[email protected]" },
  "siteVisit": {
    "siteId": "cm3k9x2ab0001",
    "visitorId": "3f1c2a9e-7b4d-4e8a-9c21-5d6e7f8a9b0c"
  }
}

Planeward checks that this visitor has a pageview on that site in your workspace. If so, the sale is credited to the visit: it shows up in the site's Analytics under the channel and campaign that brought the visitor, and the contact gets those first-touch UTMs if it had none. The response says what happened:

siteVisit in the responseMeaning
{ "credited": true, "siteId": "…" }Verified and credited
{ "credited": false, "reason": "invalid" }The ids are malformed
{ "credited": false, "reason": "not_found" }No pageview from that visitor on that site

An unverifiable visit never fails the purchase; the sale is still recorded. Recording is idempotent on externalRef, so a retry does not credit twice. A tampered link can't credit the wrong site or campaign.

Privacy

pw_vid is an anonymous id. It names no person until your app links it to an account. Treat it like any other analytics id: mention it in your privacy notice, and do not pass it on to other services.

Crawlers and agents

Robots rules, Content Signals, /.well-known files, structured data, and Markdown for AI agents.

External sites

Count visits from a site hosted elsewhere, such as a Next.js marketing site, in your Planeward site's analytics.

On this page

Set it upWhat the link carriesRead them in your appSend it with the purchasePrivacy