# RevCent MCP Guide: `CreateUrlParameterSet`

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

This document explains the `CreateUrlParameterSet` operation, its schema, recommended URL parameter configuration, and how to attach the created set to Tracking Domains.

---

## Related Documentation

| Operation / Overview | Link | Why It Matters |
|---|---|---|
| URL Parameter Set Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewUrlParameterSet.md` | Broad explanation of URL Parameter Sets and attribution metadata. |
| Tracking Domain Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewTrackingDomain.md` | Explains DNS tracking, metadata capture, and sale attribution. |
| CreateTrackingDomain | `https://revcent.com/documentation/markdown/mcp/operation/CreateTrackingDomain.md` | Creates the Tracking Domain that can later use URL Parameter Sets. |
| EditTrackingDomain | `https://revcent.com/documentation/markdown/mcp/operation/EditTrackingDomain.md` | Used to attach URL Parameter Sets to Tracking Domains. |
| GetTrackingDomain | `https://revcent.com/documentation/markdown/mcp/operation/GetTrackingDomain.md` | Used to verify URL Parameter Set associations. |
| GetUrlParameterSets |  | Lists existing URL Parameter Sets to avoid duplication. |
| GetUrlParameterSet |  | Retrieves a specific URL Parameter Set. |

---

## Operation Summary

Operation:

```text
CreateUrlParameterSet
```

Title:

```text
Create A URL Parameter Set
```

Purpose:

```text
Create a URL Parameter Set, which will issue a unique URL Parameter Set ID.
```

A URL Parameter Set defines URL query parameters that RevCent should save for visitors and purchases through RevCent DNS tracking.

After creation, the returned `url_parameter_set_id` can be associated with Tracking Domains using:

```text
EditTrackingDomain.url_parameter_sets
```

---

## Important Concept

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

Correct flow:

```text
CreateUrlParameterSet
    ↓
Receive url_parameter_set_id
    ↓
EditTrackingDomain with url_parameter_sets
    ↓
Tracking Domain starts using the set for future visitor metadata capture
```

---

## Input Schema

`CreateUrlParameterSet` input schema:

```text
type: object
additionalProperties: false
required:
  - name
```

Only send supported fields.

---

## Required Field

| Field | Type | Required | Description |
|---|---:|---:|---|
| `name` | string | Yes | URL Parameter Set name. Must be unique from other URL Parameter Sets. |

---

## Optional Fields

| Field | Type | Description |
|---|---:|---|
| `description` | string | Human-readable description. |
| `enabled` | boolean | Whether the URL Parameter Set is enabled. |
| `url_parameters` | array[object] | URL parameters RevCent should save as metadata. |

---

## Output Schema

Successful output can include:

| Field | Type | Description |
|---|---:|---|
| `api_call_id` | string | 20-character API call ID. |
| `api_call_unix` | integer | Unix timestamp when the API call was initiated. |
| `code` | integer | API response code. `1` indicates success. |
| `url_parameter_set_id` | string | 20-character URL Parameter Set ID. |
| `result` | string | Result message. |

Store the returned:

```text
url_parameter_set_id
```

It is needed to attach the set to Tracking Domains.

---

## `url_parameters` Schema

Each object inside `url_parameters` can include:

