# RevCent Metadata Overview This document explains metadata in RevCent at a broad level: what it is, how it works, why it matters, caveats to understand, and how ecommerce businesses can use metadata for attribution, search, reporting, conversion tracking, segmentation, BigQuery analysis, and automation. This is not an operation-specific guide. It is an overview of metadata as a RevCent capability. Sources: - RevCent Metadata operation schemas: `GetMetadata`, `GetMetadataEntry`, `InsertMetadata` - RevCent BigQuery operation guidance: `BigQueryRunQuery`, `GetBigQueryTables` - RevCent Tracking Domain overview: `OverviewTrackingDomain` - RevCent Tracking Domain operation schemas --- # What Is Metadata in RevCent? Metadata is custom name/value data attached to RevCent records. A metadata entry is conceptually: ```json { "name": "source", "value": "facebook" } ``` or: ```json { "name": "checkout_page", "value": "version_b" } ``` Metadata lets a business store custom context that is not necessarily a standard RevCent schema field. For example, a sale may have built-in fields such as: ```text customer_id email amount created_date_unix gateway status ``` but the business may also want custom context such as: ```text affiliate_id email_version facebook_post_id instagram_post checkout_page landing_page funnel_step utm_campaign ``` That custom context is where metadata becomes valuable. --- # Metadata Is Name/Value Context Metadata is usually best understood as: ```text metadata name = custom dimension metadata value = specific segment/value for that dimension ``` Examples: | Metadata Name | Metadata Value | Meaning | |---|---|---| | `source` | `facebook` | The sale/customer came from Facebook. | | `affiliate_id` | `partner_123` | The sale is attributed to affiliate partner_123. | | `checkout_page` | `version_b` | The customer used checkout page version B. | | `email_version` | `welcome_v3` | The sale came from a specific email variation. | | `facebook_post_id` | `post_987654` | The sale came from a specific Facebook post. | | `instagram_post` | `spring_reel_02` | The sale came from a specific Instagram reel/post. | | `landing_page` | `longform_a` | The customer landed on a specific landing page. | | `coupon_code` | `spring10` | The sale used a specific coupon. | This gives ecommerce businesses the ability to ask and answer more detailed questions than standard fields alone can support. --- # Metadata Can Be Anything Metadata names and values can literally be any custom business context the account chooses to store. Metadata is not limited to advertising. Advertising examples: ```text utm_source utm_campaign ad_id adset_id gclid fbclid affiliate_id click_id ``` Content and social examples: ```text facebook_post facebook_post_id instagram_post instagram_story tiktok_video youtube_video influencer_post ``` Email examples: ```text email_version email_subject_variant email_link email_segment newsletter_issue ``` Funnel and checkout examples: ```text landing_page checkout_page checkout_version funnel_name funnel_step upsell_page product_quiz_answer ``` Internal business examples: ```text call_center_batch support_agent internal_experiment webinar_id sms_campaign shipping_promo offer_version ``` The value of metadata is that it lets the business define its own dimensions for analysis, search, and automation. --- # Metadata vs Standard Schema Fields Metadata should be used for custom business context. It should not replace obvious standard schema fields. Examples of standard schema fields: ```text customer first name customer last name email phone state postal code transaction ID gateway ID sale amount approval status created date subscription status ``` If a user asks: ```text Find customers named Sarah. ``` that should use customer/search fields, not metadata. If a user asks: ```text Run a report on sales by customer home state. ``` that should generally use the customer/sale address state field, not metadata, because state is a normal schema property. But if a user asks: ```text Show sales by affiliate. ``` that may be metadata, such as: ```text affiliate_id = partner_123 ``` If a user asks: ```text How did page B perform? ``` that may be metadata, such as: ```text checkout_page = version_b ``` MCP/AI should use this decision rule: ```text If the requested dimension is an obvious schema field, use the schema field. If the requested dimension is custom, ambiguous, or not obviously in the schema, inspect metadata. If unsure, inspect both GetBigQueryTables and the metadata index. ``` --- # Metadata Index: Names and Values RevCent exposes metadata discovery through two key retrieval concepts: ```text GetMetadata GetMetadataEntry ``` ## GetMetadata `GetMetadata` returns metadata names/index entries. It tells MCP/AI which metadata names exist. Example metadata names: ```text source campaign affiliate_id checkout_page email_version facebook_post_id ``` Important: ```text GetMetadata returns metadata names. GetMetadata does not return values. ``` ## GetMetadataEntry `GetMetadataEntry` retrieves one metadata entry by metadata ID and returns values for that metadata name. Example: ```text metadata name = checkout_page values = version_a, version_b, version_c ``` Important: ```text GetMetadataEntry returns a maximum of 500 unique values. ``` This makes it useful for discovery and validation, but not a full export of every possible value when the metadata is high-cardinality. --- --- # InsertMetadata: Adding Metadata to Specific Items `InsertMetadata` is the operation used to add one or more metadata name/value pairs to a specific RevCent item. This is the write-side counterpart to metadata discovery: ```text InsertMetadata = add metadata to a specific item. GetMetadata = discover metadata names. GetMetadataEntry = discover values for one metadata name. BigQueryRunQuery = report/analyze using metadata. Search operations = find individual records that may include metadata. ``` A metadata insert is conceptually: ```json { "item_type": "sale", "item_id": "XXXXXXXXXXXXXXXXXXXX", "metadata": [ { "name": "checkout_page", "value": "version_b" }, { "name": "email_version", "value": "abandoned_cart_v3" } ] } ``` This allows MCP clients, AI workflows, Functions, AI Voice Agents, AI Assistants, direct API clients, and external systems to attach custom context to specific RevCent records. --- ## Supported Item Types `InsertMetadata` supports metadata insertion on these item types: ```text customer sale product_sale shipping subscription subscription_renewal salvage_transaction chargeback fraud_detection ``` Examples: ```text Insert call outcome metadata on a customer. Insert checkout variant metadata on a sale. Insert external sync status metadata on a shipping item. Insert renewal salvage result metadata on a subscription_renewal. Insert chargeback evidence status metadata on a chargeback. Insert automated risk review metadata on a fraud_detection item. ``` --- ## Required InsertMetadata Inputs `InsertMetadata` requires: | Field | Purpose | |---|---| | `item_type` | The type of item receiving metadata. | | `item_id` | The 20-character ID of the item receiving metadata. | | `metadata` | An array of metadata name/value pairs. | Each metadata object requires: ```text name value ``` Example: ```json { "name": "ai_assistant_outcome", "value": "refund_policy_explained" } ``` --- ## Cascade Behavior `InsertMetadata` also supports an optional `cascade` boolean. Default: ```text cascade = false ``` When `cascade = true`, metadata may be inserted into related sub-items. Example: ```text If inserting metadata on a sale, related shipping, subscriptions, and other sale-related items may also receive that metadata. ``` Important: ```text Metadata will always be inserted to a related customer record regardless of cascade value. ``` This matters because inserting metadata onto a sale, subscription, renewal, salvage transaction, chargeback, or other customer-related item may also make that metadata available on the customer record. Use `cascade = true` only when the metadata logically applies to related sub-items. Good cascade examples: ```text campaign_batch = spring_2026_test_b checkout_page = version_b source = facebook affiliate_id = partner_123 ``` Poor cascade examples: ```text shipping_label_printed = true chargeback_evidence_status = document_created fraud_review_result = suspicious_but_allowed ``` Those may be better applied only to the specific item they describe. --- # Who Can Insert Metadata? Metadata can be inserted through several paths in RevCent. These paths are important because metadata is not only a tracking feature. It is also an automation, AI, reporting, state, and operational outcome feature. --- ## MCP Clients Can Insert Metadata Directly MCP clients can call the `InsertMetadata` operation directly. This is appropriate when the MCP client already knows: ```text item_type item_id metadata name/value pairs whether cascade should be true or false ``` Example MCP/API request: ```json { "item_type": "sale", "item_id": "XXXXXXXXXXXXXXXXXXXX", "metadata": [ { "name": "mcp_outcome", "value": "metadata_inserted_by_mcp" }, { "name": "automation_source", "value": "revcent_mcp" } ], "cascade": false } ``` MCP can use `InsertMetadata` to: ```text Mark an item as processed. Save a parsed result from a user request. Tag a sale/customer/subscription for later reporting. Add an automation outcome after running another operation. Save a routing or workflow decision. Add metadata before or after triggering an AI Assistant, AI Voice Agent, or Function. ``` MCP does not need to route metadata insertion through an AI Assistant, AI Voice Agent, or Function when it already has the correct item context and user authorization. --- ## AI Assistants Can Insert Metadata With a System Action AI Assistants have access to the `InsertMetadata` system action. This means an AI Assistant can insert metadata inside an assistant step when it determines that a conversation, decision, parse result, or workflow outcome should be saved to a RevCent item. Examples: ```text An AI Assistant determines the customer asked about refunds. An AI Assistant parses the customer intent as interested in subscription. An AI Assistant decides the issue should be escalated. An AI Assistant completes a workflow step and marks the item. ``` Example: ```json { "item_type": "customer", "item_id": "XXXXXXXXXXXXXXXXXXXX", "metadata": [ { "name": "ai_assistant_outcome", "value": "refund_question_detected" }, { "name": "ai_assistant_next_action", "value": "escalate_to_support" } ] } ``` This turns AI Assistant conversation results into durable RevCent data that can be used later by search, BigQuery, Functions, customer groups, support teams, or other AI workflows. --- ## AI Voice Agents Can Insert Metadata During Voice Calls AI Voice Agents have access to the `InsertMetadata` system action. This means a voice agent can insert metadata during or after a voice call when it determines a call outcome, customer intent, callback request, objection, salvage result, or next action. Examples: ```text The customer requested a callback. The customer said they will retry payment tomorrow. The customer gave a decline reason. The customer asked to cancel. The customer showed interest in a subscription. The voice agent determined the call should not be retried. ``` Example: ```json { "item_type": "salvage_transaction", "item_id": "XXXXXXXXXXXXXXXXXXXX", "metadata": [ { "name": "ai_voice_outcome", "value": "retry_after_payday" }, { "name": "ai_voice_next_action", "value": "follow_up_later" } ] } ``` Callback example: ```json { "item_type": "customer", "item_id": "XXXXXXXXXXXXXXXXXXXX", "metadata": [ { "name": "ai_voice_outcome", "value": "callback_requested" }, { "name": "ai_voice_callback_window", "value": "tomorrow_afternoon" } ] } ``` This makes voice-call outcomes searchable, reportable, and usable in follow-up automation. --- ## Functions Can Insert Metadata as Part of Automation Functions can use `InsertMetadata` as part of event-driven, scheduled, filter, pre-agent, or API-direct automation when the Function needs to write an outcome back to a RevCent item. Examples: ```text A Function marks a sale as reviewed. A Function marks a shipping item as synced to a warehouse. A Function marks a subscription renewal as requiring manual review. A Function marks a fraud detection as passed/failed. A Function records an external API sync result. ``` Example: ```json { "item_type": "subscription_renewal", "item_id": "XXXXXXXXXXXXXXXXXXXX", "metadata": [ { "name": "function_processed", "value": "renewal_review_v1" }, { "name": "renewal_review_result", "value": "manual_review" } ] } ``` This is useful for idempotency, workflow state, reporting, and later search. --- ## Direct API Calls and External Agents Can Insert Metadata External systems can also use direct API calls to insert metadata. Examples: ```text A custom checkout inserts checkout_page = version_b. A CRM inserts crm_segment = vip_repeat_customer. An external AI agent inserts risk_classification = medium_risk. A warehouse system inserts external_sync_status = sent_to_warehouse. A chargeback mitigation tool inserts chargeback_evidence_status = document_created. ``` Direct API insertion is useful when an external system has context that should be saved on the relevant RevCent item. --- # InsertMetadata Use Cases ## AI Outcome Tracking ```text ai_assistant_outcome = refund_policy_explained ai_voice_outcome = callback_requested ai_voice_salvage_result = customer_will_retry_payment ``` Use this to track what AI workflows actually did. ## Parsed Conversation Results ```text parsed_customer_intent = wants_discount parsed_sentiment = neutral parsed_next_action = send_coupon_offer ``` Use this to turn unstructured conversations into structured data. ## Workflow State ```text support_workflow_step = awaiting_customer_reply renewal_route_decision = manual_review function_processed = fraud_review_v2 ``` Use this to let later automation or human teams continue from the correct step. ## Attribution and Experiments ```text checkout_page = version_b email_version = abandoned_cart_v3 instagram_post = spring_reel_02 facebook_post_id = post_987654 ``` Use this for granular ecommerce reporting and optimization. ## Chargeback and Risk Operations ```text chargeback_evidence_status = document_created fraud_review_result = passed_review external_ai_risk_classification = medium_risk ``` Use this for compliance, support, reporting, and operational follow-up. --- # InsertMetadata Safety and Quality Rules Metadata is most valuable when names and values are controlled and consistent. MCP, AI Assistants, AI Voice Agents, Functions, and external systems should follow these rules: 1. Insert metadata only when the target `item_type` and `item_id` are known. 2. Use descriptive metadata names. 3. Use consistent values. 4. Prefer lowercase snake_case values for report-friendly outcomes. 5. Do not insert secrets, API keys, credentials, or raw payment data as metadata. 6. Do not use metadata to replace a standard schema field. 7. Use Key Values for account-wide configuration; use metadata for item-specific context. 8. Use `cascade = true` only when the metadata should apply to related sub-items. 9. Remember related customer metadata behavior. 10. Avoid creating multiple near-duplicate metadata names for the same concept. 11. Prefer names and values that will be useful for future search, BigQuery, customer groups, Functions, AI Assistants, AI Voice Agents, or human review. --- # InsertMetadata and Later Analysis Inserted metadata becomes useful because it can later be discovered and analyzed. After metadata is inserted: ```text GetMetadata can discover the metadata name. GetMetadataEntry can show values for that metadata name. Search operations may surface records containing the metadata. BigQueryRunQuery can analyze revenue, counts, chargebacks, refunds, and outcomes by metadata. Customer groups can segment customers based on metadata. Functions and AI workflows can make later decisions from metadata. ``` Example reporting questions: ```text What was recovery rate by ai_voice_outcome? How much revenue came from checkout_page = version_b? Which ai_assistant_outcome led to the most retained customers? How many chargebacks have chargeback_evidence_status = document_created? Which external_ai_risk_classification produced the most refunds? ``` `InsertMetadata` is what allows AI and automation outcomes to become queryable business data. # Why Metadata Matters for Ecommerce Metadata helps ecommerce businesses understand what is actually driving revenue, declines, refunds, subscriptions, renewals, chargebacks, and customer behavior. Without metadata, a business may know: ```text We had 500 sales. ``` With metadata, a business can ask: ```text Which affiliate drove the sales? Which checkout page converted best? Which email version produced the most revenue? Which Instagram post created the highest lifetime value customers? Which campaign produced the most refunds? Which landing page produced the most chargebacks? Which traffic source produced the best subscription renewal rate? Which funnel version produced the lowest decline rate? ``` Metadata turns raw activity into business intelligence. --- # Conversion Tracking and Metadata Conversion tracking connects visitor activity to later purchases or conversions. RevCent tracking can capture URL parameters, associate them with a tracked visitor, and later attach the resulting metadata to the conversion/sale when the visitor becomes a buyer. Conceptual flow: ```text Visitor lands on site with URL parameters ↓ RevCent tracking identifies visitor ↓ Tracking domain captures configured URL parameters ↓ RevCent saves those parameters as metadata ↓ Visitor continues through site/checkout ↓ Sale or conversion occurs ↓ Sale can be associated with visitor and metadata ↓ Reporting can analyze conversion performance by metadata ``` Example landing page URL: ```text https://example.com/?utm_source=facebook&utm_campaign=spring_sale&affiliate_id=partner_123&checkout_page=version_b ``` Potential saved metadata: ```json [ { "name": "utm_source", "value": "facebook" }, { "name": "utm_campaign", "value": "spring_sale" }, { "name": "affiliate_id", "value": "partner_123" }, { "name": "checkout_page", "value": "version_b" } ] ``` This metadata can later power reports like: ```text Revenue by utm_source Sales by affiliate_id Declines by checkout_page Chargebacks by utm_campaign Subscription renewals by original campaign ``` --- # DNS Tracking and RevCent Internal Tracking RevCent Tracking Domains use DNS-based tracking and SSL to support first-party visitor tracking. A tracking domain is a root domain configured with DNS records so RevCent can perform tracking tied to the merchant’s own domain. This matters because modern browsers, ad blockers, third-party cookie restrictions, cross-domain checkout flows, and privacy restrictions can make normal tracking less reliable. DNS-based / first-party tracking helps connect: ```text Visitor → tracking activity → URL parameters → metadata → sale/conversion ``` Tracking domains can include: ```text url_parameters url_parameter_sets ``` These define which URL parameters RevCent should capture and how those parameters should be saved as metadata. --- # URL Parameters to Metadata One of the most important tracking-domain capabilities is attaching metadata based on URL parameters or URL parameter sets. Example URL: ```text https://example.com/?utm_source=google&utm_campaign=spring_sale&gclid=abc123&affiliate_id=aff_001 ``` Configured tracking may save: | URL Parameter | Metadata Name | Example Value | |---|---|---| | `utm_source` | `utm_source` or `source` | `google` | | `utm_campaign` | `utm_campaign` or `campaign` | `spring_sale` | | `gclid` | `gclid` | `abc123` | | `affiliate_id` | `affiliate_id` | `aff_001` | Tracking domains can define manual URL parameters and can also use URL parameter sets. A manual URL parameter configuration can conceptually include: | Field | Purpose | |---|---| | `url_parameter` | The query parameter to capture, such as `utm_source`. | | `metadata_name` | The RevCent metadata name to save the value under. If omitted, the URL parameter name may be used. | | `default_value` | Optional default value to save when the parameter is present. | | `days` | Number of days to persist the parameter for the visitor. | Example configuration concept: ```json { "url_parameter": "utm_source", "metadata_name": "source", "days": 30 } ``` This means: ```text Capture utm_source from the landing URL. Save it as metadata name source. Persist it for the visitor for the configured duration. ``` --- # Track.js and Visitor Association 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 conversions. Important caveat: ```text Tracking the visit alone is not enough. The conversion or sale must be tied back to the tracked visitor. ``` Depending on the implementation: - WordPress / supported plugin setups may handle visitor ID integration. - Custom / non-WordPress sites need developer implementation to preserve and pass the RevCent visitor ID into checkout or sale creation flows. - Third-party shops or custom funnels must preserve visitor identity through checkout. If the visitor ID is not preserved or passed into the conversion flow, attribution may be incomplete. For custom/non-WordPress sites, the tracking script commonly appears in the website footer: ```html ``` The actual tracking domain should match the configured RevCent tracking domain. --- # Useful Granular Metrics From Metadata Metadata enables granular reporting that is difficult or impossible with standard fields alone. ## Marketing Attribution Metrics ```text Revenue by source Sales by campaign Refunds by ad creative Chargebacks by affiliate Customer lifetime value by utm_source Subscription renewal rate by original campaign Trial conversion by traffic source ``` ## Social Content Metrics ```text Sales by facebook_post_id Revenue by instagram_post Refund rate by influencer_post Customer LTV by TikTok video Declines by social story ``` ## Email Metrics ```text Sales by email_version Revenue by email_subject_variant Subscription starts by newsletter_issue Refunds by email_link Customer LTV by email segment ``` ## Funnel and Checkout Metrics ```text Sales by checkout_page Decline rate by checkout_version Conversion value by landing_page Refunds by funnel_step Trial success by upsell_page Failed payments by product_quiz_answer ``` ## Affiliate and Partner Metrics ```text Sales by affiliate_id Net revenue by partner Chargebacks by affiliate Subscription renewal success by affiliate Refund rate by sub_id ``` ## Operational Metrics ```text Sales by support_agent Revenue by call_center_batch Refunds by internal_experiment Chargebacks by campaign batch Shipping issues by promo ``` These metrics can help the business make decisions such as: ```text Which campaigns should scale? Which affiliates are profitable? Which checkout page should become default? Which social posts produce quality customers? Which email version has the best long-term value? Which traffic sources produce chargebacks? ``` --- # Metadata and BigQueryRunQuery Metadata is especially useful when paired with `BigQueryRunQuery`. `GetMetadata` and `GetMetadataEntry` help MCP/AI discover what metadata names and values exist. `BigQueryRunQuery` is used for the actual analytics. Examples: ```text Revenue by checkout_page Sales by affiliate_id Chargebacks by campaign Refund rate by email_version Customer lifetime value by source Subscription renewals by landing_page ``` Recommended workflow: ```text 1. Use GetMetadata to discover metadata names. 2. Use GetMetadataEntry to inspect values for a relevant metadata name. 3. Use GetBigQueryTables to inspect the exact BigQuery table schemas. 4. Write BigQuery Standard SQL using the confirmed schema. 5. Use BigQueryRunQuery for reporting, grouping, counts, and analytics. ``` Important: ```text Do not guess how metadata is stored in BigQuery. Use GetBigQueryTables first. ``` Metadata may appear as a repeated record, JSON field, nested structure, or other schema-specific shape. MCP/AI must confirm the actual schema before writing SQL. --- # Metadata and Search Operations Metadata also matters for Search operations. RevCent Search operations can surface metadata in result objects, and users may ask for searches that are actually metadata searches without realizing it. Examples: | User Request | Possible Metadata Meaning | |---|---| | "Find sales by affiliate partner_123" | `affiliate_id = partner_123` | | "Find sales from page B" | `checkout_page = version_b` | | "Find orders from Instagram reel 2" | `instagram_post = spring_reel_02` | | "Show failed sales from email version 3" | `email_version = welcome_v3` | | "Find customers from webinar May" | `webinar_id = may_webinar` | MCP/AI should inspect metadata when the search dimension is not an obvious schema property. Search operations are useful for: ```text Finding individual records Inspecting result metadata Seeing highlights that explain matches Searching by broad terms ``` BigQuery is better for: ```text Counts Revenue Grouping Aggregations Dashboards Trend analysis ``` --- # Metadata and Customer Segmentation Metadata can help segment customers by acquisition context, behavior, content, and funnel journey. Examples: ```text Customers from affiliate_id = partner_123 Customers from checkout_page = version_b Customers from email_version = welcome_v3 Customers from instagram_post = spring_reel_02 Customers from source = facebook Customers from webinar_id = may_webinar ``` These segments can support: - Customer groups - Email campaigns - AI Assistant targeting - AI Voice Agent targeting - VIP workflows - Support prioritization - Retention analysis - Revenue recovery strategies --- # Metadata and Automation Metadata can be used in Functions, AI Assistants, AI Voice Agents, customer groups, reports, and external workflows. Examples: ```text A Function only sends a Slack alert when affiliate_id is present. An AI Assistant runs only for customers from a specific campaign. An AI Voice Agent filter excludes customers from a certain source. A customer group includes customers where checkout_page = version_b. An external AI agent monitors BigQuery reports by metadata values. A payment routing Function considers landing_page or funnel_step context. ``` Metadata adds custom business context to automation decisions. InsertMetadata is what allows these automation systems to write their decisions back to RevCent as durable item-level context. Examples: ```text An AI Assistant inserts ai_assistant_outcome on a customer. An AI Voice Agent inserts ai_voice_outcome on a salvage_transaction. A Function inserts function_processed on a sale. An MCP client inserts mcp_review_status on a chargeback. An external AI agent inserts external_ai_risk_classification on a fraud_detection item. ``` Once inserted, that metadata can be used by future searches, reports, customer groups, AI workflows, Functions, and support processes. --- # Caveats and Best Practices ## 1. Metadata Names and Values Should Be Consistent Avoid inconsistent names: ```text source Source traffic_source utm_source ``` unless the distinction is intentional. Avoid inconsistent values: ```text Facebook facebook FB Meta ``` unless the business deliberately treats them differently. Consistency makes reports and automation easier. --- ## 2. Metadata Can Be High-Cardinality Some metadata values can have many unique values. Examples: ```text gclid fbclid click_id session_id visitor_id external_order_id request_id ``` High-cardinality metadata is useful for tracing individual events but may be less useful for grouped reports. For reporting dimensions, use controlled values such as: ```text source campaign affiliate_id checkout_page email_version landing_page traffic_channel ``` --- ## 3. GetMetadataEntry Returns Only Up to 500 Unique Values `GetMetadataEntry` is useful for discovery, but it is not a full export. If there are more than 500 values, use BigQuery or reporting tools for deeper analysis. --- ## 4. Metadata Does Not Replace Schema Fields Do not use metadata when the user’s request maps to a known schema field. Examples: ```text first_name email state postal_code approved status created_date_unix gateway transaction_id ``` If the field exists in the schema, use it directly. --- ## 5. Tracking Requires Visitor Association For tracking metadata to be attached to a conversion, the visitor identity must be connected to the sale/conversion. If the visitor ID is lost during checkout, attribution can be incomplete. --- ## 6. Tracking Domain Setup Requires DNS and SSL A tracking domain requires DNS records and SSL initialization. The domain owner must be able to modify DNS records. Setup generally involves: ```text Create tracking domain Add returned A records to DNS Initialize SSL Add returned CNAME records to DNS Initialize DNS Confirm DNS status complete Install/configure Track.js or plugin integration Confirm visitor ID is passed into conversion flow ``` --- ## 7. Metadata Is Only Useful if Captured Correctly If URL parameters are not configured or the site does not pass visitor/conversion context properly, reports may be incomplete. MCP/AI should verify: ```text Tracking domain exists DNS is complete SSL is issued Track.js is installed URL parameters or parameter sets are configured Visitor ID is preserved Metadata appears in resulting records ``` --- --- ## 8. Inserted Metadata Should Be Controlled When metadata is inserted by MCP, AI Assistants, AI Voice Agents, Functions, or external systems, names and values should be controlled. Avoid creating many inconsistent variations: ```text callback_requested Callback Requested call_back_requested customer_requested_callback ``` Choose one convention and reuse it. Controlled metadata is much easier to search, segment, and report on. # Practical Ecommerce Examples ## Example 1: Affiliate Profitability Metadata: ```text affiliate_id = partner_123 ``` Questions: ```text How many sales did partner_123 drive? What was net revenue? How many refunds came from that affiliate? What was chargeback rate? What is customer lifetime value by affiliate? ``` Use: ```text GetMetadata → GetMetadataEntry → GetBigQueryTables → BigQueryRunQuery ``` --- ## Example 2: Checkout Page Test Metadata: ```text checkout_page = version_a checkout_page = version_b ``` Questions: ```text Which checkout page generated more sales? Which page had fewer declines? Which page had higher average order value? Which page generated fewer refunds? Which page led to better subscription renewal rates? ``` --- ## Example 3: Email Version Performance Metadata: ```text email_version = welcome_v2 email_version = welcome_v3 ``` Questions: ```text Which email version created more sales? Which version created higher lifetime value customers? Which version had higher refund rate? Which version generated better subscription retention? ``` --- ## Example 4: Social Post Attribution Metadata: ```text facebook_post_id = post_987654 instagram_post = spring_reel_02 ``` Questions: ```text Which post drove the most sales? Which post drove the highest-value customers? Which post produced the most refunds? Which post should be promoted again? ``` --- ## Example 5: Landing Page and Campaign Quality Metadata: ```text landing_page = longform_a campaign = spring_sale source = google ``` Questions: ```text What was revenue by landing page? Which landing page had the highest conversion quality? Which campaign drove the best renewal rate? Which source produced the fewest chargebacks? ``` --- # MCP/AI Guidance When a user asks for search or reporting: 1. Identify whether the requested dimension is a known schema field. 2. If it is a schema field, use the schema field. 3. If it sounds custom, ambiguous, campaign-related, content-related, funnel-related, social-related, or experiment-related, inspect metadata. 4. Use `GetMetadata` to discover metadata names. 5. Use `GetMetadataEntry` to inspect exact values. 6. Use Search operations for individual record discovery. 7. Use `BigQueryRunQuery` for counts, revenue, grouping, and analytics. 8. Use `GetBigQueryTables` before writing SQL. 9. Do not guess metadata names or values. 10. Do not assume advertising-only metadata. 11. Remember metadata can be any business-defined context. 12. Use `InsertMetadata` when MCP, an AI Assistant, AI Voice Agent, Function, or external system needs to add item-specific metadata. 13. Confirm the target `item_type`, `item_id`, metadata names, metadata values, and `cascade` behavior before inserting metadata. 14. Remember that AI Assistants and AI Voice Agents can access the `InsertMetadata` system action directly. --- # Summary Metadata is one of the most flexible and powerful analysis tools in RevCent. It allows ecommerce businesses to attach custom context to records and later use that context for: ```text Conversion tracking Attribution Reporting Search BigQuery analytics Customer segmentation Automation AI workflows Affiliate analysis Campaign analysis Funnel optimization Email performance Social post attribution Checkout testing Revenue recovery analysis Chargeback/refund analysis ``` The most important concepts are: ```text Metadata is custom name/value data. InsertMetadata adds metadata name/value pairs to specific RevCent items. Metadata can be anything, not just advertising data. GetMetadata discovers names. GetMetadataEntry discovers values for one name. Tracking domains can attach metadata from URL parameters and URL parameter sets. DNS tracking and Track.js help connect visitors to conversions. Search operations can surface metadata for individual records. MCP clients can call InsertMetadata directly, and AI Assistants / AI Voice Agents can use the InsertMetadata system action. BigQueryRunQuery is used for reporting and analytics. Use schema fields when they exist; use metadata when the dimension is custom or ambiguous. ``` When used correctly, metadata turns RevCent from a system of records into a system of insights. --- 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.