--- title: "Metadata" description: "A non-technical overview of Metadata in RevCent, focused on custom name/value context, URL parameter capture, Tracking Domain and URL Parameter Set configuration, item-level tagging, reporting, filtering, segmentation, and automation workflows." type: "feature" company: "RevCent" canonical: "https://revcent.com/documentation/markdown/ecosystem/feature/Metadata.md" relationships: - name: "Tracking Domain" url: "https://revcent.com/documentation/markdown/ecosystem/feature/TrackingDomain.md" - name: "URL Parameter Set" url: "https://revcent.com/documentation/markdown/ecosystem/feature/URLParameterSet.md" technical_links: web_app: "https://kb.revcent.com/en/tracking/conversion-tracking" api: section: "https://revcent.com/docs/api/v2#section-metadata" operations: - name: "Get Metadata" operation_id: "GetMetadata" operation: "https://revcent.com/docs/api/v2#operation-GetMetadata" schema: "https://revcent.com/documentation/files/api/operation/GetMetadata.json" - name: "Insert Metadata" operation_id: "InsertMetadata" operation: "https://revcent.com/docs/api/v2#operation-InsertMetadata" schema: "https://revcent.com/documentation/files/api/operation/InsertMetadata.json" - name: "Get A Metadata Entry" operation_id: "GetMetadataEntry" operation: "https://revcent.com/docs/api/v2#operation-GetMetadataEntry" schema: "https://revcent.com/documentation/files/api/operation/GetMetadataEntry.json" mcp: overview: "https://revcent.com/documentation/markdown/mcp/operation/OverviewMetadata.md" operations: - name: "Get Metadata" operation_id: "GetMetadata" markdown: "https://revcent.com/documentation/markdown/mcp/operation/GetMetadata.md" available_via_ai: true - name: "Insert Metadata" operation_id: "InsertMetadata" markdown: "https://revcent.com/documentation/markdown/mcp/operation/InsertMetadata.md" available_via_ai: true - name: "Get A Metadata Entry" operation_id: "GetMetadataEntry" markdown: "https://revcent.com/documentation/markdown/mcp/operation/GetMetadataEntry.md" available_via_ai: true --- # Metadata Metadata in RevCent is a flexible feature for attaching custom name/value context to RevCent records. A metadata entry is simple: ```json { "name": "source", "value": "facebook" } ``` or: ```json { "name": "checkout_page", "value": "version_b" } ``` Metadata lets a business preserve custom context that does not belong to one of RevCent's standard fields. It is useful for traffic attribution, landing page tests, affiliate identifiers, checkout variants, AI outcomes, external workflow markers, reporting dimensions, and other business-defined information. ## Why Metadata Is a Feature Metadata is a feature because it is a reusable RevCent capability that can be used across multiple records, workflows, and tools. Metadata is not a standalone customer-facing record by itself. Instead, it is a structured layer of custom context attached to or associated with records such as Customers, Sales, Transactions, Shipments, Subscriptions, Subscription Renewals, Salvage Transactions, Chargebacks, and Fraud Detections. In practical terms: ```text Record = the RevCent item being described Metadata = custom context attached to that item ``` ## Technical Links | Area | Link | |---|---| | Web App | `https://kb.revcent.com/en/tracking/conversion-tracking` | | API | `https://revcent.com/docs/api/v2#section-metadata` | | MCP | `https://revcent.com/documentation/markdown/mcp/operation/OverviewMetadata.md` | ## Core Purpose Metadata helps RevCent users answer business-specific questions that are not always represented by built-in fields. For example, a Sale already has standard fields such as customer, amount, currency, payment type, and creation date. Metadata allows the business to add context such as: ```text affiliate_id = partner_123 checkout_page = version_b landing_page = longform_a email_version = abandoned_cart_v3 instagram_post = spring_reel_02 ai_assistant_outcome = refund_question_detected external_sync_status = sent_to_warehouse ``` This makes Metadata especially useful when a business needs to preserve the origin, experiment, workflow status, or custom operational meaning of a RevCent item. ## Metadata vs Standard Fields Metadata should be used for custom context, not as a replacement for normal RevCent fields. Use standard fields when the data is already part of the item schema: ```text customer name email phone address amount status gateway transaction ID created date subscription status ``` Use Metadata when the data is business-defined or not obviously represented by a standard field: ```text affiliate_id checkout_page landing_page email_version social_post_id funnel_step manual_review_result ai_voice_outcome ``` A good decision rule: ```text If RevCent already has a normal field for it, use the normal field. If it is custom business context, use Metadata. ``` ## Where Metadata Comes From Metadata can be created in several ways. The most important distinction is whether metadata is being attached automatically as part of an initial purchase flow, or inserted later through the manual `InsertMetadata` operation. ### URL Parameters Captured by Tracking A common source of metadata is a URL parameter on a landing page. Example landing page URL: ```text https://example.com/landing-page?source=facebook&ad=spring_offer&landing_page=version_b ``` If the Tracking Domain and URL Parameter Set are configured to capture those parameters, RevCent can save them as metadata: ```json [ { "name": "source", "value": "facebook" }, { "name": "ad", "value": "spring_offer" }, { "name": "landing_page", "value": "version_b" } ] ``` ### Automatic Initial Purchase Propagation During an initial purchase, metadata captured from tracking or supplied with the purchase context can be automatically inserted, attached, and propagated to related RevCent records. For example, purchase metadata may be attached to the Sale and its related Customer, Transaction, Shipping item, and other purchase-related records as applicable. This is important because the same acquisition or conversion context can follow the customer lifecycle instead of living only on one record. Conceptually: ```text Visitor or purchase includes metadata ↓ Initial purchase is created ↓ RevCent attaches metadata to the Sale ↓ RevCent also propagates relevant metadata to related records, such as Customer, Transaction, Shipping, and other related purchase items ``` This automatic initial-purchase propagation is different from manually calling `InsertMetadata`. ### Manual InsertMetadata Operation Metadata can also be inserted directly through the manual `InsertMetadata` operation when a system already knows the item it wants to tag. Example: ```json { "item_type": "sale", "item_id": "XXXXXXXXXXXXXXXXXXXX", "metadata": [ { "name": "checkout_page", "value": "version_b" } ], "cascade": false } ``` This is useful when an API client, MCP client, Function, AI Assistant, AI Voice Agent, or external system needs to save structured context on a RevCent item after the item exists, or outside the automatic initial-purchase metadata flow. ### Automation Outcomes Metadata can preserve the result of an automated workflow. Examples: ```text function_processed = renewal_review_v1 ai_assistant_outcome = escalation_created ai_voice_outcome = callback_requested external_sync_status = sent_to_fulfillment manual_review_status = approved ``` This allows later workflows and human users to understand what happened to the item. ## Relationship to Tracking Domains Tracking Domains are one of the most important sources of metadata. A Tracking Domain tells RevCent which domain should be tracked and enables RevCent Track.js to identify visitors on that domain. When a visitor lands on a tracked domain with recognized URL parameters, RevCent can save those parameter values as metadata. A typical flow looks like this: ```text Visitor lands on a tracked domain ↓ URL contains configured parameters ↓ RevCent Track.js identifies the visitor ↓ RevCent saves allowed parameters as metadata ↓ Visitor later completes a purchase or conversion ↓ RevCent attaches the saved metadata to the Sale ↓ RevCent can propagate the metadata to related purchase records, such as the Customer, Transaction, Shipping item, and other related items as applicable ``` For this to work well, the Tracking Domain must be configured correctly and the visitor identity must be preserved through the purchase flow. ## Relationship to URL Parameter Sets URL Parameter Sets define which URL parameters RevCent should capture and save. This matters because RevCent should not save every parameter found on every URL. A URL can contain noisy or irrelevant parameters, and saving everything would create messy metadata. A URL Parameter Set helps define intentional capture rules such as: ```text capture source as source capture campaign as campaign capture ad as ad capture landing_page as landing_page capture affiliate_id as affiliate_id ``` Example: ```text URL parameter: utm_source metadata name: source ``` This lets a business decide what the incoming URL parameter should be called once saved as RevCent metadata. ## Visitor Association Is Required Tracking a visitor is only part of the process. For tracked metadata to be useful on a Sale or related item, the visitor must be connected to the purchase or conversion flow. Supported WordPress flows may handle visitor ID passing automatically. Custom and non-WordPress implementations need to preserve and pass the RevCent visitor ID into the sale creation flow. If the visitor ID is lost before checkout, RevCent may not be able to attach the visitor's saved metadata to the resulting item. ## Metadata Structure Metadata is stored as name/value pairs. | Field | Meaning | |---|---| | `name` | The metadata dimension or label. | | `value` | The specific value for that name. | Examples: | Name | Value | Meaning | |---|---|---| | `source` | `facebook` | The visitor or item came from Facebook. | | `affiliate_id` | `partner_123` | The item is associated with a specific affiliate. | | `checkout_page` | `version_b` | The customer used checkout version B. | | `email_version` | `welcome_v3` | The item is connected to a specific email variation. | | `landing_page` | `longform_a` | The visitor first landed on a specific page. | ## Metadata Indexing RevCent maintains an index of metadata names and values. The index helps users discover which metadata names exist and which values have been seen for a given name. For example, after receiving: ```json { "name": "source", "value": "google" } ``` and later: ```json { "name": "source", "value": "facebook" } ``` RevCent can recognize `source` as a metadata name with values such as `google` and `facebook`. Metadata values are case-sensitive, so `Facebook` and `facebook` should be treated as different values unless the business intentionally normalizes them. ## Supported Item Types for Manual InsertMetadata The manual `InsertMetadata` operation can insert metadata onto supported RevCent item types. This is separate from automatic initial-purchase metadata propagation. Common supported item types include: ```text customer sale product_sale shipping subscription subscription_renewal salvage_transaction chargeback fraud_detection ``` This means manually inserted Metadata can describe many different kinds of activity, from a customer's acquisition source to a sale context, shipping sync result, or chargeback workflow status. ## Cascade Behavior for Manual InsertMetadata When manually inserting metadata with `InsertMetadata`, RevCent supports a `cascade` option. This manual cascade behavior should not be confused with the automatic metadata attachment and propagation that can occur during an initial purchase. Default behavior: ```text cascade = false ``` When `cascade = true`, metadata may also be inserted into related sub-items. For example, metadata inserted onto a Sale may also be useful on related items if the metadata describes the full purchase context. Good cascade candidates: ```text source = facebook campaign = spring_2026 affiliate_id = partner_123 checkout_page = version_b ``` Poor cascade candidates: ```text shipping_label_printed = true chargeback_evidence_status = document_created fraud_review_result = suspicious_but_allowed ``` Those examples describe a specific item or action, so they should usually stay on the specific item they describe. Important behavior: ```text Metadata may also be inserted onto the related Customer record depending on the item context. ``` Because of this, metadata names should be clear and intentional. ## Metadata and AI Assistants AI Assistants can use Metadata to preserve structured outcomes from AI workflows. Examples: ```text ai_assistant_outcome = refund_question_detected ai_assistant_next_action = escalate_to_support ai_assistant_review_result = customer_needs_follow_up ``` This is useful when an AI Assistant determines something meaningful during a thread and the result should be saved on the relevant Customer, Sale, Subscription, or other supported item. ## Metadata and AI Voice Agents AI Voice Agents can also save call outcomes as Metadata. Examples: ```text ai_voice_outcome = callback_requested ai_voice_decline_reason = insufficient_funds ai_voice_next_action = retry_tomorrow ai_voice_salvage_result = customer_will_update_card ``` This lets voice call outcomes become durable RevCent context that can be reviewed or used by later workflows. ## Metadata and Functions Functions can insert metadata as part of automation logic. Examples: ```text function_processed = fraud_review_v2 external_sync_status = sent_to_crm renewal_review_result = manual_review shipping_sync_status = warehouse_notified ``` This is useful for idempotency, workflow state, external sync markers, and preserving the outcome of custom logic. ## Metadata and Search / Filtering Metadata can help find or filter records by custom context. Examples: ```text Find sales from affiliate_id = partner_123 Find customers from checkout_page = version_b Find shipping items with external_sync_status = sent_to_warehouse Find chargebacks with chargeback_evidence_status = document_created Find salvage transactions where ai_voice_outcome = callback_requested ``` This works best when metadata names and values are controlled and consistent. ## Metadata and Reporting Metadata is vital for reporting because it gives RevCent records custom dimensions that normal fields may not provide. Sales, Customers, Transactions, Shipments, Subscriptions, Subscription Renewals, Salvage Transactions, Chargebacks, Fraud Detections, and other related records can receive business-specific context through metadata. Some metadata is automatically attached and propagated during the initial purchase flow, while other metadata is added later through the manual `InsertMetadata` operation. That context allows a business to group, filter, compare, and explain performance in ways that would not be possible from standard fields alone. For example, a Sale may have an amount, date, campaign, customer, and payment status. Metadata can add the business context behind that sale: ```text source = facebook affiliate_id = partner_123 checkout_page = version_b landing_page = longform_a email_version = abandoned_cart_v3 coupon_test = summer_offer_b ``` Once that context is attached, reporting can answer questions such as: ```text How much revenue came from each traffic source? Which affiliate generated the highest-value customers? Which checkout page produced the best conversion quality? Which landing page produced the most chargebacks? Which email version produced the best subscription renewal behavior? Which AI Voice Agent outcome led to the most successful salvage recoveries? Which external workflow status is associated with delayed shipments? ``` Metadata is especially important because it can connect the same custom context across multiple records. During an initial purchase, captured or supplied metadata can be automatically attached and propagated to the Sale and related records such as the Customer, Transaction, Shipping item, and other purchase-related items as applicable. Separately, the manual `InsertMetadata` operation can be used later to add operational metadata onto a specific Shipping item, Chargeback, Fraud Detection, Salvage Transaction, or other supported item. This makes metadata useful not only for one record, but also for broader reporting across the customer lifecycle. Useful reporting dimensions include: | Metadata Name | Common Reporting Use | |---|---| | `source` | Compare revenue, refunds, or chargebacks by traffic source. | | `affiliate_id` | Measure partner quality and downstream customer value. | | `checkout_page` | Compare checkout variants and conversion quality. | | `landing_page` | Compare funnel entry points. | | `email_version` | Compare email creative or sequence performance. | | `ai_assistant_outcome` | Measure AI workflow results. | | `ai_voice_outcome` | Measure call and recovery outcomes. | | `external_sync_status` | Review fulfillment, CRM, or warehouse workflow status. | Reporting is only as useful as the metadata is consistent. If one workflow saves `facebook`, another saves `Facebook`, and another saves `fb`, those may appear as separate values. For reporting-friendly metadata, use controlled names and controlled values wherever possible. ## Naming Guidance Metadata names should be descriptive, consistent, and stable. Good names: ```text source affiliate_id checkout_page landing_page email_version ai_assistant_outcome external_sync_status ``` Poor names: ```text src thing misc value info status ``` Metadata values should also be consistent. Prefer: ```text facebook callback_requested version_b sent_to_warehouse ``` Avoid mixing inconsistent variants unless the difference is intentional: ```text Facebook facebook FB Meta ``` ## High-Cardinality Metadata Some metadata values may have many unique values. Examples: ```text gclid fbclid click_id visitor_id external_order_id request_id ``` These can be useful for tracing a specific visitor, click, or external record, but they may be less useful for broad grouping. For broader segmentation, use controlled values such as: ```text source campaign affiliate_id checkout_page landing_page email_version traffic_channel ``` ## What Not to Store as Metadata Do not use Metadata for sensitive secrets or regulated payment data. Avoid storing: ```text API keys passwords private tokens raw card numbers CVV values sensitive authentication credentials ``` Metadata should be treated as operational context, not as a secret vault. ## Common Use Cases ### Traffic Source Attribution ```text source = google source = facebook source = affiliate ``` ### Affiliate and Partner Context ```text affiliate_id = partner_123 sub_id = creative_04 partner_offer = trial_bundle ``` ### Funnel and Checkout Testing ```text landing_page = longform_a checkout_page = version_b upsell_page = post_purchase_a ``` ### Email and Messaging Context ```text email_version = abandoned_cart_v3 sms_campaign = winback_june newsletter_issue = summer_launch ``` ### AI and Automation Outcomes ```text ai_assistant_outcome = escalation_created ai_voice_outcome = callback_requested function_processed = renewal_review_v1 ``` ### Operational Workflow State ```text external_sync_status = sent_to_fulfillment manual_review_status = approved chargeback_evidence_status = document_created ``` ## AI/MCP Guidance When using Metadata through MCP or AI: 1. Confirm whether the user is describing a standard RevCent field or custom context. 2. Use standard fields when the dimension is already a normal schema field. 3. Use Metadata when the dimension is business-defined, experiment-related, attribution-related, workflow-related, or ambiguous. 4. Use `GetMetadata` to discover existing metadata names. 5. Use `GetMetadataEntry` to inspect values for a specific metadata name. 6. Use `InsertMetadata` only when the target item type and item ID are known. 7. Confirm metadata names and values before inserting high-impact metadata. 8. Use `cascade = true` only when the metadata logically belongs on related items. 9. Keep metadata names and values consistent. 10. Do not insert secrets, credentials, or raw payment data. ## Common Mistakes Avoid these mistakes: ```text Using Metadata for data that already has a standard field. Creating many inconsistent names for the same concept. Mixing case or spelling for values that should be grouped together. Saving every URL parameter instead of only intentional parameters. Forgetting to configure URL Parameter Sets. Forgetting to create and configure Tracking Domains. Forgetting to preserve the visitor ID through checkout. Using cascade when the metadata only describes one specific item. Storing secrets or raw payment data as metadata. Using vague names that will be hard to interpret later. ``` ## Summary Metadata is RevCent's flexible custom context feature. It allows a business to attach structured name/value information to RevCent records and then use that context for attribution, reporting, filtering, segmentation, search, AI workflows, Functions, and operational review. The most important ideas are: ```text Metadata is item-specific custom context. Metadata is not the same as a standard field. Tracking Domains and URL Parameter Sets can capture URL parameters as metadata. Automatic initial-purchase metadata propagation can attach metadata to the Sale and related records. Manual InsertMetadata can add metadata directly to supported RevCent items after the item exists. Consistent names and values make metadata much more useful for reporting and automation. ``` Used well, Metadata makes RevCent records more meaningful because it preserves the business-specific context behind each item and turns that context into useful reporting dimensions. --- Document Parent Directory * [Features](https://revcent.com/documentation/markdown/ecosystem/feature/index.md) - Non-technical markdown documentation for features within the RevCent ecosystem. A feature is a part of the RevCent ecosystem that a user can create and configure.