---
title: "Key Values"
description: "A non-technical overview of Key Values in RevCent, focused on how account-wide reusable values and pointers can be centrally maintained, referenced by supported RevCent features, and used safely in templates, AI workflows, API calls, and Functions."
type: "feature"
company: "RevCent"
canonical: "https://revcent.com/documentation/markdown/ecosystem/feature/KeyValue.md"
technical_links:
  web_app: "https://kb.revcent.com/en/tools/key-value"
  api:
    section: "https://revcent.com/docs/api/v2#section-key_values"
    operations:
      - name: "Get Key Values"
        operation_id: "GetKeyValues"
        operation: "https://revcent.com/docs/api/v2#operation-GetKeyValues"
        schema: "https://revcent.com/documentation/files/api/operation/GetKeyValues.json"
      - name: "Create A Key Value"
        operation_id: "CreateKeyValue"
        operation: "https://revcent.com/docs/api/v2#operation-CreateKeyValue"
        schema: "https://revcent.com/documentation/files/api/operation/CreateKeyValue.json"
      - name: "Get A Key Value"
        operation_id: "GetKeyValue"
        operation: "https://revcent.com/docs/api/v2#operation-GetKeyValue"
        schema: "https://revcent.com/documentation/files/api/operation/GetKeyValue.json"
      - name: "Edit A Key Value"
        operation_id: "EditKeyValue"
        operation: "https://revcent.com/docs/api/v2#operation-EditKeyValue"
        schema: "https://revcent.com/documentation/files/api/operation/EditKeyValue.json"
      - name: "Delete A Key Value"
        operation_id: "DeleteKeyValue"
        operation: "https://revcent.com/docs/api/v2#operation-DeleteKeyValue"
        schema: "https://revcent.com/documentation/files/api/operation/DeleteKeyValue.json"
  mcp:
    overview: "https://revcent.com/documentation/markdown/mcp/operation/OverviewKeyValue.md"
    operations:
      - name: "Get Key Values"
        operation_id: "GetKeyValues"
        markdown: "https://revcent.com/documentation/markdown/mcp/operation/GetKeyValues.md"
        available_via_ai: true
      - name: "Create A Key Value"
        operation_id: "CreateKeyValue"
        markdown: "https://revcent.com/documentation/markdown/mcp/operation/CreateKeyValue.md"
        available_via_ai: true
      - name: "Get A Key Value"
        operation_id: "GetKeyValue"
        markdown: "https://revcent.com/documentation/markdown/mcp/operation/GetKeyValue.md"
        available_via_ai: true
      - name: "Edit A Key Value"
        operation_id: "EditKeyValue"
        markdown: "https://revcent.com/documentation/markdown/mcp/operation/EditKeyValue.md"
        available_via_ai: true
      - name: "Delete A Key Value"
        operation_id: "DeleteKeyValue"
        markdown: "https://revcent.com/documentation/markdown/mcp/operation/DeleteKeyValue.md"
        available_via_ai: true
---

# Key Values

Key Values are account-wide reusable values in RevCent.

They allow a user to create a stable key and assign that key a value. Supported RevCent features can then reference the key instead of hardcoding the value in many different places.

A simple way to think about it:

```text
key = stable name
value = centrally managed content or pointer
```

Example:

```text
support_email = support@example.com
```

If the support email changes later, the user can update the Key Value once instead of manually editing every template, assistant message, Function, or supported workflow that references it.

## Why Key Values Are a Feature

Key Values are a configurable RevCent feature because users create and maintain them as shared account-level configuration.

They are not created as the result of an individual sale, customer action, transaction, shipment, or other one-time event.

A Key Value can be used to centralize things such as:

- support contact details,
- reusable customer-facing text,
- AI Assistant message values,
- Function-managed state,
- feature flags,
- operational thresholds,
- pointer aliases for supported RevCent entities.

Key Values are most useful when the same value must be reused in multiple places and may need to change later.

## Technical Links

