# RevCent URL Parameter Set Overview for AI/MCP

AI/MCP-focused overview for URL Parameter Sets in RevCent.

This document explains what URL Parameter Sets are, why they exist, how they relate to Tracking Domains, how URL parameters become metadata, and how AI/MCP clients should create, edit, retrieve, and attach URL Parameter Sets for ecommerce attribution.

---

## Core Concept

A URL Parameter Set is a reusable collection of URL query parameters that RevCent should save for visitors and purchases through RevCent DNS tracking.

In plain language:

```text
URL Parameter Set = reusable list of URL parameters RevCent should capture as metadata
Tracking Domain = domain where RevCent DNS tracking occurs
Sale / Conversion = commerce event that can receive captured metadata
```

URL Parameter Sets make it easier to manage attribution parameters across one or more Tracking Domains.

Instead of manually adding the same URL parameters to each Tracking Domain, create a URL Parameter Set once and attach it to one or more Tracking Domains.

---

## Why URL Parameter Sets Matter

URL Parameter Sets help ecommerce businesses capture the source and lifecycle of a sale.

When a visitor lands on a tracked domain with URL parameters, RevCent can save those values and later attach them to visitor/purchase metadata.

Example:

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

RevCent can capture:

```text
utm_source = google
utm_campaign = spring_sale
gclid = abc123
```

This metadata can then support:

- sale origination analysis,
- campaign attribution,
- affiliate attribution,
- customer journey analysis,
- subscription acquisition reporting,
- refund analysis by source,
- chargeback analysis by traffic source,
- revenue by campaign,
- AI Assistant decisions,
- BigQuery reporting.

The purpose is to make reporting as granular as possible by capturing the original URL parameter context that drove the visitor and eventual conversion.

---

## Related Operation Links

| Operation / Overview | Link | Purpose |
|---|---|---|
| Tracking Domain Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewTrackingDomain.md` | Broad overview of DNS tracking, Tracking Domains, visitor tracking, metadata, attribution, WooCommerce tracking, and reporting. |
| CreateTrackingDomain | `https://revcent.com/documentation/markdown/mcp/operation/CreateTrackingDomain.md` | Creates a Tracking Domain and begins the DNS setup lifecycle. |
| EditTrackingDomain | `https://revcent.com/documentation/markdown/mcp/operation/EditTrackingDomain.md` | Associates URL Parameter Sets with a Tracking Domain via `url_parameter_sets`. |
| GetTrackingDomain | `https://revcent.com/documentation/markdown/mcp/operation/GetTrackingDomain.md` | Retrieves Tracking Domain details, including associated URL Parameter Sets. |
| GetUrlParameterSets |  | Lists URL Parameter Sets. |
| GetUrlParameterSet |  | Retrieves one URL Parameter Set by ID. |
| CreateUrlParameterSet | `https://revcent.com/documentation/markdown/mcp/operation/CreateUrlParameterSet.md` | Creates a reusable URL Parameter Set. |
| EditUrlParameterSet | `https://revcent.com/documentation/markdown/mcp/operation/EditUrlParameterSet.md` | Edits a URL Parameter Set. |
| BigQueryRunQuery | `https://revcent.com/documentation/markdown/mcp/operation/BigQueryRunQuery.md` | Correct method for attribution and metadata reporting. |

---

## URL Parameter Sets vs Tracking Domain `url_parameters`

Tracking Domains can have URL parameters configured in two ways:

| Method | Best Use |
|---|---|
| URL Parameter Sets | Preferred. Reusable, organized, and can apply across multiple Tracking Domains. |
| Tracking Domain `url_parameters` | Legacy/manual domain-specific parameters for a single Tracking Domain only. |

Recommended rule:

```text
Use URL Parameter Sets whenever parameters should be reused, organized, or applied consistently.
Use direct Tracking Domain url_parameters only for one-off domain-specific parameters.
```

Why URL Parameter Sets are preferred:

- reusable across multiple Tracking Domains,
- easier to maintain,
- consistent metadata naming,
- avoids duplicate setup,
- easier for AI/MCP to reason about,
- safer for long-term attribution reporting.

---

## How URL Parameter Sets Attach to Tracking Domains

A URL Parameter Set is created independently.

Then it is associated with a Tracking Domain using:

```text
EditTrackingDomain.url_parameter_sets
```

Conceptual flow:

```text
CreateUrlParameterSet
    ↓
Get returned url_parameter_set_id
    ↓
EditTrackingDomain with url_parameter_sets array
    ↓
Tracking Domain begins using that set for future visitor URL parameter capture
```

Example:

```json
{
  "tracking_domain_id": "TTTTTTTTTTTTTTTTTTTT",
  "url_parameter_sets": [
    "PPPPPPPPPPPPPPPPPPPP"
  ]
}
```

Important:

