# RevCent MCP Overview: Tracking Domains and Conversion Tracking

This document explains RevCent Tracking Domains for MCP/AI usage. It covers what tracking domains are, why they matter for ecommerce conversion attribution, how DNS-based tracking works, how URL parameters become metadata, and how the tracking-domain API operations should be used.

Sources:
- RevCent Knowledge Base: RevCent Track.js — `https://kb.revcent.com/tracking/revcent-trackjs`
- RevCent Knowledge Base: Conversion Tracking — `https://kb.revcent.com/tracking/conversion-tracking`
- RevCent API/MCP operation schemas:
  - `GetTrackingDomains`
  - `CreateTrackingDomain`
  - `GetTrackingDomain`
  - `EditTrackingDomain`
  - `InitializeTrackingDomainSSL`
  - `InitializeTrackingDomainDNS`

---

## What Is a Tracking Domain?

A RevCent Tracking Domain is a root domain configured with custom DNS records so RevCent can perform first-party visitor and conversion tracking for that domain.

A tracking domain is used to:

- Track visitors on ecommerce sites.
- Persist visitor identity using first-party tracking.
- Capture URL parameters such as `utm_source`, `utm_campaign`, `gclid`, `fbclid`, `sub_id`, or affiliate IDs.
- Save tracked URL parameter values as RevCent metadata.
- Associate visitor activity with later purchases.
- Improve conversion attribution.
- Support reporting by traffic source, affiliate, campaign, ad, keyword, or other marketing dimensions.
- Power more accurate conversion data for RevCent reporting, BigQuery, dashboards, and chargeback documentation.

In practical terms, a tracking domain lets RevCent connect:

```text
Visitor → Tracking activity → URL parameters / metadata → Sale / conversion
```

---

## Why Tracking Domains Matter

Most ecommerce businesses need to know where purchases came from.

Examples:

- Which campaign generated this sale?
- Which affiliate sent this customer?
- Which ad click became a purchase?
- Which landing page converted best?
- Which UTM campaign produced the most revenue?
- Which traffic source generated refunds or chargebacks?
- Which Google Ads `gclid` belongs to the sale?
- Which sub ID should receive credit?

Tracking Domains help answer these questions by preserving visitor attribution data before checkout and attaching that attribution to resulting RevCent records.

---

# DNS-Based Tracking Purpose

RevCent Tracking Domains use custom DNS and SSL to enable in-house DNS tracking.

The tracking-domain schema describes tracking domains as custom DNS with free SSL that enables first-party cookies required for accurate visitor tracking, especially across domains. Once the domain is properly set up and SSL is issued, RevCent's in-house DNS tracking can be used for accurate conversion metrics.

This matters because modern browsers, ad blockers, cross-domain flows, cookie restrictions, and third-party tracking limitations can make normal tracking less reliable.

DNS-based tracking improves reliability by using infrastructure tied to the merchant's own domain.

---

## Why First-Party Tracking Helps

First-party tracking means the visitor tracking is associated with the merchant's own domain rather than a generic third-party tracking domain.

Benefits:

- More reliable visitor identity.
- Better continuity across pages and checkout.
- Stronger attribution between visit and conversion.
- More accurate tracking of URL parameters.
- Better ability to connect ad click data to sales.
- Better reporting by metadata.
- Better conversion details for analysis and chargeback support.

---

# How Conversion Tracking Works

At a high level:

1. A visitor lands on a tracked domain.
2. RevCent Track.js / DNS tracking identifies the visitor.
3. URL parameters are captured.
4. The tracking domain saves selected URL parameters as metadata.
5. The visitor continues browsing, adding products, or moving through checkout.
6. When a sale or conversion occurs, RevCent associates the purchase with the tracked visitor.
7. The sale/conversion can include visitor details, tracking details, metadata, references, and ad-related values.
8. Reporting can group, filter, or attribute conversions based on the saved metadata.

Example flow:

```text
https://example.com/?utm_source=google&utm_campaign=spring_sale&gclid=abc123
        ↓
Tracking Domain captures visitor and parameters
        ↓
RevCent saves metadata:
utm_source = google
utm_campaign = spring_sale
gclid = abc123
        ↓
Customer purchases
        ↓
Sale/conversion is associated with visitor and metadata
        ↓
Revenue can be reported by source, campaign, affiliate, gclid, etc.
```