| Area | Link |
|---|---|
| Web App | https://kb.revcent.com/en/tools/key-value |
| API | https://revcent.com/docs/api/v2#section-key_values |
| MCP | https://revcent.com/documentation/markdown/mcp/operation/OverviewKeyValue.md |

## Core Purpose

The purpose of Key Values is to reduce hardcoding and make shared RevCent configuration easier to maintain.

Instead of embedding a value directly in many different places, a user can store the value under a key and reference that key from supported features.

For example:

```text
support_email
brand_phone
active_payment_profile
sync_cursor
vip_threshold
feature_enabled
```

This allows RevCent workflows to become more flexible because a shared value can be changed centrally.

## Account-Wide Scope

Key Values are account-wide.

They are not attached to a specific customer, sale, product, transaction, shipment, or other individual item.

Use Key Values for shared account-level values.

Use metadata when the value belongs to a specific item.

Conceptually:

```text
Key Value = shared account-level value
Metadata = item-specific value
```

## Key Structure

A Key Value is built around a unique key.

The key is the stable name used by supported features to retrieve or resolve the stored value.

A Key Value may include:

| Field | Purpose |
|---|---|
| Key | The unique name used to reference the value. |
| Description | Human-readable explanation of what the key is for. |
| Key Type | Whether the key stores a string or a pointer. |
| Value | The stored raw value or pointer target. |
| Pointer Type | The entity type referenced when the key is a pointer. |

## Key Naming Rules

The key is important because it cannot be changed after creation.

Key naming rules:

| Rule | Requirement |
|---|---|
| Minimum length | 2 characters |
| Maximum length | 100 characters |
| Allowed characters | Alphabetical characters and underscores only |
| Starts with underscore | Not allowed |
| Ends with underscore | Not allowed |
| Spaces | Not allowed |
| Numbers | Not allowed |
| Hyphens or periods | Not allowed |

Good examples:

```text
support_email
brand_phone
active_payment_profile
sync_cursor
vip_threshold
```

Bad examples:

```text
support-email
support.email
support email
support_email_1
_support_email
support_email_
```

Use clear names because the key becomes the long-term reference point.

## Descriptions

A good description should explain what the Key Value is for and where it is used.

Good descriptions answer questions like:

- What does this value store?
- Which features use it?
- Is it manually maintained or Function-managed?
- Is it a pointer?
- Is changing it high-impact?

Example:

```text
Support email used in Email Templates and AI Assistant messages.
```

Another example:

```text
Pointer to the active payment profile used by API-call pointer shortcodes.
```

## Key Types

Key Values support two main key types:

```text
String
Pointer
```

These types behave differently and should be used for different purposes.

## String Key Values

A string Key Value stores raw text.

The stored string can be used for text, settings, JSON-formatted state, feature flags, thresholds, or reusable content.

Examples:

```text
support@example.com
888-555-0100
true
500
{"last_run_unix":1770000000}
```

String Key Values are useful for:

- Email Template shortcodes,
- AI Assistant message shortcodes,
- Function state,
- shared text,
- shared settings,
- feature flags,
- thresholds,
- reusable brand details.

String values can be up to 5 MB.

## Pointer Key Values

A pointer Key Value points to another RevCent entity.

A pointer is useful when a user wants a stable key to resolve to a specific RevCent item that may change later.

The currently documented pointer type is:

```text
Payment Profile
```

Example:

```text
active_payment_profile → Primary Credit Card Payment Profile
```

Later, the user can update the pointer target:

```text
active_payment_profile → New Payment Profile V2
```

Anything that references the pointer key can then resolve to the updated pointer target without hardcoding the new Payment Profile ID.

Important: a Key Value pointer can reference a Payment Profile, but it does not create or modify the Payment Profile itself.

## Key Values and Payment Profile Pointers

Payment Profile pointers are powerful because they can be used in supported API-call shortcode contexts.

For example, a sale request or workflow can reference a key instead of hardcoding a Payment Profile ID:

```json
{
  "payment_profile": "[key_values.active_payment_profile]"
}
```

