--- title: "Notes" description: "A non-technical overview of Notes in RevCent, focused on how short human-readable notes are attached to customers, sales, and related items, how notes can be created manually in the web app or programmatically through API, MCP, AI Assistants, AI Voice Agents, and automations, and how notes support customer history, support workflows, automation, events, and BigQuery reporting." type: "item" company: "RevCent" canonical: "https://revcent.com/documentation/markdown/ecosystem/item/Note.md" relationships: - name: "Customer" url: "https://revcent.com/documentation/markdown/ecosystem/item/Customer.md" technical_links: web_app: "https://kb.revcent.com/en/management/organization/user#customer-notes" api: section: "https://revcent.com/docs/api/v2#section-notes" operations: - name: "Create A Note" operation_id: "CreateNote" operation: "https://revcent.com/docs/api/v2#operation-CreateNote" schema: "https://revcent.com/documentation/files/api/operation/CreateNote.json" mcp: overview: "https://revcent.com/documentation/markdown/mcp/operation/OverviewNote.md" operations: - name: "Create A Note" operation_id: "CreateNote" markdown: "https://revcent.com/documentation/markdown/mcp/operation/CreateNote.md" available_via_ai: true bigquery_schema: "https://revcent.com/documentation/files/bigquery/dataset.json" bigquery_tables: - "note" --- # Notes Notes are short, human-readable records attached to RevCent items. A Note is not a configuration feature. It is an item-level record that preserves useful context about a customer, sale, shipment, subscription, renewal, product sale, or another supported commerce item. Notes help humans, AI workflows, support teams, and automations understand what happened before, what was promised, what needs follow-up, or why a particular item matters. Simple examples: ```text Customer requested callback tomorrow afternoon. Support explained refund policy; customer accepted. Voice call: customer will retry payment Friday. Shipping address corrected after customer confirmation. Renewal failed; customer plans to update card after payday. ``` The practical idea is: ```text Something meaningful happens with a customer or related item ↓ A human, API workflow, MCP client, AI Assistant, AI Voice Agent, or Function creates a Note ↓ The Note becomes part of the item and customer history ↓ Humans and automated workflows can use that context later ``` --- ## Why Notes Are an Item Notes are an item because each Note is an individual record created from a specific action. A user does not configure one reusable Note and apply it everywhere. Instead, each Note represents one specific piece of context attached to one customer-related item. Conceptually: ```text Customer, Sale, Shipping record, Subscription, Renewal, or Product Sale exists ↓ A meaningful support, operational, AI, or automation outcome occurs ↓ A Note is created ↓ The Note is attached to the relevant item and customer context ``` This makes Notes different from features such as Functions, AI Assistants, AI Voice Agents, and Email Templates. Those features can create or use Notes, but the Note itself is the created record. --- ## Technical Links | Area | Link | |---|---| | Web App | `https://kb.revcent.com/en/management/organization/user#customer-notes` | | API | `https://revcent.com/docs/api/v2#section-notes` | | MCP / AI | `https://revcent.com/documentation/markdown/mcp/operation/OverviewNote.md` | | BigQuery Schema | `https://revcent.com/documentation/files/bigquery/dataset.json` | | BigQuery Tables | `note` | --- ## Core Purpose The core purpose of a Note is to preserve concise operational context. Notes answer questions such as: - What did the customer say? - What did support promise? - Why does this sale need review? - What happened during an AI Voice Agent call? - Why was the shipment changed? - Why is a subscription being followed up on? - What should the next support person or AI workflow know? - Why was an item escalated, reviewed, refunded, contacted, or ignored? Notes are especially useful when the information is important for humans to read later. --- ## Relationship to Customers Notes are closely connected to Customers. In the RevCent web app, users can create customer notes from a Customer detail page or from another customer-related item page. For example, when viewing a Sale details page, a user can create a Note for that Sale and the Note is also connected to the Customer related to the Sale. This makes Notes useful across the customer lifecycle. A support user can open a Customer and see context from related records such as: ```text Sales Shipping records Subscriptions Subscription renewals Product sales Other customer-related activity ``` The customer relationship matters because most operational context ultimately belongs to the customer history. --- ## Items Notes Can Be Attached To Programmatic Note creation supports attaching Notes to specific RevCent item types. Common supported item types include: | Item Type | Example Note Use | |---|---| | `customer` | General customer support history, preferences, callback requests, escalation context. | | `sale` | Sale-specific review, refund discussion, payment concern, order clarification. | | `product_sale` | Product-specific concern within a sale, replacement request, product issue. | | `shipping` | Address correction, delivery concern, tracking issue, fulfillment follow-up. | | `subscription` | Subscription preference, cancellation discussion, pause/continue context. | | `subscription_renewal` | Renewal failure follow-up, retry timing, payment update plan. | Use the item type that best represents where the context belongs. If the Note is about the customer generally, attach it to the Customer. If it is about a specific Sale, Shipping record, Subscription, or Renewal, attach it to that item so the context stays close to the related activity. --- ## Manual Notes in the Web App Notes can be created manually by RevCent users in the web app. The Knowledge Base describes customer notes as available from customer detail pages and from pages for entities related to a customer. Users can click the blue note button, view existing customer notes, enter a new note, and add it to the customer-related record. Manual Notes are useful for: ```text Support call summaries Refund explanations Shipping corrections Customer preferences Escalation details Follow-up reminders Internal review comments ``` A manually created Note should be short, useful, and written for the next person or workflow that may need to understand the customer history. --- ## Programmatic Notes Through API and MCP / AI Notes can also be created programmatically. This is important because Notes are not limited to manual support activity. They can be created by API workflows, MCP clients, AI Assistants, AI Voice Agents, Functions, or external systems when a workflow has something useful to preserve. Programmatic examples: ```text An AI Assistant reviews a declined sale and creates a Note explaining the recovery decision. An AI Voice Agent finishes a call and creates a concise call-summary Note. A Function detects a high-risk item and creates a Note for manual review. An external CRM creates a Note after a customer support escalation. A warehouse or fulfillment system creates a Note after a delivery exception. An MCP client creates a Note because the user explicitly asked it to document something. ``` The key requirement is that the workflow must know the target item type and item ID. Conceptual create flow: ```text Identify the relevant item ↓ Choose the correct item_type ↓ Use the target item_id ↓ Write concise note text ↓ Create the Note through API, MCP, AI, or automation ``` --- ## CreateNote Operation The `CreateNote` operation is the programmatic way to create a Note. Conceptual request body: ```json { "item_type": "customer", "item_id": "XXXXXXXXXXXXXXXXXXXX", "text": "Customer requested callback tomorrow afternoon." } ``` Use `CreateNote` when the goal is to add human-readable context to a specific RevCent item. Do not use Notes as a substitute for structured fields. If the business needs reportable values, workflow flags, or machine-readable outcomes, use Metadata in addition to or instead of a Note. --- ## Note Text Length Notes are meant to be short. The MCP overview states that note text is limited to 255 characters. Good Note: ```text Customer requested callback tomorrow afternoon to update payment card. ``` Poor Note: ```text A full transcript of the customer conversation with every statement, internal reasoning, multiple paragraphs, and detailed analysis. ``` If the content is too long, create a concise Note and store the full content somewhere more appropriate, such as a support system, document, transcript store, external CRM, or structured Metadata. --- ## Notes Should Summarize, Not Create Noise Notes should summarize meaningful interactions. Avoid creating a separate Note for every tiny conversation turn or system action. Avoid: ```text Customer said hello. Customer asked a question. Customer paused. Customer asked another question. Customer sounded upset. ``` Better: ```text Customer asked about refund policy, declined refund for now, and requested email follow-up. ``` A useful Note should help a future support user, AI workflow, or operations team quickly understand the outcome. --- ## Notes Created by AI Assistants AI Assistants can create Notes when an assistant workflow produces a useful conclusion or operational outcome. Examples: ```text AI reviewed declined sale; customer appears eligible for payment recovery follow-up. AI detected possible refund concern and escalated for support review. AI confirmed customer should receive subscription follow-up email. ``` AI Assistant Notes should be concise and outcome-focused. They should not store hidden reasoning, chain-of-thought, or long analysis. The Note should contain only the useful final context that humans and future workflows need. --- ## Notes Created by AI Voice Agents AI Voice Agents can create Notes after a call when the call produced useful context. Examples: ```text Voice call: customer requested callback tomorrow afternoon. Voice call: customer will retry payment after payday. Voice call: customer declined renewal and asked not to be called again. Voice call: customer confirmed corrected shipping address. ``` A single call-summary Note is usually better than many small notes from the same call. For structured outcomes, the AI Voice Agent or related workflow should use Metadata as well. Example: ```text Note: Voice call: customer requested callback tomorrow afternoon. Metadata: ai_voice_outcome = callback_requested ``` --- ## Notes Created by Functions and External Systems Functions and external systems can create Notes when custom automation needs to leave readable context inside RevCent. Examples: ```text Function routed renewal to manual review: high-value decline. Function synced shipment to warehouse and received confirmation. External CRM escalated customer to Tier 2 support. Warehouse reported delivery exception; support follow-up needed. ``` Functions and external systems should use Notes for readable context and Metadata for structured automation or reporting fields. --- ## Notes and Events A Note can create an Event when it is created. The common event notation is: ```text note.created ``` This allows Notes to become automation triggers. Example workflow: ```text Support user creates Note on customer ↓ RevCent records note.created event ↓ Function or AI Assistant runs from the event ↓ Workflow inspects the Note and related customer/item context ↓ Workflow takes appropriate follow-up action ``` Because Notes can trigger workflows, businesses should write them consistently and avoid ambiguous language when downstream automation depends on the Note text. --- ## Notes vs Metadata Notes and Metadata have different purposes. | Concept | Best For | |---|---| | Note | Short human-readable context attached to an item. | | Metadata | Structured name/value data for filtering, reporting, attribution, segmentation, and automation. | Example Note: ```text Customer requested callback tomorrow afternoon. ``` Example Metadata: ```json { "name": "support_outcome", "value": "callback_requested" } ``` Best practice: ```text Use Notes for humans. Use Metadata for structured automation and reporting. Use both when the business needs readable context and reportable structure. ``` --- ## Notes vs AI Memos Notes and AI Memos are also different. | Concept | Best For | |---|---| | Note | Item-level customer, sale, shipping, subscription, or support history. | | AI Memo | A memo created by an AI Assistant to alert or inform users about something the assistant found. | Use a Note when the context belongs directly on a customer or related commerce item. Use an AI Memo when the assistant needs to create a broader alert, reminder, or assistant-authored message for user attention. --- ## Retrieving Notes Notes are often retrieved by retrieving the item they are attached to. For example: ```text To view notes for a customer, retrieve the Customer details and inspect the notes array. To view notes for a sale, retrieve the Sale details and inspect its notes. To view notes for a shipping record, retrieve the Shipping details and inspect its notes. ``` This item-detail approach is best when the user wants Notes for one known item. Use BigQuery when the user wants to search or analyze Notes across many records. --- ## BigQuery Table: note RevCent includes a BigQuery table for Notes: ```text note ``` This table is useful for searching and analyzing Notes across the account. Use the BigQuery schema before writing exact SQL because field names can change or vary by table version. In general, Note reporting can involve: ```text Note IDs Creation timestamps Note text The customer or related item context The user, API, AI, or workflow source that created the Note Related item type and item ID ``` Possible BigQuery questions include: ```text How many Notes were created per day? Which customers have the most Notes? Which Notes mention refund, callback, cancellation, chargeback, shipping, or renewal? Which support users or workflows are creating Notes? Which customers have long-running support histories? Which Notes were created by API/AI workflows versus web-app users? ``` --- ## Note Reporting Examples Notes are useful for support and operations reporting because they capture human-readable context. Examples: | Report | Business Question | |---|---| | Notes created per day | Is support volume increasing? | | Customers with many Notes | Which customers need the most attention? | | Notes mentioning refunds | Which customer interactions involve refund concerns? | | Notes mentioning callbacks | How many callback requests are being created? | | Notes mentioning shipping | Which support issues are fulfillment-related? | | Notes by source | Are Notes mainly created by users, API workflows, AI, or automation? | | Notes over time per customer | How long has the customer support issue been active? | Notes should be written consistently if the business plans to report on them. For exact reporting logic, confirm the current `note` table fields from the BigQuery schema first. --- ## Notes in Customer Support Notes are one of the most practical tools for support continuity. They help support staff quickly understand: ```text What happened previously What the customer requested What was promised Whether the issue was escalated Whether follow-up is needed Whether the customer is upset or satisfied What an AI or automation already did ``` Without Notes, each support interaction can start from zero. With Notes, the support team has a concise customer history directly connected to RevCent commerce records. --- ## Notes in Revenue Recovery Notes are useful for revenue recovery because failed or declined payments often require context. Examples: ```text Customer will retry after payday. Customer requested new payment link. Customer wants callback before retry. Customer updated card and wants subscription resumed. ``` AI Assistants, AI Voice Agents, Functions, and support users can all create Notes that help later recovery workflows understand what already happened. --- ## Notes in Shipping and Fulfillment Support Notes can preserve shipping and fulfillment context. Examples: ```text Customer confirmed corrected shipping address. Replacement shipment requested. Customer reported package missing. Warehouse reported delivery exception. Tracking number sent manually to customer. ``` When a Note is attached to a Shipping record, it helps connect support context directly to the shipment involved. --- ## Notes in Subscription Support Subscription businesses need good customer history because decisions often happen over time. Examples: ```text Customer wants to pause subscription for one month. Customer asked about next renewal date. Customer plans to update card Friday. Customer requested cancellation after current period. ``` A concise subscription Note can prevent repeated explanations and help AI or support workflows make better follow-up decisions. --- ## Good Note Design A good Note is: ```text Short Specific Useful later Attached to the correct item Free of sensitive payment data Written in consistent operational language Focused on outcome, not internal reasoning ``` Good examples: ```text Customer requested callback tomorrow afternoon to update card. Customer confirmed corrected shipping address. Support explained refund policy; customer accepted. AI Voice call: customer wants renewal follow-up Friday. ``` Poor examples: ```text Called them. Customer mad. Need follow up. Long transcript pasted here... Internal reasoning hidden behind the decision... ``` --- ## Common Mistakes to Avoid Avoid: - creating play-by-play Notes during a conversation, - attaching the Note to the wrong item, - writing vague Notes that are not useful later, - storing full transcripts in Notes, - storing card numbers, CVV, passwords, API keys, or credentials, - storing hidden AI reasoning or chain-of-thought, - using Notes for structured values that should be Metadata, - assuming every Note means the same thing unless the business uses consistent wording, - using BigQuery SQL without checking the current `note` table schema. --- ## MCP / AI Guidance When an MCP client, AI Assistant, AI Voice Agent, or automation handles Notes, it should: 1. Determine whether the user wants to create a Note or retrieve Notes. 2. Confirm the target item type and item ID before creating a Note. 3. Use `CreateNote` for programmatic Note creation. 4. Keep Note text concise and within the length limit. 5. Prefer one summary Note for a completed interaction instead of many small Notes. 6. Avoid full transcripts, sensitive payment data, secrets, and hidden AI reasoning. 7. Use item detail retrieval when showing Notes for one known item. 8. Use BigQuery when searching or analyzing Notes across many records. 9. Use Metadata instead of free-form Note text for structured automation or reporting values. 10. Write Notes for future humans and workflows, not just the current action. --- ## Summary Notes are RevCent item records that preserve short, human-readable context on Customers and related commerce items. They can be created manually in the web app or programmatically through API, MCP, AI Assistants, AI Voice Agents, Functions, and external systems. Notes can be attached to customer-related records such as Customers, Sales, Product Sales, Shipping records, Subscriptions, and Subscription Renewals. They are useful for customer support, revenue recovery, shipping follow-up, subscription retention, AI workflow context, automation triggers, and BigQuery reporting. The most important rule is simple: ```text Use Notes for concise human-readable context. Use Metadata for structured reportable data. ``` --- Document Parent Directory * [Items](https://revcent.com/documentation/markdown/ecosystem/item/index.md) - Non-technical markdown documentation for items within the RevCent ecosystem. An item is an entity that is spawned as a result of a feature or operation conducted within the RevCent ecosystem.