---

# RevCent Track.js

RevCent Track.js is the JavaScript tracking layer used with tracking domains.

Track.js helps RevCent identify visitors and connect browsing/session information to later sales or conversions.

Use Track.js when a website, landing page, funnel, or store needs RevCent visitor tracking.

Common use cases:

- Landing-page tracking.
- Campaign attribution.
- Cross-page visitor tracking.
- Passing visitor IDs into checkout.
- Recording traffic-source metadata.
- Tracking conversions from ad platforms.
- Improving RevCent reporting accuracy.

---

## Providing the Visitor ID

For conversion tracking to work correctly, RevCent must be able to associate the visitor with the sale or checkout event.

Depending on the site implementation, this may be handled by the RevCent WordPress plugin or by a non-WordPress/custom implementation.

Common implementation patterns:

| Site Type | Visitor ID Handling |
|---|---|
| WordPress / supported plugin | Plugin handles DNS tracking and visitor ID integration when enabled/configured. |
| Custom / non-WordPress site | Developer must ensure the RevCent visitor ID is passed into the relevant checkout or sale creation flow. |
| Third-party shop / custom funnel | The store/funnel must preserve visitor identity through the checkout process. |

Important:

- Tracking the visit alone is not enough.
- The conversion must be tied back to the visitor.
- If the visitor ID is not provided or preserved, attribution may be incomplete.

---

# Tracking Domain API Operations

## `GetTrackingDomains`

Returns a paginated list of tracking domains.

Use it to:

- Find existing tracking domains.
- Check whether a domain is already configured.
- Inspect SSL/DNS status.
- Retrieve tracking domain IDs.
- Review URL parameters associated with tracking domains.

Required input:

```json
{
  "limit": 25,
  "page": 1
}
```

Important output fields:

| Field | Description |
|---|---|
| `id` | 20-character tracking domain ID. |
| `name` | User-friendly tracking domain name. |
| `description` | Tracking domain description. |
| `enabled` | Whether the domain is enabled. |
| `domain` | Root domain associated with the tracking domain. |
| `url_parameter_sets` | URL parameter set IDs associated with this domain. |
| `url_parameters` | Manually configured URL parameters to save. |
| `a_records` | DNS A records required for tracking endpoints. |
| `ssl.status` | SSL setup status. |
| `ssl.cname_records` | CNAME records required for SSL validation. |
| `dns.status` | DNS tracking setup status. |

---

## `CreateTrackingDomain`

Creates a tracking domain and returns a new `tracking_domain_id`.

Use it when a merchant needs to set up tracking for a root domain.

Example request:

```json
{
  "name": "Main Store Tracking",
  "description": "Tracking domain for example.com ecommerce store.",
  "domain": "example.com"
}
```

Required by schema:

| Field | Required | Description |
|---|---:|---|
| `name` | Yes | Unique tracking-domain name. |

Strongly recommended:

| Field | Why |
|---|---|
| `description` | Documents what the domain is for. |
| `domain` | Root domain to track, such as `example.com`. |

Important schema notes:

- `domain` should be the root domain, not a subdomain such as `www.example.com`.
- Only requests from the root domain are tracked.
- The domain cannot be modified after creation.
- The user must own the domain and be able to modify DNS records.
- The response includes `a_records` that must be added to DNS.

Output includes:

```json
{
  "tracking_domain_id": "XXXXXXXXXXXXXXXXXXXX",
  "a_records": [
    {
      "name": "rctrk",
      "value": "..."
    }
  ]
}
```

---

## `GetTrackingDomain`

Retrieves one tracking domain by ID.

Use it to:

- Retrieve current A records.
- Retrieve CNAME records after SSL initialization.
- Check SSL status.
- Check DNS status.
- Inspect URL parameter configuration.
- Confirm whether the domain is ready.

Example request:

```json
{
  "tracking_domain_id": "XXXXXXXXXXXXXXXXXXXX"
}
```

---

## `EditTrackingDomain`

Edits an existing tracking domain.

