# RevCent Discounts Operations Overview for AI/MCP Clients ## Purpose This document is an AI/MCP-focused overview of Discount items and the Discount retrieval operations in RevCent: - `GetDiscounts` - `GetDiscount` A Discount item is created when a Sale has a discount entry and that Sale is processed. A Discount can also be created when a valid RevCent Coupon is applied during an initial Sale, Subscription Renewal, or Trial expiration. The Discount item records the amount deducted from the purchase before payment and preserves relationships to the Sale and other commerce records. This overview helps AI agents and MCP clients decide how to retrieve Discounts, follow their related IDs, create a Sale that includes an authorized discount entry, and use BigQuery for Discount reporting. --- ## Core Mental Model Use this distinction: ```text Coupon = reusable promotional configuration and code discount entry = amount-or-percent instruction supplied with a Sale Discount item = historical record RevCent creates when the reduction is applied ``` The creation flow is: ```text CreateSale or another Sale-processing flow receives: - a manual discount entry, or - an applicable Coupon ↓ RevCent calculates the reduction ↓ The Sale is processed ↓ RevCent creates a Discount item ↓ The Sale and other related records expose the Discount ID ``` There is no standalone MCP operation named `CreateDiscount`. To create a new Discount outcome, the user must be performing an authorized commerce workflow that accepts a discount entry or Coupon, such as `CreateSale`. --- ## Related Documentation | Document | Link | Why It Matters | |---|---|---| | Ecosystem Discount overview | `https://revcent.com/documentation/markdown/ecosystem/item/Discount.md` | Non-technical meaning and relationship graph for Discount items. | | Knowledge Base Discount page | `https://kb.revcent.com/en/payments/discount` | Web-app explanation and instructions for viewing Discount records. | | Sales overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewSale.md` | Explains the parent Sale and downstream commerce lifecycle. | | Product Sales overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewProductSale.md` | Explains product line items related to Discounts. | | Subscription Renewal overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewSubscriptionRenewal.md` | Explains recurring billing records that can receive Discounts. | | Trial overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewTrial.md` | Explains trial and expiration activity that can receive Discounts. | | CreateSale | `https://revcent.com/documentation/markdown/mcp/operation/CreateSale.md` | Sale creation schema, including manual discount entries and Coupons. | | EstimateSale | `https://revcent.com/documentation/markdown/mcp/operation/EstimateSale.md` | Calculates itemized Sale totals before payment. | | GetDiscounts | `https://revcent.com/documentation/markdown/mcp/operation/GetDiscounts.md` | Operation-specific bounded list guidance. | | GetDiscount | `https://revcent.com/documentation/markdown/mcp/operation/GetDiscount.md` | Operation-specific single-record guidance. | | BigQueryRunQuery | `https://revcent.com/documentation/markdown/mcp/operation/BigQueryRunQuery.md` | Correct operation for metrics, aggregation, and broad analysis. | --- ## Why Discount Items Matter Discounts explain why the amount collected is lower than the undiscounted purchase amount. They help AI/MCP clients answer operational questions such as: - Which Discount was applied to this Sale? - Was it a fixed amount or a percentage? - What was the calculated reduction? - Did a Coupon cause the Discount? - Which Customer received it? - Which Products, Product Sales, or Shipping items were related? - Was the Discount connected to an initial Sale, Subscription Renewal, or Trial? - Which payment, Campaign, or Third Party Shop context surrounded it? Discounts are also important analytically because promotional revenue should be measured after the cost of the reduction. --- ## How Discounts Are Created ### Manual discount entry on a Sale The `CreateSale` schema accepts an optional `discount` array. Each entry requires `discount_value` and `discount_type`. Supported types: | Value | Meaning | |---|---| | `amount` | Fixed monetary reduction. | | `percent` | Percentage reduction calculated by RevCent. | Optional fields can name and describe the Discount and control whether it applies to Products, Shipping, or both. Example input fragment: ```json { "discount": [ { "discount_value": 10, "discount_type": "percent", "name": "Retention offer", "description": "Authorized percentage reduction", "apply_to_product": true, "apply_to_shipping": false } ] } ``` This fragment is not a complete `CreateSale` request. The client must also follow the full `CreateSale` schema and payment requirements. When the Sale is processed, the response can include `discount_created`, an array containing the created Discount IDs and calculated results. ### Coupon-generated Discount The `CreateSale` schema also accepts a `coupon` array. If RevCent validates and applies a Coupon, the Coupon produces a Discount item. The key distinction is: ```text Coupon tells RevCent which configured promotion to evaluate. Discount records the reduction actually applied to the commerce event. ``` A Coupon can be configured for initial Sales, future purchases, Subscription Renewals, or Trial expiration behavior. AI/MCP clients should never assume a code is valid or applicable without validation or an authoritative RevCent result. ### Other Sale-processing paths Discount entries can also pass through estimated, pending, manual, hosted, custom-storefront, or integrated-shop Sale flows. The creation principle remains the same: the Discount item is created from an applied reduction on commerce activity, not as a free-standing record. --- ## Consequential Action Rule Creating a Sale with a Discount changes the amount the business collects. Before an AI/MCP client includes a discount entry or Coupon in a payment-producing Sale, it should confirm or already have authoritative context for: - the user's intent to apply a Discount, - the exact fixed amount or percentage, - whether Products, Shipping, or both are eligible, - the correct currency and Sale context, - the user's authorization to grant the reduction, - the Coupon code, if one is being used, - whether the user needs an estimate before payment. Use `EstimateSale` when the user wants to see calculated totals before a payment-producing operation. Never invent a Discount, Coupon, approval limit, or promotional promise. --- ## Discount Record Fields `GetDiscount` and each `GetDiscounts` result can include these core fields: | Field | Meaning | |---|---| | `id` | The 20-character Discount ID. | | `created_date_unix` | Unix timestamp when the Discount item was created. | | `updated_date_unix` | Unix timestamp when the item was last updated. | | `discount_amount` | Total monetary reduction applied. | | `discount_percent` | Percentage of the request total represented by the reduction. | | `discount_type` | `amount` or `percent`. | | `name` | Discount name. | | `coupon` | Related Coupon details when a Coupon produced the Discount. | | `customer` | Related Customer details. | | `third_party_shop` | Originating Shop details when applicable. | The Coupon object can include: - Coupon `id`, - `coupon_code`, - Coupon `name`, - Coupon `description`. Treat the returned calculated `discount_amount` and `discount_percent` as authoritative. Do not recalculate them from incomplete context and replace RevCent's result. --- ## Related Entity IDs A Discount response can include arrays of IDs for related records, including: - `sales` - `product_sales` - `shipping` - `tax` - `discounts` - `trials` - `subscriptions` - `subscription_renewals` - `transactions` - `paypal_transactions` - `offline_payments` - `check_directs` - `salvage_transactions` - `pending_refunds` - `chargebacks` - `fraud_detections` - `api_calls` - `ai_threads` - `ai_assistants` These IDs form a relationship graph. Follow them with the matching single-record Get operation only when the related details are needed for the user's request. For example: ```text GetDiscount returns sales: [sale_id] ↓ Use GetSale with that exact sale_id when Sale details are needed ↓ The Sale can expose Product Sales, payments, Shipping, Tax, and other context ``` Do not guess related record details from the existence of an ID. --- ## Operation: GetDiscounts ### Purpose `GetDiscounts` returns a bounded, paginated operational list of Discount records previously created. Use it when: - browsing a small set of recent Discounts, - identifying a Discount ID, - filtering Discounts for a specific Customer, Campaign, currency, payment type, Shop, or Metadata value, - supporting a narrow operational or customer-service workflow. Do not use it for totals, counts, trends, aggregation, broad analysis, data mining, document-property searches, or bulk exports. ### Required inputs | Field | Type | Constraints | |---|---:|---| | `date_start` | integer | Unix timestamp in seconds. | | `date_end` | integer | Unix timestamp in seconds; the range cannot exceed 90 days. | | `limit` | integer | From 1 through 25. | | `page` | integer | Pagination page. | ### Optional filters | Field | Type | Purpose | |---|---:|---| | `campaign_filter` | array | Filter by one or more 20-character Campaign IDs. | | `currency_filter` | array | Filter by ISO 4217 currency code, such as `USD`. | | `payment_type_filter` | array | Filter by `credit_card`, `paypal`, `offline_payment`, or `check_direct`. | | `shop_filter` | array | Filter by one or more 20-character Shop IDs. | | `metadata_filter` | array | Filter by Metadata name/value pairs. | | `customer_id` | string | Filter to Discounts related to a specific Customer. | For a Metadata name-presence query, the API schema supports the special value `METADATA_NAME_EXISTS`. Use it only when the user wants to filter for the existence of a Metadata name regardless of its value. ### Example input ```json { "date_start": 1767225600, "date_end": 1769817600, "limit": 25, "page": 1, "currency_filter": ["USD"], "payment_type_filter": ["credit_card"], "customer_id": "XXXXXXXXXXXXXXXXXXXX" } ``` Use authoritative timestamps and IDs from the user's context or prior RevCent results. The sample values are structural examples, not values to copy into a live call. ### Output and pagination The response includes: - `results`, containing the current page of Discount records, - `total_count`, the number of records matching the date range and filters, - `total_pages`, the number of available pages. Do not automatically loop through all pages. If the user's intent becomes analytical, switch to `BigQueryRunQuery`. --- ## Operation: GetDiscount ### Purpose `GetDiscount` retrieves one Discount by ID. Input: ```json { "discount_id": "XXXXXXXXXXXXXXXXXXXX" } ``` The `discount_id` must be an exact 20-character Discount ID from an authoritative source, such as: - a `discount_created` result from Sale creation, - a `discounts` relationship array on a Sale or related record, - a selected `GetDiscounts` result, - a verified user-provided Discount ID. Use `GetDiscount` when: - the user asks for the details of a specific Discount, - the client needs the calculated amount or percentage, - the client needs Coupon, Customer, or Shop context, - the client needs related entity IDs for a narrow follow-up workflow. Do not invent, truncate, transform, or loosely match the ID. --- ## Choosing Between GetDiscounts and GetDiscount ```text Do you already have the exact Discount ID? ├─ Yes → GetDiscount └─ No ↓ Do you need a small operational list within a narrow date range? ├─ Yes → GetDiscounts └─ No ↓ Is the request for metrics, totals, trends, ranking, or broad analysis? ├─ Yes → BigQueryRunQuery └─ No → Ask for or discover the missing authoritative context ``` --- ## Critical Analytics Rule Do **not** use `GetDiscounts` pagination to produce reporting or metrics. Use `BigQueryRunQuery` for questions such as: - How much was discounted this month? - What is the average Discount amount? - Which Coupons produce the most Discount value? - Which Products, Campaigns, or Shops receive the most Discounts? - How do Discounted Sales compare with full-price Sales? - What percentage of purchase value is being discounted? - How do renewal Discounts affect recurring revenue? - Are discounted Customers more valuable over time? Before querying, use `GetBigQueryTables` to retrieve the current schema. Do not guess table or field names. --- ## BigQuery Discount Table The documented table is: ```text `revcent.user.discount` ``` Its fields include: | Field | Type | Meaning | |---|---|---| | `created_at` | TIMESTAMP | When the Discount was created. | | `id` | STRING | Discount ID. | | `amount` | FLOAT | Total Discount amount. | | `percent` | FLOAT | Percentage of the purchase amount represented by the Discount. | | `live_mode` | BOOLEAN | Whether the record is live or test data. | | `iso_currency` | STRING | Three-character currency code. | | `payment_type` | STRING | Payment type. | | `coupon` | STRING | Related Coupon ID. | | `customer` | STRING | Related Customer ID. | | `third_party_shop` | STRING | Related Third Party Shop ID. | | `subscription` | STRING | Related Subscription ID. | | `subscription_renewal` | STRING | Related Subscription Renewal ID. | | `paypal_transaction` | STRING | Related PayPal Transaction ID. | | `offline_payment` | STRING | Related Offline Payment ID. | | `check` | REPEATED STRING | Related check IDs. | | `shipping` | REPEATED STRING | Related Shipping IDs. | | `product_sale` | REPEATED STRING | Related Product Sale IDs. | | `products` | REPEATED STRING | Related Product IDs. | | `metadata` | REPEATED RECORD | Metadata name, value, and entry date. | When reporting: - separate live and test records, - group monetary values by currency unless conversion logic is explicitly supplied, - use documented joins through related IDs, - avoid double-counting repeated relationship fields, - state the date range and filters used. --- ## Discount vs Coupon AI/MCP clients should not use these words interchangeably. | Question | Correct Object | |---|---| | What promotion rules and code were configured? | Coupon | | Was this code valid for the purchase? | Coupon validation result | | What reduction was actually applied? | Discount | | Which Sale and Product Sales received the reduction? | Discount relationships | | How much promotional value was used over time? | BigQuery Discount analysis, often joined to Coupon data | One Coupon can create many Discount items across many qualifying commerce events. --- ## Discount vs Refund A Discount reduces the amount before payment. A refund returns money after payment. ```text Original eligible purchase amount ↓ Discount applied ↓ Reduced amount paid ↓ Possible later refund of some or all paid value ``` Do not route a post-payment return of funds through Discount logic. Use the appropriate refund operation for the item and payment context. --- ## Product and Shipping Scope The Sale discount entry supports: - `apply_to_product` - `apply_to_shipping` The schema defaults both to true. Set either to false when the Discount should be limited to the other category. Examples: | Intended Offer | `apply_to_product` | `apply_to_shipping` | |---|---:|---:| | Percentage off eligible Products and Shipping | `true` | `true` | | Product-only Discount | `true` | `false` | | Shipping-only Discount | `false` | `true` | Do not infer scope from a promotional name such as “free shipping.” Use explicit schema fields and authoritative business intent. --- ## Subscription Renewal and Trial Context The RevCent Discount model can relate to Subscriptions, Subscription Renewals, and Trials. The Knowledge Base states that a manual Discount or Coupon can apply during an initial Sale, Subscription Renewal, or Trial expiration. For operational investigation: 1. Retrieve the Discount. 2. Inspect the returned relationship IDs. 3. Use `GetSubscription`, `GetSubscriptionRenewal`, or `GetTrial` only for the relevant exact ID. 4. Use BigQuery for cohort, recurring-revenue, or trial-conversion analysis. Do not assume that a Discount applies to all future renewals. Coupon and subscription settings determine lifecycle scope. --- ## Customer, Campaign, and Shop Context Discount retrieval can expose or filter by Customer, Campaign, and Third Party Shop context. Use these relationships for narrow operational questions, such as identifying the Discount on a known Customer's purchase. Use BigQuery for cross-customer, cross-Campaign, or cross-Shop analysis. Always respect authorization when returning Customer details. Only retrieve or disclose the fields needed for the user's request. --- ## Live Mode and Test Mode Discounts can be created in live or test commerce flows. For operational work, make sure the selected Discount belongs to the intended environment. For reporting, separate `live_mode = true` from test records unless the user explicitly requests a test-data analysis. Combining live and test Discounts can overstate promotional cost and distort conversion, product, and recurring-revenue analysis. --- ## Best Practices 1. Treat a discount entry and the created Discount item as different stages of the lifecycle. 2. Use exact Discount IDs from authoritative RevCent results. 3. Use `GetDiscounts` only for bounded operational retrieval. 4. Use `GetDiscount` for the selected record and follow related IDs only as needed. 5. Use `EstimateSale` when totals should be reviewed before payment. 6. Confirm authority, type, value, and scope before creating a Sale with a Discount. 7. Never guess Coupon validity or applicability. 8. Treat RevCent's returned calculated amount and percentage as authoritative. 9. Use `BigQueryRunQuery` for aggregation, trends, rankings, and broad analysis. 10. Separate live and test records and avoid mixing currencies in monetary totals. 11. Do not treat a Discount as a refund. 12. Avoid exposing unnecessary Customer or payment context when answering a narrow request. --- ## Common Mistakes to Avoid - Calling a manual input entry a persisted Discount before the Sale is processed. - Calling a Coupon and its resulting Discount the same object. - Looking for a standalone `CreateDiscount` operation. - Creating or promising an unauthorized reduction. - Guessing whether the intended type is `amount` or `percent`. - Omitting explicit Product or Shipping scope when the user's intent is limited. - Copying example IDs or timestamps into live calls. - Looping through every `GetDiscounts` page to answer an analytical question. - Recalculating the Discount from partial data and overriding the API result. - Mixing currencies or live/test data in reports. - Assuming a Discount applies to every future Subscription Renewal. - Treating a post-payment refund as a Discount. --- ## AI/MCP Decision Guide | User Intent | Recommended Action | |---|---| | “Show me this Discount.” | Use `GetDiscount` with the exact ID. | | “Find recent Discounts for this Customer.” | Use `GetDiscounts` with a narrow date range and `customer_id`. | | “Which Discount changed this Sale?” | Retrieve the Sale, use its exact `discounts` ID, then call `GetDiscount`. | | “Apply 10% to this new Sale.” | Verify authority and scope, consider `EstimateSale`, then use the appropriate Sale creation flow. | | “Use this Coupon on the Sale.” | Validate or apply the authoritative Coupon through the Sale workflow; do not invent validity. | | “How much did we discount last quarter?” | Use `GetBigQueryTables`, then `BigQueryRunQuery`. | | “Which Coupon performs best?” | Use BigQuery Discount and Coupon relationships with a clearly defined performance metric. | | “Refund the amount we charged.” | Use the appropriate refund workflow, not Discount creation. | --- ## Final AI/MCP Instruction Treat a Discount as a historical commerce item created from an applied Sale discount entry or Coupon. Use `GetDiscounts` for narrow, bounded discovery and `GetDiscount` for one exact record. Follow returned relationship IDs with the matching single-record operation only when needed. When the user wants a new Sale with a reduction, verify the exact authorization, type, value, and Product/Shipping scope, and use `EstimateSale` before payment when totals need review. Use `BigQueryRunQuery` for all Discount reporting, aggregation, and broad analysis. --- 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.