# RevCent Key Value Overview This document explains Key Values in RevCent at a broad level. It is not an operation-specific guide. Instead, it explains what Key Values are, why they exist, where they can be used, and how they help connect different RevCent features. Sources: - RevCent Key Value operation schemas - RevCent Key Value Knowledge Base - RevCent Function usage patterns --- # What Is a Key Value? A Key Value is a system-wide account value stored under a unique key. In simple terms: ```text key = stable name value = stored value ``` Example: ```text key: support_email value: support@example.com ``` The key can then be referenced in supported RevCent features. Key Values are useful when a RevCent account needs a reusable value that can be centrally maintained and accessed in multiple places. --- # Why Key Values Exist Key Values solve a common problem: ```text A business has the same value used in many places. That value may need to change later. Instead of editing every place individually, store the value once and reference the key. ``` Examples: ```text Support email address Brand phone number Default payment profile pointer Shared footer text Reusable AI Assistant phrase Function state cursor Feature flag Operational threshold External sync checkpoint ``` If the value changes, the user can update the Key Value rather than manually updating every feature that references it. --- # Key Values Are Account-Wide Key Values are system-wide within the RevCent account. They are not attached to a specific customer, sale, product, transaction, or other individual item. This makes them useful for shared configuration and reusable values. Examples: ```text support_email active_payment_profile daily_report_cursor brand_support_phone vip_ltv_threshold fraud_alerts_enabled ``` --- # Key Values Are Not Metadata Key Values and metadata are different. | Concept | What it is for | |---|---| | Key Value | Account-wide reusable value or pointer accessed by key. | | Metadata | Data attached to a specific item, such as a customer, sale, product, or transaction. | If the user wants to store information on a specific customer or sale, that is metadata. If the user wants to create a shared account-level value used across features, that is a Key Value. Important: ```text Do not use Key Values when the user asks to insert metadata. Do not use metadata when the user asks to create a reusable Key Value. ``` --- # Key Value Structure A Key Value can include: ```text key description value key_type pointer_type ``` ## `key` The key is the unique name. It cannot be modified once created. Key rules: ```text Minimum length: 2 Maximum length: 100 Alphabetical characters and underscores only Cannot start with underscore Cannot end with underscore Cannot contain spaces Cannot contain numbers Cannot contain hyphens Cannot contain periods ``` Good examples: ```text support_email active_payment_profile daily_report_cursor brand_phone checkout_footer vip_threshold ``` Invalid examples: ```text support-email support.email support email support_email_1 _support_email support_email_ 1support_email ``` Because the key cannot be changed later, it should be stable and descriptive. --- ## `description` The description explains what the Key Value is for. A good description should say: - What the key stores - Which features use it - Whether it is manually maintained or Function-managed - Whether it is a pointer - Whether changes are high-impact Examples: ```text Support email used in Email Templates and AI Assistant messages. ``` ```text Pointer to the active payment profile used by API-call pointer shortcodes. ``` ```text Function-managed cursor storing the last processed sale ID for nightly reporting. ``` The description can be up to 255 characters. --- ## `value` The value is the stored content. It can be up to 5 MB. Examples: ```text support@example.com ``` ```json {"last_run_unix":1770000000,"last_processed_sale_id":"XXXXXXXXXXXXXXXXXXXX"} ``` ```text Primary Credit Card Payment Profile ``` For `string` Key Values, the value is the stored string. For `pointer` Key Values, the value must identify an existing item of the matching pointer type. --- # Key Types RevCent Key Values support two key types: ```text string pointer ``` --- ## String Key Values A string Key Value stores raw text. Examples: ```text support@example.com 888-867-5399 true 500 {"last_run_unix":1770000000} ``` String Key Values are useful for: - Email Template shortcodes - AI Assistant message shortcodes - Function state - Shared text - Shared configuration - Feature flags - JSON state objects - Reusable thresholds - Operational cursors Example: ```json { "key": "support_email", "value": "support@example.com", "key_type": "string" } ``` --- ## Pointer Key Values A pointer Key Value points to another RevCent item. Pointer Key Values are useful when a stable key should resolve to a specific RevCent item. Currently supported pointer type: ```text payment_profile ``` Example: ```json { "key": "active_payment_profile", "value": "Primary Credit Card Profile", "key_type": "pointer", "pointer_type": "payment_profile" } ``` The value can be either the RevCent ID or name of the item corresponding to the pointer type. For `pointer_type = payment_profile`, the value must match an existing payment profile. --- # Why Pointer Key Values Are Useful Pointer Key Values allow a stable key to point to an item that may change later. Example: ```text active_payment_profile → Primary Credit Card Payment Profile ``` Later, the user can edit the Key Value: ```text active_payment_profile → New Payment Profile V2 ``` Anything that references the pointer key can use the updated target without hardcoding the new payment profile ID. This is especially useful for API-call pointer shortcodes. --- # Key Value Availability Across RevCent Key Values can be used in several RevCent features. The most important uses are: ```text Email Templates AI Assistant messages API-call pointer shortcodes Functions ``` --- # Email Templates Email Templates can reference Key Values using double-curly syntax: ```handlebars {{key_values.my_key}} ``` Example: ```handlebars Need help? Email us at {{key_values.support_email}}. ``` If: ```text support_email = support@example.com ``` then the template can render: ```text Need help? Email us at support@example.com. ``` This is useful for: - Support emails - Support phone numbers - Brand URLs - Footer content - Shared legal text - Reusable brand details --- # AI Assistant Messages AI Assistant messages can reference Key Values using bracket syntax: ```text [key_values.my_key] ``` Example: ```text If the customer needs help, tell them to contact [key_values.support_email]. ``` This is useful for: - Shared support contact information - Brand-specific phrases - Reusable policy text - Common internal instructions - Dynamic values that may change later AI Assistant messages can include Key Values in places such as: ```text Web Chat messages Autonomous assistant node step messages Branch messages ``` --- # API-Call Pointer Shortcodes API calls can use pointer Key Values with bracket shortcode syntax: ```text [key_values.my_key] ``` Example: ```json { "payment_profile": "[key_values.active_payment_profile]" } ``` If `active_payment_profile` is a pointer Key Value to a payment profile, RevCent can resolve the shortcode to the payment profile ID. Important: ```text Only pointer key types are supported in API calls at this time. String key types are not supported in API calls to avoid misconfiguration and payment errors. ``` This is a major use case for payment profile pointers. --- # Functions Functions can access Key Values through the RevCent Function object. Read a Key Value: ```javascript global["revcent"].GetKeyValue(my_key, callback) ``` Update a string Key Value: ```javascript global["revcent"].UpdateKeyValue(my_key, value, callback) ``` Important: ```text Functions can only update Key Values where key_type = string. Pointer Key Values cannot be updated within a Function. ``` This means string Key Values can be used for state management, while pointer Key Values should be updated through Key Value edit operations. --- # Functions and State Management One of the most powerful uses of Key Values is persistent state for Functions. RevCent Functions are commonly used for automation, integrations, reporting, alerts, and workflow logic. A Function may need to remember something between runs. Key Values can provide that persistent memory. --- ## State Management Example: Last Processed Sale A scheduled Function may process new sales every hour. It needs to avoid processing the same sale twice. A Key Value can store the last processed sale. ```json { "key": "last_processed_sale", "value": "{\"last_sale_id\":\"XXXXXXXXXXXXXXXXXXXX\",\"last_run_unix\":1770000000}", "key_type": "string" } ``` Function concept: ```javascript global["revcent"].GetKeyValue("last_processed_sale", function(error, value) { if (error) { callback(error); return; } const state = JSON.parse(value || "{}"); // Use state.last_sale_id to decide what to process next. const nextState = JSON.stringify({ last_sale_id: "YYYYYYYYYYYYYYYYYYYY", last_run_unix: Math.floor(Date.now() / 1000) }); global["revcent"].UpdateKeyValue("last_processed_sale", nextState, callback); }); ``` --- ## State Management Example: Daily Report Cursor A daily reporting Function can store its last run time. ```json { "key": "daily_report_cursor", "value": "{\"last_run_unix\":1770000000,\"last_report_date\":\"2026-05-30\"}", "key_type": "string" } ``` This can prevent duplicate reporting and help the Function know what data window to process. --- ## State Management Example: External Sync Cursor A Function that syncs with a shipping or CRM provider may need to remember the last external cursor. ```json { "key": "shipping_sync_cursor", "value": "{\"cursor\":\"abc123\",\"last_sync_unix\":1770000000}", "key_type": "string" } ``` --- ## State Management Example: Feature Flag A Function may check whether an automation is enabled. ```json { "key": "fraud_alerts_enabled", "value": "true", "key_type": "string" } ``` Function concept: ```javascript global["revcent"].GetKeyValue("fraud_alerts_enabled", function(error, value) { if (error) { callback(error); return; } if (value !== "true") { callback(null, { skipped: true, reason: "Fraud alerts disabled." }); return; } // Continue alert logic... }); ``` --- ## State Management Example: Dynamic Threshold A business may want a threshold that can change without editing Function code. ```json { "key": "vip_ltv_threshold", "value": "500", "key_type": "string" } ``` A Function can read the threshold and apply it. This avoids hardcoding business thresholds in Function code. --- # Key Values vs Environment Variables Key Values and Function environment variables are different. | Concept | Best for | |---|---| | Key Value | Shared values, state, feature flags, public configuration, pointers. | | Environment Variable | Secrets, private tokens, API keys, passwords, credentials. | Use environment variables for: ```text API keys Webhook secrets Private tokens Passwords Sensitive credentials ``` Use Key Values for: ```text Support email Brand phone number Feature flags Function cursors Payment profile pointer aliases Shared template values ``` Key Values should not generally be used as a secret vault unless RevCent specifically documents that use case. --- # Key Values vs Metadata Use metadata when the data belongs to a specific item. Examples: ```text Customer-specific preference Sale-specific external order ID Transaction-specific partner ID Product-specific source marker ``` Use Key Values when the data is account-wide and shared. Examples: ```text support_email active_payment_profile daily_report_cursor brand_phone vip_ltv_threshold ``` --- # Key Values vs AI Prompts A Key Value is not an AI Prompt. | Concept | Purpose | |---|---| | Key Value | Account-wide value or pointer. | | AI Prompt | Saved reusable AI prompt text. | Do not use Key Values when the user wants to save a reusable prompt. Use AI Prompts for reusable prompt text. --- # Key Values vs AI Voice Snippets A Key Value is not an AI Voice Snippet. | Concept | Purpose | |---|---| | Key Value | Shared value or pointer. | | AI Voice Snippet | Reusable AI Voice Agent instruction content. | Do not use Key Values for reusable AI Voice Agent instruction blocks. --- # Common Use Cases ## Shared Contact Details ```text support_email support_phone support_url ``` Used in Email Templates and AI Assistant messages. ## Payment Profile Pointer ```text active_payment_profile ``` Used in API calls to avoid hardcoding a payment profile ID. ## Function State ```text daily_report_cursor last_processed_sale shipping_sync_cursor ``` Used by Functions to remember progress between runs. ## Feature Flags ```text fraud_alerts_enabled salvage_calls_enabled new_checkout_copy_enabled ``` Used by Functions or AI workflows to control behavior. ## Dynamic Business Thresholds ```text vip_ltv_threshold manual_review_amount max_discount_percent ``` Used by Functions or AI logic to avoid hardcoding thresholds. ## Shared Messaging Values ```text brand_footer support_escalation_text refund_policy_summary ``` Used in templates or assistant messages. --- # Key Value Naming Strategy Good Key Value names are: - Descriptive - Stable - Lowercase or consistently styled - Specific enough to avoid confusion - Not tied to temporary wording - Not overly generic Good: ```text brand_a_support_email active_payment_profile daily_report_cursor vip_ltv_threshold shipping_sync_cursor ``` Too vague: ```text email profile cursor value setting ``` Remember: ```text The key cannot be changed once created. ``` Choose carefully. --- # High-Impact Key Values Some Key Values can affect important business behavior. ## Payment Profile Pointers A pointer like: ```text active_payment_profile ``` may affect API calls that process payments. Changing it can change payment routing. This is high-impact. ## Function State Cursors A state key like: ```text daily_report_cursor ``` may affect what a Function processes next. Changing it can cause skipped items or duplicate processing. ## Feature Flags A key like: ```text fraud_alerts_enabled ``` can turn automation on or off. ## Template and Assistant Values Changing: ```text support_email support_phone brand_footer ``` can change customer-facing content. --- # Best Practices 1. Use Key Values for account-wide reusable values. 2. Do not use Key Values as metadata. 3. Use clear, stable key names. 4. Use descriptions that explain where the key is used. 5. Use `string` for text, configuration, and Function state. 6. Use `pointer` for supported entity references such as payment profiles. 7. Verify pointer targets before creating or editing. 8. Store Function state as JSON strings when structure is needed. 9. Keep values under 5 MB. 10. Use environment variables, not Key Values, for secrets. 11. Retrieve a Key Value before editing high-impact values. 12. Be careful editing Function-managed state. 13. Do not let multiple Functions update the same key unless intentionally designed. 14. Do not assume Key Value updates are atomic unless explicitly documented. 15. Treat payment profile pointer changes as potentially payment-impacting. --- # Example Key Value Catalog A RevCent account might have Key Values like: ```text support_email support_phone active_payment_profile daily_report_cursor last_processed_sale vip_ltv_threshold fraud_alerts_enabled brand_footer shipping_sync_cursor ``` Each key should have a description explaining its purpose. Example catalog: | Key | Type | Purpose | |---|---|---| | `support_email` | string | Customer support email used in templates and AI Assistant messages. | | `active_payment_profile` | pointer | Payment profile pointer for API-call shortcodes. | | `daily_report_cursor` | string | JSON cursor used by reporting Function. | | `vip_ltv_threshold` | string | Threshold used to identify VIP customers. | | `fraud_alerts_enabled` | string | Feature flag for fraud alert Function. | | `shipping_sync_cursor` | string | External shipping sync checkpoint. | --- # Summary Key Values are account-wide reusable values in RevCent. They are useful because they allow shared values to be maintained centrally and referenced across supported features. Key Values can support: ```text Email Template shortcodes AI Assistant messages API-call pointer shortcodes Function configuration Function state management Feature flags Shared business settings Payment profile pointer aliases ``` The most important concepts are: ```text Key Values are not metadata. Keys cannot be modified after creation. String Key Values store raw values. Pointer Key Values point to supported RevCent entities, currently payment profiles. Functions can read Key Values. Functions can update string Key Values. Key Values can help Functions maintain state between runs. ``` Used well, Key Values make RevCent workflows more maintainable, more dynamic, and easier to update without repeatedly editing every template, workflow, Function, or API call. --- 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.