Use it to modify properties such as:

- Name
- Description
- Enabled status
- URL parameter sets
- URL parameters

Important:

- Do not expect to change the root `domain`; schema states the domain cannot be modified after creation.
- Only include fields you intend to edit.
- Be careful editing URL parameter behavior because it affects future attribution and metadata.

---

## `InitializeTrackingDomainSSL`

Initializes SSL for a tracking domain.

Required input:

```json
{
  "tracking_domain_id": "XXXXXXXXXXXXXXXXXXXX"
}
```

Before calling:

1. The tracking domain must already exist.
2. The A records returned from `CreateTrackingDomain` or `GetTrackingDomain` must be added to the domain's DNS.

After calling:

- The response includes `ssl.cname_records`.
- The user must add those CNAME records to DNS.
- RevCent validates those records to issue SSL.

SSL status values:

| Status | Meaning |
|---|---|
| `NOT_INITIALIZED` | SSL setup has not started. |
| `PENDING_VALIDATION` | RevCent is waiting for CNAME verification. |
| `VALIDATION_TIMED_OUT` | CNAME verification timed out. |
| `ISSUED` | SSL certificate was issued successfully. |
| `FAILED` | SSL issuance failed. |

---

## `InitializeTrackingDomainDNS`

Completes DNS tracking setup after DNS records and SSL are ready.

Required input:

```json
{
  "tracking_domain_id": "XXXXXXXXXXXXXXXXXXXX"
}
```

Before calling:

1. A records must have been added to the domain DNS.
2. SSL must have been initialized.
3. CNAME records from `InitializeTrackingDomainSSL` must have been added.
4. SSL should be issued successfully.

RevCent verifies required DNS records before completing initialization.

DNS status values:

| Status | Meaning |
|---|---|
| `AWAITING_SSL` | DNS setup is waiting for SSL status `ISSUED`. |
| `NOT_INITIALIZED` | DNS setup has not started. |
| `PENDING` | DNS initialization is in progress. |
| `COMPLETE` | DNS tracking setup is complete and ready to use. |

---

# Setup Lifecycle

The API schema describes this setup sequence:

1. Create a tracking domain using `CreateTrackingDomain`.
2. Add the returned A records to the domain's DNS settings.
3. Initialize SSL using `InitializeTrackingDomainSSL`.
4. Add the returned CNAME records to the domain's DNS settings.
5. Initialize DNS using `InitializeTrackingDomainDNS`.
6. Confirm DNS status is `COMPLETE`.
7. Install/configure Track.js or the appropriate platform/plugin integration.
8. Confirm visitor IDs are passed into conversion/sale flows.
9. Confirm URL parameters are saved as metadata.

---

## DNS Record Types

### A Records

A records are returned when the tracking domain is created.

They are used to route tracking endpoints and initialize the tracking infrastructure.

Schema examples include record names such as:

```text
rctrk
portal
rcacp
```

The user must add the exact returned A records to the DNS provider.

### CNAME Records

CNAME records are returned by `InitializeTrackingDomainSSL`.

They are required for SSL validation.

The user must add the exact returned CNAME records to DNS.

Important:

- Do not modify record names or values.
- DNS propagation can take time.
- DNS providers may display names differently depending on whether the root domain is automatically appended.
- If validation fails, verify that records were entered exactly as required.

---

# URL Parameters and Metadata

One of the most important tracking-domain features is capturing URL parameters and saving them as RevCent metadata.

Example landing page URL:

```text
https://example.com/?utm_source=google&utm_campaign=spring_sale&gclid=abc123&affiliate_id=aff_001
```

The tracking domain can save:

| URL Parameter | Metadata Name | Example Value |
|---|---|---|
| `utm_source` | `utm_source` | `google` |
| `utm_campaign` | `utm_campaign` | `spring_sale` |
| `gclid` | `gclid` | `abc123` |
| `affiliate_id` | `affiliate_id` | `aff_001` |

This metadata can later be used for:

- Reporting
- BigQuery queries
- Conversion analysis
- Affiliate attribution
- Campaign attribution
- Ad platform attribution
- Refund/chargeback analysis
- Customer segmentation
- AI Assistant workflows