```text
Creating a URL Parameter Set does not automatically attach it to a Tracking Domain.
```

The set must be associated with the Tracking Domain before it affects that domain's tracking behavior.

---

## URL Parameter Set Object

A URL Parameter Set can include:

| Field | Meaning |
|---|---|
| `id` | 20-character URL Parameter Set ID. |
| `name` | URL Parameter Set name. |
| `description` | URL Parameter Set description. |
| `enabled` | Whether the set is enabled. |
| `url_parameters` | Parameters RevCent should capture and save as metadata. |
| `created_date_unix` | Creation timestamp. |
| `updated_date_unix` | Last updated timestamp. |

---

## URL Parameter Item Schema

Each item in `url_parameters` can include:

| Field | Type | Purpose |
|---|---:|---|
| `url_parameter` | string | Query parameter to capture from the URL. |
| `metadata_name` | string | Metadata name to save the value as. Recommended empty or same as `url_parameter`. |
| `default_value` | string | Optional fixed value to save instead of the URL value when the parameter is present. Recommended empty. |
| `days` | integer | Number of days to persist the value for the visitor. Defaults to 30 if omitted. Recommended 30. |

---

## `url_parameter`

`url_parameter` is the query parameter RevCent should detect in the visitor URL.

Examples:

```text
utm_source
utm_medium
utm_campaign
utm_content
utm_term
gclid
fbclid
ttclid
msclkid
affiliate_id
sub_id
click_id
ad_id
adset_id
creative_id
```

Example:

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

If a visitor lands on:

```text
https://example.com/?utm_source=google
```

RevCent can save:

```text
utm_source = google
```

---

## `metadata_name`

`metadata_name` controls the metadata key RevCent uses when saving the URL parameter value.

Recommended:

```text
Leave metadata_name empty or set it to the same value as url_parameter.
```

Example:

```json
{
  "url_parameter": "utm_campaign",
  "metadata_name": "utm_campaign"
}
```

If `metadata_name` is empty, RevCent saves the value using the URL parameter name.

Example:

```text
url_parameter = utm_source
metadata_name = empty
saved metadata name = utm_source
```

Use a different `metadata_name` only when intentionally normalizing metadata names.

Example:

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

This saves:

```text
source = google
```

instead of:

```text
utm_source = google
```

Be careful changing metadata names because reporting and AI workflows may depend on consistent keys.

---

## `default_value`

`default_value` is optional.

It tells RevCent to save a fixed value instead of the actual URL value when the parameter is present.

Example:

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

If the URL contains:

```text
?utm_source=anything
```

RevCent saves:

```text
utm_source = organic
```

Recommended:

```text
Leave default_value empty unless there is a specific business reason to override the actual URL value.
```

Most ecommerce attribution should preserve the real URL value.

---

## `days`

`days` controls how long the URL parameter value is saved for a visitor.

If omitted:

```text
RevCent uses the default value of 30 days.
```

Recommended:

```text
30
```

Use a different value only when the business has a clear attribution-window reason.

Examples:

| Days | Use Case |
|---:|---|
| 7 | Short attribution window. |
| 30 | Standard/recommended attribution window. |
| 60 | Longer consideration period. |
| 90 | Long-cycle campaign attribution. |

---

## Recommended Ecommerce URL Parameter Set

A common ecommerce URL Parameter Set might include:

```json
{
  "name": "Standard Ecommerce Attribution Parameters",
  "description": "Captures common UTM, ad click, affiliate, and campaign parameters for RevCent DNS tracking and sale attribution.",
  "enabled": true,
  "url_parameters": [
    { "url_parameter": "utm_source", "metadata_name": "utm_source", "days": 30 },
    { "url_parameter": "utm_medium", "metadata_name": "utm_medium", "days": 30 },
    { "url_parameter": "utm_campaign", "metadata_name": "utm_campaign", "days": 30 },
    { "url_parameter": "utm_content", "metadata_name": "utm_content", "days": 30 },
    { "url_parameter": "utm_term", "metadata_name": "utm_term", "days": 30 },
    { "url_parameter": "gclid", "metadata_name": "gclid", "days": 30 },
    { "url_parameter": "fbclid", "metadata_name": "fbclid", "days": 30 },
    { "url_parameter": "ttclid", "metadata_name": "ttclid", "days": 30 },
    { "url_parameter": "msclkid", "metadata_name": "msclkid", "days": 30 },
    { "url_parameter": "affiliate_id", "metadata_name": "affiliate_id", "days": 30 },
    { "url_parameter": "sub_id", "metadata_name": "sub_id", "days": 30 },
    { "url_parameter": "click_id", "metadata_name": "click_id", "days": 30 }
  ]
}
```

AI/MCP should customize this list based on the user's actual traffic sources and affiliate/ad platforms.

---

## WooCommerce / User Shop Guidance