RevCent resolves the pointer shortcode to the actual Payment Profile target.

This makes it easier to switch which existing Payment Profile is referenced by supported calls.

Because Payment Profile pointers can affect payment routing behavior, they should be changed carefully.

## Supported Places to Use Key Values

Key Values can be used in several RevCent features.

| Feature | Method | Supported Key Types | Example |
|---|---|---|---|
| Email Template | Double-curly shortcode | String, Pointer | `{{key_values.support_email}}` |
| AI Assistant message | Bracket shortcode | String, Pointer | `[key_values.support_email]` |
| API call | Bracket shortcode | Pointer only | `[key_values.active_payment_profile]` |
| Function | RevCent Function object | String, Pointer for reading; string for updates | `global["revcent"].GetKeyValue(...)` |

## Email Template Usage

Email Templates can reference Key Values using double-curly syntax.

Example:

```handlebars
Need help? Contact us at {{key_values.support_email}}.
```

If the Key Value is:

```text
support_email = support@example.com
```

then the rendered email can include:

```text
Need help? Contact us at support@example.com.
```

This is useful for support emails, support phone numbers, brand URLs, footer text, and shared policy text.

## AI Assistant Usage

AI Assistant messages can reference Key Values using bracket syntax.

Example:

```text
If the customer needs help, tell them to contact [key_values.support_email].
```

This allows assistant messages and steps to use shared account-level values without hardcoding them inside each AI workflow.

Key Values can be used in AI Assistant message contexts such as Web Chat messages, autonomous assistant step messages, and branch messages where supported.

## API Call Pointer Usage

API calls support pointer Key Values using bracket syntax.

Example:

```json
{
  "payment_profile": "[key_values.active_payment_profile]"
}
```

Only pointer key types are supported in API calls at this time.

String key types are not supported in API calls to help avoid misconfiguration and payment errors.

The pointer must correspond to the expected field. For example, a Payment Profile pointer should be used where a payment profile value is expected.

## Function Usage

RevCent Functions can read Key Values through the RevCent Function object.

Example:

```javascript
global["revcent"].GetKeyValue("support_email", callback);
```

Functions can also update string Key Values.

Example:

```javascript
global["revcent"].UpdateKeyValue("sync_cursor", "next_cursor_value", callback);
```

Important: Functions can update string Key Values only.

Pointer Key Values cannot be updated from a Function.

Use the Key Value edit flow for pointer updates.

## Function State Management

Key Values can help Functions remember state between runs.

This is useful when a Function needs to track progress, avoid duplicate work, or store a shared operational setting.

Examples:

```text
sync_cursor
last_processed_sale
external_sync_cursor
feature_enabled
vip_threshold
```

Example state value:

```json
{"last_processed_sale":"XXXXXXXXXXXXXXXXXXXX","last_run_unix":1770000000}
```

A Function can read the current state, do work, and then update the string Key Value with the next state.

## Key Values vs Metadata

Key Values should not be confused with metadata.

| Concept | Use When |
|---|---|
| Key Value | The value is account-wide and reusable. |
| Metadata | The value belongs to a specific item. |

Use metadata for things like a customer-specific preference, sale-specific external order ID, transaction-specific partner ID, or product-specific marker.

Use a Key Value for things like support contact details, feature flags, shared thresholds, Function cursors, or Payment Profile pointer aliases.

## Key Values vs Environment Variables

Key Values should also not be confused with environment variables.

| 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 secrets and private credentials.

Use Key Values for shared RevCent configuration that supported features need to reference.

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

Use Key Values for shared data.

Use AI Prompts for reusable prompt content.

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

Use Key Values for shared values or pointers.

Use AI Voice Snippets for reusable voice-agent instruction blocks.

## Creating Key Values

Key Values can be created through the RevCent web app, API, or AI Assistant system action where enabled.

In the web app, users can create a Key Value from Tools > Key Values.

Creation requires a unique key.

After creation, the key itself cannot be modified.