---

## `url_parameters`

Tracking domains can include a manual `url_parameters` array.

Each item defines a URL parameter to capture and how it should be saved.

Fields:

| Field | Description |
|---|---|
| `url_parameter` | URL query parameter to capture, such as `utm_source`. |
| `metadata_name` | Name to save the value under in RevCent metadata. If empty, the URL parameter name is used. |
| `default_value` | Optional value to save instead of the actual URL value when the parameter is present. |
| `days` | Number of days to persist the parameter for the visitor. If omitted, default is 30 days. |

Example:

```json
{
  "url_parameter": "utm_source",
  "metadata_name": "utm_source",
  "days": 30
}
```

Example with renamed metadata:

```json
{
  "url_parameter": "utm_source",
  "metadata_name": "source",
  "days": 30
}
```

Example with default value:

```json
{
  "url_parameter": "utm_source",
  "metadata_name": "utm_source",
  "default_value": "organic",
  "days": 30
}
```

---

## Recommended URL Parameters to Track

Common ecommerce URL parameters:

| Parameter | Purpose |
|---|---|
| `utm_source` | Traffic source, such as google, facebook, email, affiliate. |
| `utm_medium` | Channel, such as cpc, social, email, organic. |
| `utm_campaign` | Campaign name. |
| `utm_content` | Ad creative, email variation, link variation. |
| `utm_term` | Keyword or search term. |
| `gclid` | Google Ads click ID. |
| `fbclid` | Facebook click ID. |
| `ttclid` | TikTok click ID. |
| `msclkid` | Microsoft Ads click ID. |
| `affiliate_id` | Affiliate or partner ID. |
| `sub_id` | Affiliate sub ID. |
| `sub_id_2` | Additional affiliate sub ID. |
| `click_id` | Generic click ID. |
| `campaign_id` | External campaign ID. |
| `ad_id` | Ad ID. |
| `adset_id` | Ad set ID. |
| `creative_id` | Creative ID. |
| `landing_page` | Landing page identifier. |

Recommended metadata names should usually match the URL parameter names unless the business has a strong reason to normalize them.

---

## Be Descriptive

URL parameters and metadata should be descriptive enough to support analysis later.

Poor:

```text
s=1
c=2
x=abc
```

Better:

```text
utm_source=google
utm_campaign=spring_sale
affiliate_id=aff_001
ad_id=123456
```

Descriptive metadata makes later reporting easier for both humans and AI.

---

# Conversion Details

Conversion tracking is designed to connect tracked visitors to resulting conversions.

Useful conversion detail categories include:

| Category | Meaning |
|---|---|
| Item details | The sale, customer, product sale, shipment, subscription, renewal, or related item associated with the conversion. |
| Conversion data | Information about the tracked conversion event. |
| References | Related IDs, visitor IDs, tracking IDs, or source references. |
| Metadata | Saved URL parameter values and business-specific attribution data. |
| AdWords / Google Ads details | Values such as `gclid` and related ad attribution data when available. |

---

# Google Ads / AdWords Tracking

Google Ads commonly uses the `gclid` parameter.

Example:

```text
https://example.com/?gclid=EAIaIQobChMI...
```

To preserve Google Ads attribution:

1. Ensure Google Ads auto-tagging is enabled.
2. Track the `gclid` URL parameter.
3. Save `gclid` as metadata, usually with metadata name `gclid`.
4. Ensure the visitor ID is passed into checkout/sale creation.
5. Use conversion reports or BigQuery to analyze sales by `gclid` or related campaign parameters.

---

# Reporting and BigQuery Use Cases

Tracking-domain metadata becomes especially valuable in reporting and BigQuery.

Examples:

```text
Revenue by utm_source
Revenue by affiliate_id
Refund rate by campaign_id
Chargeback count by traffic_source
Subscription renewal rate by landing_page
Trial conversion rate by ad_id
Average order value by utm_campaign
```

Because URL parameters are saved as metadata, users may ask for reporting using plain business terms without saying “metadata.”

Examples:

