# RevCent MCP Overview: Sales AI/MCP-focused overview for Sales in RevCent. This document explains what a Sale is, how Sales are created, how Sales relate to Product Sales, shipments, tax, discounts, customers, subscriptions, and trials, and how AI/MCP clients should choose the correct Sales-related operations. It also includes critical guidance for refunds and reporting. --- ## Core Concept A **Sale** is the central purchase object in RevCent. For ecommerce businesses, Sales are one of the most useful and valuable parts of RevCent because the Sale is not just a payment record. A Sale becomes the hub that connects the customer, products purchased, payment outcome, fulfillment, tax, discounts, refunds, subscriptions, trials, email communication, AI workflows, functions, event automation, reporting, and recovery opportunities. Using RevCent to create and manage Sales gives an ecommerce business a unified operational and analytical record of what happened before, during, and after checkout. DNS tracking and conversion tracking make this even more powerful. When a visitor arrives through a tracked domain, RevCent can capture URL parameters, persist them as metadata, associate the tracked visitor with the later Sale/conversion, and attach the origin data to the Sale lifecycle. This gives ecommerce businesses extremely granular attribution and lifecycle reporting when using `BigQueryRunQuery`. Credit card Sales are especially valuable because the customer's payment information/card is stored securely in RevCent's PCI DSS Level 1 environment. RevCent acts as a credit card vault for ecommerce businesses, storing customer payment card information on behalf of users to support future purchases, renewals, retries, recovery workflows, and customer support payment updates. A Sale can be created through: - The RevCent web app - The RevCent API - The RevCent MCP - AI workflows inside RevCent - AI Assistants that are allowed to use Sale/payment-related system tools - AI Voice Agents speaking live with customers when allowed to use Sale/payment-related system actions - A RevCent plugin, such as the RevCent WooCommerce WordPress plugin - A RevCent hosted checkout or hosted solution In practice, Sales may originate from human staff in the web app, direct API/MCP calls, automated AI workflows, voice-assisted customer recovery calls, WooCommerce checkout events, hosted checkout flows, or other RevCent-powered purchase paths. A Sale represents a customer purchase attempt for one or more products. It is the parent object that ties together payment, customer data, purchased products, shipping, tax, discounts, and downstream entities such as subscriptions and trials. Every Sale has a specific customer. A Sale is also the spawning point for: - Product Sales - Shipments - Tax records - Discount records - Subscriptions - Trials - Transactions - PayPal Transactions - Offline Payments - Check Directs - Pending Refunds - Fraud and dispute context - Fulfillment notifications for shippable products - Email Template sends, when configured - Event-triggered automations - AI Assistant workflows - AI Voice Agent workflows - Function-triggered workflows - Notes and metadata - DNS tracking metadata and visitor attribution context - AI-related records when applicable --- ## AI, MCP, Plugin, and Voice-Assisted Sale Creation Sales in RevCent are not limited to manual web app or direct API creation. A Sale can be created, retried, recovered, or completed through several RevCent surfaces. ### Web App A RevCent user can create and manage Sales through the RevCent web app. This is useful for internal staff, support, operations, finance, or manual order workflows. ### API and MCP External systems, custom apps, storefronts, automations, and MCP clients can create Sales using `CreateSale`, create pending Sales using `CreatePendingSale`, update pending Sales using `UpdatePendingSale`, process pending Sales using `ProcessPendingSale`, and estimate Sale totals using `EstimateSale`. Use API/MCP creation when another system needs to send the purchase request into RevCent directly. ### WooCommerce Plugin Sales can be created through the RevCent WooCommerce WordPress plugin after the plugin is installed on a WooCommerce site and the User Shop is created in RevCent. For WooCommerce, the expected setup is: 1. Install the RevCent WordPress plugin on the WooCommerce installation. 2. Create the User Shop in RevCent. 3. Validate and fix the User Shop configuration as needed. 4. Map products, shipping methods, and payment/offline-payment methods correctly. 5. Let the plugin send checkout/order/payment activity into RevCent. Once configured, WooCommerce checkout activity can create RevCent Sales, Product Sales, shipments, tax, discounts, and payment records through the RevCent integration flow. ### Hosted Checkout or Hosted Solution A RevCent hosted checkout or hosted solution can also create Sales. In this pattern, RevCent-hosted purchase flows collect the relevant customer/cart/payment data and create the Sale inside RevCent. ### AI Assistants AI Assistants can participate in Sale creation, retry, recovery, and analysis workflows when configured with the appropriate triggers, instructions, thread steps, system tools, and safeguards. AI Assistants can be triggered by RevCent events, on demand through the web app/API/another assistant, or on a schedule. For Sales workflows, common event triggers include declined Sales, successful Sales, failed Sales, pending Sales, subscription renewal failures, trial events, and other revenue lifecycle events. AI Assistant Sale-related use cases include: - Analyze declined Sales. - Determine whether a failed or declined Sale is recoverable. - Retry or recover abandoned/declined Sales when the assistant has been explicitly designed and permitted to do so. - Trigger recovery emails through Email Templates. - Use BigQuery to analyze decline, revenue, refund, or recovery patterns. - Create notes or metadata after recovery attempts. - Trigger Functions for custom eligibility/recovery logic. - Trigger another specialized assistant for follow-up. - Create AI Memos for high-value failed Sales or unusual payment issues. Important: AI Assistants should only create, retry, recover, or process Sales when the workflow is explicitly configured to do so and the available system tools/actions permit it. Payment actions must be guarded by clear business rules, filters, usage limits, max-runs-per-item settings, and explicit user/customer authorization when applicable. ### AI Voice Agents AI Voice Agents can help create, retry, or recover Sales live with a customer over the phone when configured with the appropriate call method, instructions, system actions, and business rules. AI Voice Agents may be inbound or outbound. Sale-related AI Voice Agent workflows include: - Declined payment recovery calls. - Abandoned checkout or pending Sale recovery calls. - Live checkout assistance. - Trial conversion calls that may create or process a Sale. - Subscription renewal recovery calls. - Customer support calls that retrieve Sale details and help complete a pending payment. - Refund/cancellation triage calls that inspect Sale context and route to the correct action. - Chargeback prevention calls related to a Sale. Typical Sale-related AI Voice Agent system actions may include: - `SearchCustomers` - `GetCustomer` - `GetSale` - `EstimateSale` - `AddCardToCustomer` - `CreateSale` - `ProcessPendingSale` - `CreateNote` - `InsertMetadata` - `SendSMTPMessage` Only enable payment, refund, card, or Sale-processing actions when the business has clear policy rules and wants the AI Voice Agent to perform those actions. The agent should verify identity, explain why it is calling, avoid pressure, get clear customer consent, respect retry limits, and create notes/metadata summarizing call outcomes. --- ## Sale Creation and Recovery Decision Guide | Origin or Workflow | Typical RevCent Path | |---|---| | Internal/manual order | Web app or `CreateSale` | | External storefront/custom checkout | API/MCP `CreateSale` | | Multi-step checkout or upsell flow | `CreatePendingSale` → `UpdatePendingSale` → `EstimateSale` → `ProcessPendingSale` | | WooCommerce checkout | RevCent WooCommerce WordPress plugin + User Shop configuration | | Hosted checkout | RevCent hosted checkout/hosted solution creates the Sale | | AI Assistant declined Sale recovery | Event-triggered or on-demand AI Assistant using configured Sale/payment tools | | AI Assistant abandoned/pending Sale recovery | Assistant reviews Sale, sends recovery email, updates metadata/notes, and processes pending Sale only if authorized | | AI Voice Agent declined payment recovery | Outbound call using `GetSale`, `AddCardToCustomer`, `ProcessPendingSale`, notes, and metadata when enabled | | AI Voice Agent live Sale creation | Live call using `CreateSale` or pending Sale flow when enabled and customer consents | AI/MCP clients should choose the least risky workflow that matches the user's intent and should never assume permission to charge, retry, create, or refund a Sale without explicit authorization and configured tool access. A Sale consists of several child or related item types. ### Product Sales Product Sales are the line-item purchase records inside a Sale. A Sale may contain one or more Product Sales. Each Product Sale represents the purchase of a specific product within that Sale. Product Sales are a subset of a Sale, but they are extremely important because they provide product-level granularity. A Product Sale can contain or expose data such as: - Product ID - Product name - Quantity - Purchase price - Total amount - SKU - Internal product ID - Subscription flag - Trial flag - Product-specific discount amount Use Product Sales for product-level analysis and product-specific refunds. ### Shipments Shipments are shipping records related to a Sale. A Sale may have one or more shipment records when shippable products are sold. Shipping may be added to the Sale request and can include: - Shipping amount - Shipping provider - Provider method - Name - Description Shipment records are separate related items and can be refunded separately with `RefundShipment`. ### Tax Tax records are tax line items related to a Sale. A Sale may include one or more tax entries. Tax can be itemized in the Sale request and can include: - Tax amount - Tax name - Tax description Tax records are separate related items and can be refunded separately with `RefundTax`. ### Discounts Discount records represent discounts applied to the Sale. Discounts may come from: - Coupon codes - Static discount entries - Percent discounts - Fixed-amount discounts - Product-specific discounts - Shipping-specific discounts Discounts reduce the Sale total and may be linked to product or shipping line items. --- ## Sales as the Origin for Subscriptions and Trials A Sale is the starting point for subscriptions and trials. If a product sold in a Sale has an associated subscription profile, RevCent can automatically create a subscription related to that Sale. If a product sold in a Sale has trial settings, RevCent can automatically create a trial related to that Sale. This means the Sale is not only a one-time order object. It can be the origin point for future recurring lifecycle events, including: - Subscription renewals - Trial expirations - Trial conversions - Subscription cancellations - Renewal-related shipments, tax, transactions, and product sales AI/MCP clients should treat the Sale as the parent context for understanding how a customer entered a subscription or trial lifecycle. --- ## Related MCP Operations | Operation | Purpose | |---|---| | `GetSales` | Retrieve a paginated operational list of Sales. Do not use for reporting, metrics, aggregation, data mining, or bulk retrieval. | | `GetSale` | Retrieve details for one Sale by Sale ID. | | `CreateSale` | Create a Sale with payment. | | `VoidSale` | Void a Sale in its entirety; if paid, refunds all associated payments for product sales, shipping, and tax. | | `AddFraudAlert` | Add a fraud alert to an existing Sale for further review before creating a fraud detection. | | `RemoveFraudAlert` | Remove a fraud alert from an existing Sale. | | `CreatePendingSale` | Create a pending Sale without processing payment. | | `UpdatePendingSale` | Update an existing pending Sale without processing payment. | | `ProcessPendingSale` | Process payment for an existing pending Sale. | | `EstimateSale` | Estimate Sale totals, products, shipping, tax, coupons, and discounts without processing payment. | | `SearchSales` | Search Sales by a single search term or phrase. | | `TriggerAIAssistant` | Can trigger an on-demand AI Assistant that may analyze, recover, or take configured actions related to a Sale. | | `TriggerAIVoiceAgent` | Can trigger an outbound AI Voice Agent that may call a customer for declined/abandoned Sale recovery when configured. | | `CreateAIAssistant` / `EditAIAssistant` | Configure AI Assistant workflows for Sale analysis, recovery, notes, emails, functions, and BigQuery reporting. | | `CreateAIVoiceAgent` / `EditAIVoiceAgent` | Configure AI Voice Agent workflows for live Sale support, recovery, retry, and customer conversations. | Related refund and analytics operations: | Operation | Purpose | |---|---| | `RefundProductSale` | Refund a Product Sale line item. Best for product-specific or partial refunds. | | `RefundShipment` | Refund a shipment/shipping item. | | `RefundTax` | Refund a tax item. | | `BigQueryRunQuery` | Required for reporting, metrics, aggregation, and data mining. | | `GetBigQueryTables` | Inspect available BigQuery tables and schemas before writing SQL. | --- ## Critical Reporting Rule Use `BigQueryRunQuery` for all Sales-related: - Reporting - Metrics - Aggregation - Counts - Totals - Revenue analysis - Refund analysis - Product analysis - Campaign analysis - Shop analysis - Subscription/trial analysis - Customer analysis - Data mining - Business intelligence - Trend analysis - Ranking - Comparison - Broad record analysis Using `GetSales` for reporting, metrics, aggregation, data mining, bulk retrieval, or business intelligence is prohibited. `GetSales` is only for small, bounded, operational lookups. AI/MCP clients must not paginate through `GetSales` to compute totals or build reports. If the user asks: - “How many Sales did I have?” - “What was revenue last month?” - “Show Sales by campaign.” - “Which products sold best?” - “What is my refund rate?” - “Give me Sales metrics.” - “Export all Sales.” - “Analyze Sales trends.” - “Find all Sales matching a broad condition.” Use `BigQueryRunQuery`, not `GetSales`. --- ## `GetSales` `GetSales` returns a paginated list of Sales. ### Correct Use Use `GetSales` only for bounded operational lookup, such as: - Listing recent Sales for manual review - Finding a Sale within a narrow date range - Looking up Sales for a specific customer - Looking up Sales using specific filters before retrieving one with `GetSale` ### Prohibited Use Do not use `GetSales` for reporting, aggregation, metrics, data mining, bulk retrieval, or business intelligence. Use `BigQueryRunQuery` instead. ### Required Inputs | Field | Type | Required | Description | |---|---:|---:|---| | `date_start` | integer | Yes | Date range start as Unix timestamp in seconds. | | `date_end` | integer | Yes | Date range end as Unix timestamp in seconds. | | `limit` | integer | Yes | Number of records to return. Range 1 to 25. | | `page` | integer | Yes | Page number for pagination. | ### Optional Filters | Field | Type | Description | |---|---:|---| | `campaign_filter` | array | Filter by one or more Campaign IDs. | | `currency_filter` | array | Filter by ISO 4217 currency code. | | `shop_filter` | array | Filter by one or more User Shop IDs. | | `payment_type_filter` | array | Filter by payment type. | | `status_filter` | array | Filter by current Sale status. | | `metadata_filter` | array | Filter by metadata name/value pairs. | | `customer_id` | string | Filter Sales related to a specific Customer ID. | --- ## `GetSale` `GetSale` retrieves the details of a specific Sale using a Sale ID. Input: ```json { "sale_id": "XXXXXXXXXXXXXXXXXXXX" } ``` Use `GetSale` when the user needs: - One specific Sale - Sale-level details - Customer context - Payment status - Product details - Related item IDs - Child entities such as Product Sales, shipping, subscriptions, trials, or transactions - Fraud alert status - PayPal dispute status - Metadata or notes `GetSale` includes related item arrays. If an AI/MCP client needs details for a specific related item, it should use the ID from the related array with the proper detail operation. Examples: | Related Array | Meaning | Follow-up Operation | |---|---|---| | `product_sales` | Product Sale IDs for products purchased within the Sale | `GetProductSale` | | `transactions` | Credit card transaction IDs | `GetTransaction` | | `paypal_transactions` | PayPal transaction IDs | PayPal transaction lookup/search/reporting operations | | `offline_payments` | Offline payment IDs | `GetOfflinePayment` | | `shipping` | Shipment IDs | `GetShipment` | | `tax` | Tax IDs | `GetTax` | | `discounts` | Discount IDs | `GetDiscount` | | `subscriptions` | Subscription IDs | `GetSubscription` | | `trials` | Trial IDs | `GetTrial` | | `pending_refunds` | Refund/pending refund IDs | `GetPendingRefund` if available in client context | --- ## `CreateSale` `CreateSale` creates a Sale with payment. Sales can be created by the web app, API, MCP, AI workflows, RevCent plugins such as the WooCommerce WordPress plugin, or a hosted solution. When using the API/MCP directly, `CreateSale` is the operation that creates a paid Sale attempt. AI Assistants and AI Voice Agents may also create Sales when explicitly configured with the correct tools/actions and business rules. This is especially useful for recovery workflows where a customer returns to complete a purchase, agrees to retry a declined payment, or completes a live voice-assisted checkout. ### Required Fields The Sale request requires: | Field | Description | |---|---| | `campaign` | 20-character Campaign ID. | | `product` | Array of products to include in the Sale. | | `payment_type` | Payment type for the Sale. | | `ip_address` | Customer IP address. | ### Payment Types `payment_type` can be: - `credit_card` - `paypal` - `offline_payment` - `check_direct` ### Credit Card Sales and PCI DSS Level 1 Card Storage RevCent is the credit card vault for ecommerce businesses using RevCent credit card Sales. When a customer pays by credit card, the customer's payment card information is stored in RevCent's PCI DSS Level 1 environment on behalf of the user, enabling secure future payments, subscription renewals, trial expiration charges, retry/recovery workflows, and customer support payment updates. When a Sale is created via credit card, RevCent stores the customer's payment information/card for future customer payments, retries, renewals, and recovery workflows. AI/MCP clients should understand that credit-card payment information is stored in RevCent's PCI DSS Level 1 environment. RevCent functions as a credit card vault for ecommerce businesses by storing customer payment card data on behalf of users. This is important for ecommerce businesses because credit card Sales store vaulted customer card data that supports: - Customer card storage - Future purchases - Subscription renewals - Trial expiration charges - Pending Sale processing - Declined Sale retry/recovery workflows - AI Assistant recovery workflows - AI Voice Agent live recovery workflows - Customer support payment updates AI/MCP clients must still treat card data as sensitive. Do not expose raw card data unnecessarily. Do not ask users to paste full card data into chat unless the active workflow and secure collection method explicitly support it. Prefer secure, RevCent-supported payment collection workflows. Important payment-specific requirements: | Payment Type | Required Fields | |---|---| | `credit_card` | `credit_card` object and `payment_profile` are required. | | `paypal` | `paypal_transaction_id` is required. | | `offline_payment` | Use the offline payment flow and related configuration. | | `check_direct` | Use the check direct flow and related configuration. | ### Product Array The `product` array contains the products being purchased. Each product entry can include: | Field | Description | |---|---| | `id` | Required 20-character Product ID. | | `quantity` | Quantity being purchased. Defaults to 1. | | `price` | Optional override price if different from the product default price. | When the Sale is created, RevCent creates Product Sale line items from these purchased products. ### Customer, Billing, and Shipping `CreateSale` can include: - `customer` - `bill_to` - `ship_to` - `customer_id` for an existing customer If an existing customer ID is not provided, the customer object should include first name, last name, and email. ### Other Sale Inputs `CreateSale` can also include: - `iso_currency` - `shipping` - `tax` - `coupon` - `discount` - `internal_sale_id` - `internal_customer_id` - `metadata` `internal_sale_id` is useful for third-party order IDs, such as an order ID from a plugin or storefront. --- ## `EstimateSale` `EstimateSale` estimates the total cost and itemized results without processing payment. It uses the same general request structure as a Sale create request, except no payment is processed. Use `EstimateSale` for: - Checkout previews - Pre-payment totals - Product totals - Shipping totals - Tax totals - Coupon validation - Discount display - Showing customer savings - Estimating a pending Sale before processing `EstimateSale` can return itemized details for: - Products - Shipping - Tax - Coupons - Discounts - Totals It can also estimate a previously created pending Sale if `sale_id` is provided. AI/MCP clients should use `EstimateSale` when the user wants to preview or calculate a cart/order total before charging the customer. --- ## Pending Sale Flow Pending Sales are designed for multi-step checkout, upsell flows, and situations where Sale details may change before payment is processed. ### `CreatePendingSale` `CreatePendingSale` creates a pending Sale and returns a Sale ID. It does **not** process payment. Use it when the user needs to: - Save customer information before payment - Save a cart/order before payment - Build a multi-step checkout - Support upsells before final payment - Create a pending order that can be updated later - Save payment info for later processing ### `UpdatePendingSale` `UpdatePendingSale` updates an existing pending Sale. It does **not** process payment. Use it to modify: - Customer details - Billing/shipping details - Products - Shipping - Tax - Discounts - Coupons - Payment information - Metadata Important: When adding or modifying products, shipping, tax, or discounts, pay close attention to `pending_options` behavior in the operation schema/client docs. Pending Sale updates can replace or modify parts of the pending order depending on options. ### `ProcessPendingSale` `ProcessPendingSale` processes payment for an existing pending Sale. Use it when the Sale is ready to be charged. A typical pending flow: 1. `CreatePendingSale` 2. `UpdatePendingSale` as the cart/upsell flow changes 3. Optional `EstimateSale` 4. `ProcessPendingSale` --- ## AI Sale Recovery Workflows AI workflows are especially useful for declined, abandoned, failed, or pending Sales. ### AI Assistant Recovery An AI Assistant can run after a Sale event or be triggered on demand. For example, an assistant can run when a Sale is declined, review Sale and customer context, decide whether recovery is appropriate, send a personalized recovery email, create a note, insert metadata, run a custom Function, or trigger another assistant. Common AI Assistant Sale recovery patterns: 1. Sale is declined, failed, abandoned, or pending. 2. Assistant is triggered by event, schedule, web app, API/MCP, or another assistant. 3. Assistant retrieves or reviews Sale/customer context. 4. Assistant applies campaign/status/metadata filters and optional Function-based eligibility logic. 5. Assistant decides whether the Sale is recoverable. 6. Assistant takes configured action, such as sending an Email Template, adding metadata, creating a note, or processing/retrying payment when explicitly permitted. 7. Assistant records the outcome for reporting and auditing. Recommended safeguards: - Use specific Sale event triggers where possible. - Use filters to reduce unnecessary AI runs. - Use max-runs-per-item to avoid retry loops. - Record outcomes with notes and metadata. - Use BigQuery for reporting on AI-assisted recovery performance. - Never allow payment actions unless the assistant is intentionally configured for those actions. ### AI Voice Agent Recovery An AI Voice Agent can recover or retry Sales live with a customer on a phone call. This is useful when a human-like real-time conversation can save a Sale that might otherwise be lost. Common AI Voice Agent Sale recovery patterns: 1. A Sale is declined, failed, abandoned, or left pending. 2. An outbound AI Voice Agent is triggered or a customer calls inbound. 3. The agent verifies the customer and explains why it is calling or how it can help. 4. The agent retrieves Sale/customer context. 5. The agent answers product, order, shipping, or payment questions. 6. If the customer consents and the action is enabled, the agent may help add/update a card or process the pending Sale. 7. The agent records the outcome with notes and metadata. Important voice-specific safeguards: - Verify identity before discussing private Sale or payment details. - Do not pressure the customer. - Only collect or update card/payment details when enabled and the customer clearly agrees. - Limit payment retries. - Use call outcome metadata for reporting. - Escalate edge cases to humans. - Avoid enabling refund, card, or Sale-processing actions unless the business has explicit policies for those actions. ### Recovery Metrics AI Assistant and AI Voice Agent recovery performance should be measured with `BigQueryRunQuery`, not `GetSales`. Examples: - AI-assisted recovered revenue - Declined Sales recovered by assistant - Voice recovery completion rate - Pending Sales processed after AI outreach - Recovery rate by campaign - Recovery rate by product - Recovery email conversion - Call outcome by voice agent - Refunds after AI-assisted Sales - Notes/metadata outcomes by workflow --- ## `VoidSale` `VoidSale` voids a Sale in its entirety. If the Sale is pending, `VoidSale` cancels the pending Sale. If the Sale is paid, `VoidSale` fully refunds all associated payments for the Sale. When a paid Sale is voided, all Product Sales, shipping, and tax are refunded in their entirety. Input: ```json { "sale_id": "XXXXXXXXXXXXXXXXXXXX" } ``` `VoidSale` can return arrays showing what was affected, including: - `pending_refund` - `product_sale_refunded` - `shipping_refunded` - `tax_refunded` - `subscription_cancelled` - `trial_cancelled` Use `VoidSale` for full Sale refunds, not for product-specific partial refunds. --- ## Partial Refunds vs Full Sale Refunds Refund routing is important. ### Partial Refunds Use component-level refund operations when only part of the Sale should be refunded. | Refund Type | Operation | Use When | |---|---|---| | Product-specific refund | `RefundProductSale` | A specific product line item is refunded fully or partially. | | Shipping refund | `RefundShipment` | A specific shipping amount is refunded fully or partially. | | Tax refund | `RefundTax` | A specific tax line item is refunded fully or partially. | For partial refunds, provide the `amount` field. If `amount` is omitted in these operations, the entire related item is refunded. ### Full Sale Refunds Use `VoidSale` when the user wants to refund the entire Sale. Do not refund every Product Sale, shipment, and tax item manually if the user wants a full Sale refund. `VoidSale` is the full-Sale operation and refunds product sales, shipping, and tax in their entirety for a paid Sale. ### AI/MCP Refund Decision Rules | User Intent | Correct Operation | |---|---| | Refund one product in an order | `RefundProductSale` | | Refund part of one product line item | `RefundProductSale` with `amount` | | Refund shipping only | `RefundShipment` | | Refund part of shipping | `RefundShipment` with `amount` | | Refund tax only | `RefundTax` | | Refund part of tax | `RefundTax` with `amount` | | Refund the entire Sale | `VoidSale` | | Cancel a pending Sale | `VoidSale` | | Analyze refund metrics | `BigQueryRunQuery` | Refunds are consequential financial actions. Do not execute a refund without explicit user authorization. --- ## Product Sales as a Subset of Sales Product Sales are the most important subset of a Sale for product-level business analysis. A Sale is the parent transaction/order. Product Sales are the child line items. This distinction matters because: - A Sale can contain multiple products. - Product Sales preserve product-level detail. - Product Sales make partial product refunds possible. - Product Sales make product-level reporting more accurate. - Product Sales support SKU-level analysis. - Product Sales are essential for product-level refund metrics. - Product Sales help determine which products drive revenue, refunds, trials, and subscriptions. For analytics, use `BigQueryRunQuery` against the relevant BigQuery tables, such as `sale` and `product_sale`, after checking schemas with `GetBigQueryTables`. --- ## Shipments, Tax, and Discounts as Sale Subsets Sales also contain or relate to shipments, tax, and discounts. ### Shipments Shipments represent shipping charges and fulfillment/shipment records. They can be tied to shippable products and can be refunded with `RefundShipment`. ### Tax Tax records represent itemized tax applied to the Sale. They can be refunded with `RefundTax`. ### Discounts Discounts represent coupon-based or static reductions applied to products and/or shipping. Discounts affect Sale totals and can appear in Sale estimation and Sale details. These child records allow RevCent to track the full economic composition of the Sale: ```text Sale total = products + shipping + tax - discounts ``` --- ## Fraud Alert Operations ### `AddFraudAlert` `AddFraudAlert` adds a fraud alert to an existing Sale. Use it when a Sale should be flagged for further review before creating a fraud detection. Input: ```json { "sale_id": "XXXXXXXXXXXXXXXXXXXX" } ``` ### `RemoveFraudAlert` `RemoveFraudAlert` removes a fraud alert from an existing Sale. Input: ```json { "sale_id": "XXXXXXXXXXXXXXXXXXXX" } ``` Use these operations for operational fraud review workflows, not for reporting. For fraud metrics or trend analysis, use `BigQueryRunQuery`. --- ## `SearchSales` `SearchSales` searches previously created Sales using a single search term or phrase. Input: ```json { "search_term": "customer@example.com" } ``` Search results can include: - Sale ID - Customer name - Customer address - Customer email - Customer phone - Ship-to fields - IP address - Fingerprint - Metadata - URL to the Sale details page - Search highlights - Search score Use `SearchSales` to locate a specific Sale when the user provides a search term. Do not use `SearchSales` for reporting, aggregation, metrics, data mining, or bulk retrieval. --- ## BigQuery for Sales Reporting Use `BigQueryRunQuery` for Sales reporting and analysis. Examples: - Sales count by day - Revenue by campaign - Sales by product - Product Sale revenue by SKU - Refund amount by product - Full refund rate by campaign - Shipping revenue by shop - Tax collected by state - Discount usage by coupon - Trial starts by campaign - Subscription starts by product - PayPal Sales by shop - Offline payment Sales by provider - Customer repeat purchase analysis - Fraud alert trends - Sale conversion analysis - Sales by DNS tracking metadata - Revenue by URL parameter metadata - Lifecycle metrics by traffic source, affiliate, ad click, or landing page Before writing SQL, use `GetBigQueryTables` if the exact table names or fields are not known. Common relevant tables may include: - `revcent.user.sale` - `revcent.user.product_sale` - `revcent.user.shipping` - `revcent.user.tax` - `revcent.user.discount` - `revcent.user.customer` - `revcent.user.subscription` - `revcent.user.trial` - `revcent.user.transaction` - `revcent.user.paypal_transaction` - `revcent.user.offline_payment` - `revcent.user.pending_refund` Always use BigQuery Standard SQL and fully qualified table references wrapped in backticks. Example format: ```sql SELECT COUNT(*) AS total_sales FROM `revcent.user.sale` WHERE created_date_unix BETWEEN 1735689600 AND 1738367999 ``` --- ## AI/MCP Operation Selection Guide | User Request | Recommended Operation | |---|---| | “Show me recent Sales” | `GetSales` only if bounded and operational | | “Get this Sale” | `GetSale` | | “Create a paid Sale” | `CreateSale` | | “Create a cart/order but do not charge yet” | `CreatePendingSale` | | “Update this pending cart/order” | `UpdatePendingSale` | | “Charge this pending Sale” | `ProcessPendingSale` | | “Estimate checkout total” | `EstimateSale` | | “Recover this declined Sale with AI” | Configured AI Assistant or AI Voice Agent workflow | | “Have AI call the customer to recover this declined/pending Sale” | `TriggerAIVoiceAgent`, if the Voice Agent is configured for Sale recovery | | “Run an assistant to analyze this failed Sale” | `TriggerAIAssistant`, if the Assistant is configured for Sale analysis/recovery | | “Find a Sale by customer email/order ID/search term” | `SearchSales` | | “Flag this Sale for fraud review” | `AddFraudAlert` | | “Remove fraud alert” | `RemoveFraudAlert` | | “Refund the entire Sale” | `VoidSale` | | “Refund one product line item” | `RefundProductSale` | | “Refund shipping” | `RefundShipment` | | “Refund tax” | `RefundTax` | | “Sales report/metrics/analysis” | `BigQueryRunQuery` | | “Where did this Sale come from?” | Inspect Sale/tracking metadata; use `BigQueryRunQuery` for reporting | | “Revenue by UTM/source/affiliate/ad click” | `BigQueryRunQuery` using DNS tracking metadata | | “Export all Sales” | Bulk export guidance, not `GetSales` | --- ## Common Mistakes to Avoid Do not: - Use `GetSales` for reporting, metrics, aggregation, data mining, or bulk retrieval. - Paginate through `GetSales` to calculate totals. - Use `SearchSales` for reporting. - Use component-level refund operations when the user wants a full Sale refund. - Use `VoidSale` when the user only wants a product-specific partial refund. - Omit `amount` in `RefundProductSale`, `RefundShipment`, or `RefundTax` when the user intends a partial refund. - Guess Sale IDs, Product Sale IDs, Shipping IDs, or Tax IDs. - Refund without explicit user authorization. - Create a Sale without verifying required fields, payment type requirements, product IDs, customer context, and campaign ID. - Treat credit card payment information casually; payment data should be handled as sensitive data and managed through RevCent-supported secure workflows. - Allow an AI Assistant or AI Voice Agent to create, retry, or process Sales without explicit workflow design, policy guardrails, and tool/action permissions. - Let AI repeatedly retry the same Sale without max-runs-per-item, retry limits, filters, or clear recovery rules. - Treat a Sale as only one product; a Sale can contain multiple Product Sales. - Forget that shippable products can create shipment and fulfillment outcomes. - Forget that products with subscription profiles or trial settings can automatically create subscriptions or trials. - Ignore Sale-triggered automations such as Email Templates, AI Assistants, AI Voice Agents, Functions, and webhooks. - Ignore DNS tracking metadata when determining Sale origination, campaign attribution, affiliate attribution, or full lifecycle performance. - Guess metadata field names instead of inspecting metadata/schema before reporting. - Ignore child entities when diagnosing Sale issues. - Treat Sales as the reporting layer; use BigQuery for reporting. --- ## Best Practices - Use `EstimateSale` before charging when the user needs checkout totals. - Use pending Sales for multi-step checkout and upsell flows. - Use AI Assistants for structured Sale analysis, declined Sale recovery, abandoned Sale follow-up, and recovery email workflows when configured with proper guardrails. - Use AI Voice Agents for live declined payment recovery, pending Sale completion, trial conversion, or checkout assistance when configured with proper identity verification, consent, and retry limits. - Use the RevCent WooCommerce WordPress plugin plus a properly configured User Shop for WooCommerce Sale creation. - For credit card Sales, understand that RevCent stores customer payment information/cards in its PCI DSS Level 1 credit card vault for future payments, renewals, retries, and recovery workflows. - Configure fulfillment accounts and product shipping settings so shippable products can trigger fulfillment workflows automatically. - Configure Email Templates for key Sale events such as purchase confirmation, decline recovery, shipping/tracking, refunds, trials, and subscriptions. - Configure DNS tracking and URL parameter metadata so Sale origination and lifecycle performance can be reported at the most granular level. - Configure AI Assistants, AI Voice Agents, Functions, and event workflows around Sale outcomes to automate recovery, support, risk review, and operations. - Treat every Sale as a source of downstream business outcomes, not merely as a payment record. - Use `GetSale` before issuing refunds or operational changes. - Use `RefundProductSale` for product-specific refunds to preserve product-level refund metrics. - Use `RefundShipment` for shipping-specific refunds. - Use `RefundTax` for tax-specific refunds. - Use `VoidSale` for full Sale refunds or pending Sale cancellation. - Use `BigQueryRunQuery` for metrics and reporting. - Preserve `internal_sale_id` when integrating with plugins, hosted stores, or external carts. - Use metadata for business-specific dimensions, but verify metadata names before querying. - Treat the Sale as the parent object and Product Sales, shipments, tax, discounts, subscriptions, and trials as related/child context. --- ## Additional Public Source References for AI/MCP Clients The following public RevCent references are useful background for this overview: - RevCent payments/card storage pages state that RevCent is a certified PCI DSS Level 1 service provider and stores customer card data for users as a credit card vault for ecommerce businesses. - RevCent shipping documentation states that shipping is created when a customer purchases a shippable product, and that subscription renewals with shippable products can also create shipping items. - RevCent reporting pages describe BigQuery as the reporting/query engine for metrics and dashboard-style analysis. - RevCent Tracking Domain documentation explains that DNS-based tracking can capture URL parameters, save them as metadata, associate visitor activity with later Sales/conversions, and support reporting by traffic source, affiliate, campaign, ad, keyword, and other marketing dimensions. --- ## Final AI/MCP Instruction A Sale is the parent purchase object in RevCent. It is created through the web app, API, MCP, AI workflows, AI Assistants, AI Voice Agents, plugins such as the RevCent WooCommerce WordPress plugin, or a hosted solution and ties together the customer, product sales, shipments, tax, discounts, payment, fraud status, subscriptions, and trials. Use `GetSale` for specific Sale details, `CreateSale` for paid Sale creation, pending Sale operations for multi-step checkout flows, `EstimateSale` for pre-payment totals, and `VoidSale` for full Sale refunds. Use `RefundProductSale`, `RefundShipment`, and `RefundTax` for partial or component-level refunds. AI Assistants and AI Voice Agents can create, retry, recover, or complete Sales only when they are explicitly configured with the correct tools/actions, instructions, filters, business rules, user/customer consent requirements, and safety limits. For ecommerce businesses, the main value of RevCent Sales is that a Sale can drive the entire purchase lifecycle: payment, product line items, fulfillment, emails, events, AI, functions, subscriptions, trials, refunds, support, risk review, recovery, and analytics. Use `BigQueryRunQuery` for all Sales reporting, metrics, aggregation, data mining, and business intelligence. Using `GetSales` for those purposes is prohibited.## Sale Creation Outcome Chart The following Markdown chart shows what can occur when a Sale is created in RevCent. Some outcomes depend on configuration, product settings, payment type, shop/plugin setup, fulfillment settings, Email Template triggers, AI/Function triggers, and business rules. ### Markdown Chart This chart is plain Markdown/text so it renders reliably in AI/MCP clients and documentation viewers. ```text SALE CREATED ├─ Customer associated │ ├─ New customer created, or │ └─ Existing customer linked │ ├─ DNS tracking / conversion attribution can attach metadata │ ├─ Visitor identity associated with Sale/conversion │ ├─ URL parameters captured and saved as metadata │ ├─ Examples: utm_source, utm_campaign, gclid, fbclid, affiliate_id, sub_id │ ├─ Sale origination and lifecycle context becomes visible │ └─ BigQueryRunQuery can report at the most granular attribution level │ ├─ Payment record created or linked │ ├─ Credit card transaction │ │ └─ Customer payment information/card is stored in RevCent's PCI DSS Level 1 credit card vault │ ├─ PayPal transaction │ ├─ Offline payment │ └─ Check direct │ ├─ Product Sales created │ ├─ One Product Sale per product line item │ ├─ Product-level revenue/refund metrics become possible │ ├─ Product-specific partial refunds can use RefundProductSale │ ├─ If product has subscription profile → Subscription can be created automatically │ ├─ If product has trial settings → Trial can be created automatically │ └─ If product is shippable → Shipment/fulfillment workflow can begin │ ├─ Shipping, tax, and discounts created │ ├─ Shipment records for shippable products │ ├─ Tax records │ └─ Discount records from coupons or static discounts │ ├─ Fulfillment outcomes can occur │ ├─ Fulfillment can be notified for shippable products │ ├─ Shipping/tracking lifecycle begins │ └─ Shipping-related customer support context is created │ ├─ Customer communication can occur │ ├─ Email Templates can send confirmation, decline, recovery, shipping, refund, trial, or subscription emails │ └─ AI-personalized follow-up emails can be sent when configured │ ├─ Event-driven automation can occur │ ├─ AI Assistant workflows │ ├─ AI Voice Agent workflows │ ├─ Function workflows │ ├─ Webhooks/integrations │ ├─ Notes │ ├─ Metadata │ └─ AI Memos or internal alerts │ ├─ Recovery or risk workflows can occur │ ├─ Declined Sale recovery │ ├─ Abandoned/pending Sale recovery │ ├─ Fraud alert/risk review │ └─ Chargeback prevention workflows │ ├─ Refund paths later depend on intent │ ├─ Partial product refund → RefundProductSale │ ├─ Partial shipping refund → RefundShipment │ ├─ Partial tax refund → RefundTax │ └─ Full Sale refund/cancel → VoidSale │ └─ Reporting and analytics ├─ Use BigQueryRunQuery for metrics/reporting/data-mining └─ Do not use GetSales for reporting or aggregation ``` --- 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.