For WooCommerce/User Shops, URL Parameter Sets are especially useful because they allow RevCent DNS tracking to capture the store's acquisition and attribution parameters.

Recommended flow:

```text
WooCommerce store has Tracking Domain DNS-complete
    ↓
URL Parameter Set is attached to that Tracking Domain
    ↓
Visitor lands with UTM/ad/affiliate parameters
    ↓
RevCent stores URL parameter values as metadata
    ↓
A Sale can later include origination metadata and lifecycle attribution
```

This gives ecommerce businesses more granular reporting than relying on a basic cart/order record.

---

## Reporting With BigQuery

Do not use URL Parameter Set operations for reporting.

Use:

```text
BigQueryRunQuery
```

for reports such as:

- revenue by `utm_source`,
- revenue by `utm_campaign`,
- subscriptions by original traffic source,
- refunds by affiliate ID,
- chargebacks by campaign,
- customer lifetime value by click ID,
- WooCommerce Sales by ad click ID,
- trial conversion by source,
- subscription renewal revenue by original acquisition metadata.

URL Parameter Sets define future metadata capture. BigQuery reports on captured metadata.

---

## Operational Retrieval

Use:

```text
GetUrlParameterSets
```

to list URL Parameter Sets.

Required input:

| Field | Purpose |
|---|---|
| `limit` | Number of objects to return. Range 1 to 25. |
| `page` | Pagination page. |

Use:

```text
GetUrlParameterSet
```

to retrieve one URL Parameter Set by ID.

Required input:

| Field | Purpose |
|---|---|
| `url_parameter_set_id` | 20-character URL Parameter Set ID. |

---

## Setup Workflow

Recommended AI/MCP workflow:

```text
1. Ask what traffic sources and ad/affiliate platforms should be tracked.
2. Build a URL parameter list.
3. Use descriptive metadata names.
4. Use days = 30 unless the user has a reason to change attribution window.
5. CreateUrlParameterSet.
6. Store returned url_parameter_set_id.
7. Attach the set to Tracking Domain(s) using EditTrackingDomain.url_parameter_sets.
8. Verify with GetTrackingDomain.
9. Test visitor URLs with parameters.
10. Confirm metadata appears on resulting visitor/sale/conversion records.
11. Use BigQuery for reporting.
```

---

## Best Practices

1. Use URL Parameter Sets instead of per-domain `url_parameters` whenever possible.
2. Use clear names and descriptions.
3. Capture common UTM parameters.
4. Capture ad click IDs used by the merchant's ad platforms.
5. Capture affiliate/sub IDs if affiliate traffic exists.
6. Keep `metadata_name` empty or the same as `url_parameter` unless normalization is intentional.
7. Avoid `default_value` unless overriding real URL values is intentional.
8. Use `days = 30` unless a different attribution window is required.
9. Attach the URL Parameter Set to Tracking Domain(s) after creation.
10. Use `GetTrackingDomain` to verify the association.
11. Use BigQuery for reporting.
12. Be careful changing metadata names because reports/workflows may depend on them.

---

## Common Mistakes to Avoid

Do not:

- create a URL Parameter Set but forget to attach it to a Tracking Domain,
- use vague parameter names,
- change metadata names without considering reports,
- use `default_value` and accidentally overwrite real attribution values,
- assume historical metadata is rewritten after editing a set,
- send an empty `url_parameters` array in edit unless intentionally removing all parameters,
- use URL Parameter Set operations for reporting,
- rely on WooCommerce alone for attribution when RevCent DNS tracking is available,
- duplicate the same parameters across many Tracking Domains instead of using a reusable set.

---

## AI/MCP Decision Guide

| User Intent | Correct Action |
|---|---|
| Create reusable attribution parameters | Use `CreateUrlParameterSet`. |
| Edit existing parameter set | Use `EditUrlParameterSet`. |
| Retrieve one set | Use `GetUrlParameterSet`. |
| List sets | Use `GetUrlParameterSets`. |
| Attach set to a Tracking Domain | Use `EditTrackingDomain.url_parameter_sets`. |
| Check attached sets | Use `GetTrackingDomain`. |
| Track one-off domain-specific parameter | Use Tracking Domain `url_parameters` only if URL Parameter Set is not appropriate. |
| Report on captured metadata | Use `BigQueryRunQuery`. |

---

## Final AI/MCP Instruction

URL Parameter Sets are reusable RevCent tracking configurations that define which URL query parameters should be saved as metadata for visitors and purchases.

Create URL Parameter Sets for attribution parameters such as UTM values, click IDs, affiliate IDs, and campaign IDs. Attach them to Tracking Domains with `EditTrackingDomain.url_parameter_sets`. Prefer URL Parameter Sets over domain-specific `url_parameters` for better consistency and maintainability.

URL Parameter Sets affect future metadata capture. Use BigQuery to report on the metadata captured from those parameters.


---
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.