| User asks | Likely metadata |
|---|---|
| “Group revenue by affiliate.” | `affiliate_id`, `affiliate`, `partner_id` |
| “Show sales by traffic source.” | `utm_source`, `source`, `traffic_source` |
| “Which campaign converted best?” | `utm_campaign`, `campaign_id` |
| “Show Google Ads conversions.” | `gclid`, `utm_source`, `utm_campaign` |
| “Group by sub ID.” | `sub_id`, `subid`, `sub_1` |

MCP should use metadata-discovery operations, such as `GetMetadata` and `GetMetadataEntry`, when building BigQuery reports that group or filter by user-defined metadata.

---

# MCP Guidance for Tracking Domains

When a user asks about setting up conversion tracking, attribution, or DNS tracking, MCP should think in terms of:

1. Does the user already have a tracking domain?
2. Is the root domain correct?
3. Has DNS been configured?
4. Is SSL issued?
5. Is DNS tracking complete?
6. Is Track.js installed or plugin DNS tracking enabled?
7. Is the visitor ID being passed into conversion flows?
8. Are important URL parameters being saved as metadata?
9. Are URL parameter names descriptive?
10. Are reports using the correct metadata names?

---

## If the User Wants to Create Tracking

Recommended MCP flow:

1. Ask for the root domain, such as `example.com`.
2. Confirm the user owns the domain and can edit DNS.
3. Call `CreateTrackingDomain`.
4. Show the returned A records clearly.
5. Tell the user to add A records to DNS.
6. After A records are added, call `InitializeTrackingDomainSSL`.
7. Show returned CNAME records clearly.
8. Tell the user to add CNAME records to DNS.
9. After CNAME records are added and propagated, call `InitializeTrackingDomainDNS`.
10. Use `GetTrackingDomain` to verify:
    - `ssl.status = ISSUED`
    - `dns.status = COMPLETE`
11. Configure URL parameters.
12. Confirm Track.js / plugin implementation.
13. Confirm visitor ID is passed into checkout/sale creation.

---

## If the User Asks Why Conversions Are Not Tracking

Check:

- Tracking domain exists.
- Domain is root domain, not `www`.
- A records are present.
- SSL was initialized.
- CNAME records are present.
- SSL status is `ISSUED`.
- DNS status is `COMPLETE`.
- Track.js is installed on landing pages.
- WordPress plugin DNS tracking is enabled if using the plugin.
- Visitor ID is being passed to RevCent at checkout or sale creation.
- URL parameters are configured.
- User is testing with a fresh visitor/session.
- Ad click parameters are actually present in the landing URL.
- Browser or ad-blocker behavior is not interfering with testing.
- Purchases are occurring on a flow that preserves visitor ID.

---

## If the User Wants Better Attribution

Recommend:

- Track standard UTM parameters.
- Track ad click IDs such as `gclid`, `fbclid`, `ttclid`, and `msclkid`.
- Track affiliate IDs and sub IDs.
- Use descriptive metadata names.
- Use URL parameter sets when the same parameters apply to multiple domains.
- Use consistent naming across domains.
- Avoid renaming the same concept differently on different domains.
- Use BigQuery to report by metadata.
- Use `GetMetadata` before building metadata-based reports.

---

# Common Tracking Domain Mistakes

## Using a Subdomain Instead of Root Domain

Tracking domain `domain` should be the root domain, such as:

```text
example.com
```

Not:

```text
www.example.com
```

The schema states only requests from the root domain will be tracked and the domain cannot be changed after creation.

---

## Not Adding DNS Records

Creating a tracking domain is not enough.

The user must add:

1. A records from `CreateTrackingDomain` / `GetTrackingDomain`.
2. CNAME records from `InitializeTrackingDomainSSL`.

Then DNS must be initialized.

---

## Initializing DNS Before SSL Is Ready

DNS tracking cannot complete until SSL is issued.

If `dns.status = AWAITING_SSL`, check `ssl.status`.

---

## Not Passing Visitor ID

If the visitor ID is not passed into checkout/sale creation, RevCent may not be able to connect the purchase to the tracked visitor.

---

## Not Configuring URL Parameters

If URL parameters are not configured, RevCent may not save important attribution values as metadata.

---

## Using Inconsistent Metadata Names

For example:

```text
utm_source
source
traffic_source
trafficSource
```