The user can then configure the description, key type, value, and pointer target if the key is a pointer.

## Editing Key Values

Key Values can be edited through the RevCent web app, API, or AI Assistant system action where enabled.

Users can edit:

- description,
- key type,
- string value,
- pointer type,
- pointer target.

High-impact Key Values should be reviewed before editing.

Examples of high-impact Key Values include Payment Profile pointers, Function state cursors, feature flags, and customer-facing template values.

## High-Impact Key Values

Some Key Values can change important business behavior.

A Payment Profile pointer can affect which existing Payment Profile is referenced by supported API calls.

A Function state cursor can affect what a Function processes next.

A feature flag can turn automation behavior on or off.

A template value can change customer-facing content.

These should be named clearly, described well, and edited carefully.

## Good Key Value Design

Good Key Values are:

- clearly named,
- stable,
- documented with useful descriptions,
- scoped to account-wide values,
- not used as item-specific metadata,
- not used as a secret store,
- reviewed before high-impact edits.

Good examples:

```text
support_email
brand_phone
active_payment_profile
sync_cursor
vip_threshold
feature_enabled
```

Avoid vague keys like:

```text
email
value
profile
cursor
setting
```

## Common Ecommerce Use Cases

### Shared Support Details

A business can create Key Values for support contact information.

Examples:

```text
support_email
support_phone
support_url
```

These can be reused in Email Templates and AI Assistant messages.

### Payment Profile Alias

A business can create a pointer Key Value such as:

```text
active_payment_profile
```

Supported API calls can reference the key instead of hardcoding the Payment Profile ID.

### Function State Cursor

A Function can use a string Key Value to remember the last item it processed.

Example:

```text
last_processed_sale
```

The Function can read the value at the beginning of a run and update it at the end.

### Feature Flag

A Function or workflow can use a string Key Value as a simple feature flag.

Example:

```text
fraud_alerts_enabled = true
```

The Function can check the value before deciding whether to continue.

### Dynamic Threshold

A business can store a threshold as a string Key Value.

Example:

```text
vip_threshold = 500
```

A Function or AI workflow can read the value so the threshold can be changed without editing the workflow code.

## Common Mistakes

Avoid these mistakes:

- using Key Values for item-specific metadata,
- using vague key names,
- assuming a key can be renamed after creation,
- putting secrets or private credentials in Key Values,
- using string Key Values in API calls where only pointer values are supported,
- changing a Payment Profile pointer without reviewing downstream impact,
- expecting a Function to update pointer Key Values,
- allowing multiple Functions to update the same state key without intentional design,
- using a Key Value where an AI Prompt or AI Voice Snippet would be more appropriate.

## Best Practices

1. Use Key Values for shared account-wide values.
2. Use metadata for item-specific values.
3. Choose stable key names before creation.
4. Add descriptions that explain where the key is used.
5. Use string keys for shared text, settings, state, feature flags, and thresholds.
6. Use pointer keys for supported entity references such as Payment Profiles.
7. Validate pointer targets before relying on them.
8. Store structured Function state as JSON strings when needed.
9. Keep values under the documented size limit.
10. Use environment variables for secrets.
11. Review high-impact keys before editing.
12. Be careful when multiple automations depend on the same key.

## Summary

Key Values are account-wide reusable values in RevCent.

They let users store a value once and reference it from supported RevCent features.

They can support Email Template shortcodes, AI Assistant message shortcodes, API-call pointer shortcodes, Function access, Function state management, feature flags, shared customer-facing details, and Payment Profile pointer aliases.

The key concepts are:

```text
Key Values are account-wide.
Keys cannot be modified after creation.
String Key Values store raw values.
Pointer Key Values point to supported RevCent entities.
API calls support pointer Key Values only.
Functions can read Key Values.
Functions can update string Key Values only.
Key Values are not metadata.
Key Values are not environment variables.
```

Used well, Key Values make RevCent workflows easier to maintain because shared values can be updated centrally instead of being hardcoded across many separate places.


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