| Field | Type | Purpose |
|---|---:|---|
| `url_parameter` | string | Query parameter to capture, such as `utm_source`. |
| `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 when the parameter is present. Recommended empty. |
| `days` | integer | Number of days to persist the value for a visitor. Defaults to 30. Recommended 30. |

---

## Field: `url_parameter`

The URL query parameter RevCent should capture.

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

---

## Field: `metadata_name`

The metadata key used when saving the parameter value.

Recommended:

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

Example:

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

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

Use different metadata names only when intentionally normalizing metadata.

---

## Field: `default_value`

Optional.

Use `default_value` only when the URL parameter is present but RevCent should save a fixed value instead of the URL value.

Recommended:

```text
Leave default_value empty.
```

Example of intentional override:

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

Be careful: this discards the real URL value for that parameter.

---

## Field: `days`

Optional.

Controls how long RevCent saves the URL parameter value for a visitor.

If omitted:

```text
RevCent uses 30 days.
```

Recommended:

```text
30
```

---

## Recommended Ecommerce Parameters

Common ecommerce attribution parameters:

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

AI/MCP should ask what platforms the business uses and tailor the list.

Examples:

| Platform / Source | Parameters |
|---|---|
| Google Ads | `gclid`, `utm_source`, `utm_campaign`, `utm_medium` |
| Meta/Facebook | `fbclid`, `utm_source`, `utm_campaign`, `utm_content` |
| TikTok | `ttclid`, `utm_source`, `utm_campaign` |
| Microsoft Ads | `msclkid`, `utm_source`, `utm_campaign` |
| Affiliates | `affiliate_id`, `sub_id`, `click_id` |
| Email | `utm_source`, `utm_medium`, `utm_campaign`, `utm_content` |

---

## Example Request: Standard Ecommerce Attribution

```json
{
  "name": "Standard Ecommerce Attribution Parameters",
  "description": "Captures UTM, click ID, campaign, and affiliate 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": "gclid",
      "metadata_name": "gclid",
      "days": 30
    },
    {
      "url_parameter": "fbclid",
      "metadata_name": "fbclid",
      "days": 30
    },
    {
      "url_parameter": "affiliate_id",
      "metadata_name": "affiliate_id",
      "days": 30
    },
    {
      "url_parameter": "sub_id",
      "metadata_name": "sub_id",
      "days": 30
    }
  ]
}
```

---

## Example Request: Minimal

```json
{
  "name": "Basic UTM Parameters",
  "enabled": true,
  "url_parameters": [
    {
      "url_parameter": "utm_source",
      "metadata_name": "utm_source",
      "days": 30
    },
    {
      "url_parameter": "utm_campaign",
      "metadata_name": "utm_campaign",
      "days": 30
    }
  ]
}
```

---

## Attaching the Created Set to a Tracking Domain

After creation, use the returned URL Parameter Set ID in:

```text
EditTrackingDomain.url_parameter_sets
```

Example:

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

Important:

```text
If the Tracking Domain already has URL Parameter Sets attached, include all sets that should remain attached.
```

Do not accidentally replace existing Tracking Domain associations with only the newly created set unless that is intended.

---

## Recommended Workflow

```text
1. Ask which traffic sources/ad platforms/affiliate networks the merchant uses.
2. Build the URL parameter list.
3. Check existing URL Parameter Sets with GetUrlParameterSets to avoid duplicates.
4. CreateUrlParameterSet.
5. Store returned url_parameter_set_id.
6. Attach the set to Tracking Domain(s) with EditTrackingDomain.
7. Verify with GetTrackingDomain.
8. Test a visitor URL containing configured parameters.
9. Verify metadata attaches to future visitor/purchase records.
10. Use BigQuery for reporting.
```

---

## Best Practices

1. Use a clear unique name.
2. Include a meaningful description.
3. Set `enabled = true` when ready for use.
4. Capture common UTM parameters.
5. Capture ad platform click IDs used by the merchant.
6. Capture affiliate IDs and sub IDs when affiliate traffic exists.
7. Keep `metadata_name` empty or identical to `url_parameter` unless normalization is intentional.
8. Leave `default_value` empty unless overriding the real URL value is intentional.
9. Use `days = 30` unless the attribution window should differ.
10. Attach the set to Tracking Domains after creation.
11. Verify associations with `GetTrackingDomain`.
12. Use BigQuery for reporting.

---

## Common Mistakes to Avoid

Do not:

- forget that `name` is required,
- use a duplicate or vague name,
- create the set but forget to attach it to a Tracking Domain,
- use `default_value` unintentionally,
- rename metadata keys in ways that break reports,
- omit important ad click IDs,
- create multiple duplicate sets for the same standard parameters,
- use URL Parameter Set operations for reporting,
- assume historical metadata is created retroactively.

---

## AI/MCP Decision Guide

| User Intent | Correct Action |
|---|---|
| Create reusable URL parameters | Use `CreateUrlParameterSet`. |
| Avoid duplicates | Check `GetUrlParameterSets` first. |
| Attach set to a domain | Use `EditTrackingDomain.url_parameter_sets`. |
| Verify attachment | Use `GetTrackingDomain`. |
| Track one-off domain-specific parameter | Consider Tracking Domain `url_parameters`, but prefer URL Parameter Sets. |
| Report on values captured | Use `BigQueryRunQuery`. |

---

## Final AI/MCP Instruction

Use `CreateUrlParameterSet` to create reusable sets of URL query parameters that RevCent should capture as metadata through DNS tracking.

The operation requires `name`. Add useful `url_parameters`, keep metadata naming consistent, use `days = 30` unless there is a reason to change it, and avoid `default_value` unless overriding real URL values is intentional.

After creation, attach the returned `url_parameter_set_id` to Tracking Domains using `EditTrackingDomain.url_parameter_sets`.


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