may all mean the same thing, but inconsistent naming makes reporting harder.

Use consistent metadata names across tracking domains.

---

# Example Tracking Domain Setup

## Create Domain

```json
{
  "name": "Main Store Tracking",
  "description": "Tracks visitors and conversions for example.com.",
  "domain": "example.com"
}
```

## Add Returned A Records

Example shape:

```json
[
  {
    "name": "rctrk",
    "value": "..."
  },
  {
    "name": "portal",
    "value": "..."
  },
  {
    "name": "rcacp",
    "value": "..."
  }
]
```

## Initialize SSL

```json
{
  "tracking_domain_id": "XXXXXXXXXXXXXXXXXXXX"
}
```

## Add Returned CNAME Records

Example shape:

```json
[
  {
    "name": "...",
    "value": "..."
  }
]
```

## Initialize DNS

```json
{
  "tracking_domain_id": "XXXXXXXXXXXXXXXXXXXX"
}
```

## Confirm Status

Use `GetTrackingDomain` and verify:

```text
ssl.status = ISSUED
dns.status = COMPLETE
```

---

# Example URL Parameter Configuration

```json
{
  "url_parameters": [
    {
      "url_parameter": "utm_source",
      "metadata_name": "utm_source",
      "days": 30
    },
    {
      "url_parameter": "utm_campaign",
      "metadata_name": "utm_campaign",
      "days": 30
    },
    {
      "url_parameter": "gclid",
      "metadata_name": "gclid",
      "days": 30
    },
    {
      "url_parameter": "affiliate_id",
      "metadata_name": "affiliate_id",
      "days": 30
    }
  ]
}
```

---

# Best Practices

1. Use the root domain.
2. Confirm the user can edit DNS before creating the tracking domain.
3. Save and display all A and CNAME records clearly.
4. Do not modify DNS record values.
5. Wait for DNS propagation before troubleshooting.
6. Confirm SSL status before initializing DNS.
7. Configure URL parameters before running traffic.
8. Use descriptive URL parameters and metadata names.
9. Use URL parameter sets for shared tracking logic across domains.
10. Ensure visitor ID is passed into conversion/sale creation.
11. Test with real landing URLs containing URL parameters.
12. Confirm metadata is saved on visitor/conversion records.
13. Use BigQuery for attribution reporting.
14. Use `GetMetadata` and `GetMetadataEntry` when users ask for reports by affiliate, source, campaign, or other custom dimensions.
15. Document which metadata names are used for attribution.

---

# Quick Decision Guide

| User Goal | MCP Should Use |
|---|---|
| List tracking domains | `GetTrackingDomains` |
| Create tracking for a domain | `CreateTrackingDomain` |
| Retrieve DNS/SSL records | `GetTrackingDomain` |
| Start SSL setup | `InitializeTrackingDomainSSL` |
| Complete DNS setup | `InitializeTrackingDomainDNS` |
| Edit name/description/URL parameters | `EditTrackingDomain` |
| Diagnose missing attribution | Check DNS, SSL, Track.js, visitor ID, and URL parameter config |
| Report conversions by source/affiliate/campaign | BigQuery + metadata discovery |
| Track Google Ads conversions | Capture and save `gclid` metadata |
| Track affiliates | Capture affiliate/sub ID URL parameters as metadata |

---

# Summary

Tracking Domains are RevCent’s foundation for accurate ecommerce conversion tracking.

They use custom DNS, SSL, Track.js, visitor IDs, and URL-parameter metadata to connect visits to conversions.

For MCP usage, the most important concepts are:

- A tracking domain must be created for the root domain.
- DNS A records and SSL CNAME records must be added by the user.
- SSL must be issued before DNS tracking can be completed.
- DNS status should be `COMPLETE` before relying on tracking.
- Track.js or plugin DNS tracking must be installed/enabled.
- Visitor ID must be passed into conversion flows.
- URL parameters should be saved as metadata for reporting.
- Metadata powers attribution reporting in RevCent and BigQuery.


---
Document Parent Directory
* [Operations](https://revcent.com/documentation/markdown/mcp/operation/index.md) - AI/MCP details and overviews for operations available within the RevCent MCP.