# RevCent Tax Overview for AI/MCP AI/MCP-focused overview for Tax in RevCent. This document explains how tax works in RevCent, how tax records are created, how Tax Profiles drive tax calculation, how refunds should be handled, and how AI/MCP clients should retrieve, configure, and report on tax-related data. --- ## Core Concept A Tax record in RevCent represents tax that was calculated and applied to a commerce event. Tax can be associated with: - Sales, - Product Sales, - Subscription Renewals, - Trial Expiration payments, - customers, - campaigns, - third-party shops, - payment types, - transactions, - PayPal transactions, - Offline Payments, - shipments, - discounts, - refunds, - chargebacks, - fraud detections, - AI workflows, - API calls, - metadata. In plain language: ```text Tax Profile = tax calculation configuration Tax = tax amount calculated/recorded on a transaction-related commerce event RefundTax = refund tax when tax should be partially or fully refunded ``` Tax records are part of the full RevCent commerce model. They are not isolated accounting notes. They are connected to the same Sales, Product Sales, Subscriptions, Renewals, Trials, Payments, Shops, Customers, and Reporting data that make RevCent useful for ecommerce operations. --- ## Related Operation Links | Operation | Link | Purpose | |---|---|---| | `GetTaxes` | | Retrieve a bounded operational list of Tax records. Do not use for reporting/aggregation. | | `GetTax` | | Retrieve one Tax record by ID. | | `RefundTax` | | Refund all or part of a Tax record. | | `GetTaxProfiles` | | Retrieve Tax Profiles. | | `GetTaxProfile` | | Retrieve one Tax Profile by ID. | | `CreateTaxProfile` | `https://revcent.com/documentation/markdown/mcp/operation/CreateTaxProfile.md` | Create a Tax Profile. | | `EditTaxProfile` | `https://revcent.com/documentation/markdown/mcp/operation/EditTaxProfile.md` | Edit an existing Tax Profile. | --- ## Related Overview Links AI/MCP clients should use these related overview files for broader context: | Overview | Link | Why It Matters | |---|---|---| | Sales Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewSale.md` | Sales can include tax as part of the full order/payment lifecycle. | | Product Sales Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewProductSale.md` | Product Sales are line items inside a Sale and can connect to tax. | | Subscription Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewSubscription.md` | Subscription renewals can calculate tax when recurring billing occurs. | | Subscription Renewal Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewSubscriptionRenewal.md` | Renewals can have related tax records and tax reporting needs. | | Trial Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewTrial.md` | Trial expiration payments can calculate tax. | | Shop Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewShop.md` | Third-party shops such as WooCommerce can originate Sales that include tax. | | Offline Payment Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewOfflinePayment.md` | Offline/alternate payment records may relate to tax. | | PayPal Transaction Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewPayPalTransaction.md` | PayPal transactions may relate to Sales/Renewals that include tax. | | BigQueryRunQuery | `https://revcent.com/documentation/markdown/mcp/operation/BigQueryRunQuery.md` | Correct method for tax metrics, reporting, aggregation, and data mining. | --- ## Why Tax Matters in RevCent Tax is a critical component of ecommerce transactions. RevCent Tax records help merchants understand: - tax calculated on Sales, - tax calculated on Subscription Renewals, - tax calculated on Trial Expiration payments, - tax by campaign, - tax by shop, - tax by customer, - tax by payment type, - tax refunds, - tax related to chargebacks or disputes, - tax generated by third-party integrations, - tax by product or product group through related Sale/Product Sale data, - tax performance in BigQuery reporting. For ecommerce businesses, tax is part of the total order economics along with: ```text product amount shipping discounts tax processor fees refunds gross revenue net revenue ``` RevCent keeps tax connected to the full commerce lifecycle so tax can be reviewed operationally and analyzed through BigQuery. --- ## How Tax Is Created Tax records are created when tax is recorded for a transaction-related commerce event. There are two important tax sources: 1. **External shop/storefront tax**, used for initial User Shop / WooCommerce Sales when the shop has already calculated tax. 2. **RevCent Tax Profile tax**, used when RevCent needs to calculate tax internally. For initial WooCommerce/User Shop Sales, the tax calculated by the shop is used instead of Tax Profiles. For Subscription Renewals, Trial Expiration payments, and custom stores/API/hosted flows without external tax calculation, RevCent uses enabled Tax Profiles to calculate tax. Conceptual initial WooCommerce/User Shop Sale flow: ```text Customer checks out in WooCommerce/User Shop ↓ External shop calculates tax ↓ Shop/plugin sends Sale and tax context to RevCent ↓ RevCent stores tax using the shop-provided tax amount/context ``` Conceptual RevCent Tax Profile flow: ```text Subscription Renewal / Trial Expiration / Custom Store payment needs tax ↓ RevCent checks enabled Tax Profiles ↓ Campaign filter is evaluated, if configured ↓ Tax Profile uses associated tax third-party integration ↓ Tax is calculated ↓ Tax record is created and linked to related commerce records ``` Tax records can include the tax amount, calculated rate, tax name, tax description, Tax Profile if applicable, customer, shop, campaign, payment type, currency, and related record IDs. --- ## Critical Rule: User Shop / WooCommerce Initial Sale Tax For initial Sales created from a User Shop / Third-Party Shop such as WooCommerce, tax calculated by the shop is used instead of RevCent Tax Profiles. This is a critical distinction. Correct rule: ```text Initial WooCommerce/User Shop Sale: use tax calculated by the external shop/storefront Subscription Renewal: use RevCent Tax Profiles when tax must be calculated by RevCent Trial Expiration Payment: use RevCent Tax Profiles when tax must be calculated by RevCent Custom Store / API / Hosted / Non-Shop Flow without external tax calculation: use RevCent Tax Profiles when RevCent needs to calculate tax ``` For WooCommerce and other integrated shops, the storefront/cart may already calculate tax during checkout. In that case, RevCent should use the tax amount supplied by the shop for the initial Sale rather than recalculating tax using Tax Profiles. This prevents: - duplicate tax calculation, - mismatched tax totals between WooCommerce and RevCent, - incorrect customer order totals, - refund/accounting discrepancies, - confusion between storefront tax and RevCent-calculated tax. Simple model: ```text WooCommerce checkout calculates initial order tax ↓ WooCommerce / RevCent plugin sends Sale tax to RevCent ↓ RevCent stores the Tax record using the shop-provided tax context ``` Tax Profiles are not the primary tax source for initial WooCommerce/User Shop Sales when the external shop has already calculated tax. --- ## When Tax Profiles Are Used Tax Profiles are used when RevCent needs to calculate tax internally. Primary Tax Profile use cases: | Use Case | Tax Source | |---|---| | Initial WooCommerce/User Shop Sale with shop-calculated tax | External shop tax is used. | | Subscription Renewal | RevCent Tax Profile is used when tax must be calculated by RevCent. | | Trial Expiration Payment | RevCent Tax Profile is used when tax must be calculated by RevCent. | | Custom store without external tax calculation | RevCent Tax Profile is used. | | API-created Sale without provided external tax | RevCent Tax Profile may be used. | | Hosted/custom checkout where RevCent is tax calculator | RevCent Tax Profile may be used. | This distinction matters most for WooCommerce businesses. For WooCommerce: ```text Initial checkout tax = WooCommerce/storefront-calculated Future renewal tax = RevCent Tax Profile-calculated Trial expiration tax = RevCent Tax Profile-calculated ``` This allows WooCommerce to remain the storefront/cart while RevCent remains the backend commerce engine for renewals, trials, refunds, reporting, AI, and lifecycle automation. --- ## Why WooCommerce Initial Tax Is Different From Renewal Tax Initial WooCommerce Sales occur inside the external shop/cart context. WooCommerce may already know: - customer cart, - shipping address, - tax settings, - product tax classes, - coupons, - checkout state, - shipping method, - storefront tax configuration, - external tax plugins/providers used by the store. Because the shop has already calculated the initial checkout tax, RevCent should store and honor that tax for the initial Sale. Subscription Renewals and Trial Expiration payments are different. They happen later inside RevCent, not inside the original WooCommerce checkout session. For those later lifecycle payments, RevCent needs Tax Profiles so it can calculate tax correctly without relying on the initial Sale's tax amount. Important: ```text Do not reuse the initial WooCommerce Sale tax as the tax source for future subscription renewals or trial expirations. ``` Future lifecycle payments need their own tax calculation. --- ## Tax Profiles A Tax Profile is the RevCent configuration that controls tax calculation when RevCent is responsible for calculating tax. A Tax Profile includes: - name, - description, - enabled/disabled state, - optional campaign filters, - required tax-type third-party integration. Simple model: ```text Tax Profile = when/how RevCent should calculate tax Tax record = result of tax being calculated ``` Tax Profiles must be created before RevCent can use that tax calculation configuration for renewals, trial expirations, and custom/non-shop flows that do not provide external tax. They are not used to recalculate initial WooCommerce/User Shop Sale tax when the shop already supplied the tax amount. --- ## Tax Profile Third-Party Integration A Tax Profile requires: ```text third_party_integration ``` The third-party integration must be an existing user third-party integration of type: ```text tax ``` This integration is used for tax calculations. Before creating a Tax Profile, AI/MCP clients should verify: - user has a tax third-party integration, - the integration is the correct tax provider/configuration, - the integration is enabled/ready, - the integration ID is the user third-party integration ID, - the integration type is `tax`. Do not guess the third-party integration ID. Use the appropriate third-party integration listing operation to locate available user integrations before creating or editing a Tax Profile. --- ## Campaign Filters on Tax Profiles Tax Profiles support an optional: ```text campaign_filter ``` The campaign filter is an array of Campaign IDs. If provided: ```text Only RevCent-calculated tax events originating from the specified Campaigns will calculate tax using this Tax Profile. This primarily means Subscription Renewals, Trial Expiration payments, and custom/API/hosted Sale flows where RevCent is responsible for tax calculation. ``` If not provided: ```text All eligible RevCent-calculated tax events will calculate tax using this Tax Profile. This does not override initial WooCommerce/User Shop Sales where tax was already calculated by the external shop. ``` This matters when a business has: - multiple brands, - multiple campaigns, - multiple stores, - different tax configurations, - test vs production campaign differences, - international vs domestic tax strategy, - product-line-specific campaign routing. Example: ```json { "campaign_filter": [ "CCCCCCCCCCCCCCCCCCCC" ] } ``` Use campaign filters carefully because an omitted filter means broad application. --- ## Enabled vs Disabled Tax Profiles Tax Profiles include: ```text enabled ``` If enabled, the profile can be used for tax calculation. If disabled, it should not be expected to calculate tax. Best practice: ```text Create or edit Tax Profiles carefully. Do not enable a Tax Profile until the third-party tax integration and campaign scope are confirmed. ``` Use disabled Tax Profiles for setup/testing when the user is not ready for live calculation. --- ## Tax Records A Tax record can include: | Field / Area | Purpose | |---|---| | `id` | 20-character Tax ID. | | `amount` | Tax amount. | | `rate` | Calculated tax rate. | | `name` | Tax name. | | `description` | Tax description. | | `amount_original_total` | Total calculated amount when item was first created before discounts/refunds. | | `amount_total` | Current total after refunds and discounts. | | `amount_gross` | Money actually transacted. | | `amount_net` | Gross amount minus fees. | | `amount_fees` | Calculated processor fees. | | `amount_captured` | Captured but not yet settled amount. | | `amount_settled` | Settled amount. | | `amount_remaining` | Amount remaining to be processed. | | `amount_refunded` | Refunded amount. | | `amount_to_salvage` | Amount tied to salvage transactions not yet salvaged. | | `campaign_id` / `campaign_name` | Campaign context. | | `customer` | Customer context. | | `iso_currency` | Three-character ISO currency code. | | `live_mode` | Whether record was created with live/test key. | | `payment_type` | Credit Card, PayPal, Offline Payment, or Check. | | `third_party_shop` | Originating shop, if applicable. | | `tax_profile` | Tax Profile that generated the tax, if applicable. | | `metadata` | Custom name/value pairs. | | related IDs | Related Sales, Product Sales, Shipments, Subscriptions, Renewals, Transactions, PayPal, Offline Payments, Refunds, etc. | This structure allows tax to be traced across the full transaction lifecycle. --- ## Tax and Sales Sales can include tax as part of the total order amount. For initial Sales from WooCommerce/User Shops, the shop-calculated tax is used instead of RevCent Tax Profiles. For custom stores, API-created Sales, hosted flows, or other non-shop flows where external tax calculation is not supplied, RevCent can calculate tax if a matching/enabled Tax Profile applies. Tax can then be linked to the Sale and related Product Sales. For ecommerce analysis, this is useful because businesses can understand: - tax collected by sale, - tax by campaign, - tax by shop, - tax by product through Product Sale linkage, - tax by customer, - refund-adjusted tax, - gross/net revenue including tax context. --- ## Tax and Product Sales Product Sales are individual line items within a Sale. Tax records can be connected to Product Sales through related IDs. This is useful because line-item level analysis can help answer: - which products drive the most taxable revenue, - tax collected by product, - tax collected by Product Group, - tax refunded by product, - tax by shippable vs non-shippable products, - tax by WooCommerce product/internal ID. Use BigQuery for these metrics. Do not attempt to aggregate product-level tax by repeatedly calling operational endpoints. --- ## Tax and Subscription Renewals Subscription Renewals can calculate tax using RevCent Tax Profiles. Unlike initial WooCommerce/User Shop Sales, renewals happen later inside RevCent and do not reuse the external shop's initial checkout tax calculation. This is important for recurring revenue businesses because every renewal may need tax handling, not only the initial Sale. Conceptual flow: ```text Subscription renewal date arrives ↓ RevCent calculates renewal payment ↓ Matching Tax Profile applies ↓ Tax record is created for renewal context ↓ Renewal/payment/shipment/reporting records include tax relationship ``` Tax Profile campaign filters can also affect whether subscription renewals calculate tax through a given Tax Profile. For subscription businesses, tax reporting should include: - tax on initial subscription Sales, - tax on Subscription Renewals, - tax refunds on renewals, - tax by Subscription Profile, - tax by subscription product, - tax by shop/campaign, - tax by customer region. Use `BigQueryRunQuery` for these reports. --- ## Tax and Trial Expiration Payments Tax Profiles can also apply to Trial Expiration payments because those payments are calculated later inside RevCent, not as part of the original external shop checkout. This matters when a trial converts or expires into a paid transaction. Conceptual flow: ```text Trial expires / payment is attempted ↓ RevCent calculates payment ↓ Matching Tax Profile applies ↓ Tax record may be created ``` For trial-based ecommerce funnels, this allows tax to be tracked not only at initial trial checkout, but also at the later conversion/expiration payment point where applicable. --- ## Tax and Third-Party Shops / WooCommerce Tax records can include `third_party_shop` context. For WooCommerce and other third-party shops, this allows RevCent to connect tax back to the originating shop. Correct model: ```text WooCommerce = storefront RevCent = backend commerce engine ``` For the initial WooCommerce/User Shop Sale, use the tax calculated by the external shop/storefront. For later RevCent-driven lifecycle payments, such as Subscription Renewals and Trial Expiration payments, use Tax Profiles when RevCent must calculate tax. RevCent should be the backend system for payments, subscriptions, renewals, refunds, reporting, and tax-related commerce context. Tax Profile behavior should be configured carefully for renewals, trial expirations, and custom/non-shop flows where RevCent is responsible for tax calculation. --- ## Tax and Payment Types Tax records can include payment type context: - Credit Card, - PayPal, - Offline Payment, - Check. This allows tax records to remain connected to the type of payment used. This matters for support and reporting because refunds and payment details may differ by payment method. Examples: | Payment Type | Tax Context | |---|---| | Credit Card | Tax may be tied to a card transaction and refund flow. | | PayPal | Tax may be tied to PayPal transaction/refund context. | | Offline Payment | Tax may be tied to alternate/third-party payment providers. | | Check | Tax may be tied to check payment records. | --- ## Tax Refunds Use: ```text RefundTax ``` to refund a Tax record. `RefundTax` requires: ```text tax_id ``` It optionally accepts: ```text amount ``` Behavior: ```text If amount is provided, that amount of tax is refunded. If amount is not provided, the entire tax amount is refunded. ``` Example partial tax refund: ```json { "tax_id": "TTTTTTTTTTTTTTTTTTTT", "amount": 2.50 } ``` Example full tax refund: ```json { "tax_id": "TTTTTTTTTTTTTTTTTTTT" } ``` The output can include: - amount refunded, - tax ID, - pending refund IDs created as a result of the refund, - result message. --- ## When to Refund Tax Refund tax when tax should be returned to the customer as part of a refund workflow. Common cases: - full Sale refund, - partial Product Sale refund where tax needs proportional adjustment, - tax correction, - cancelled taxable item, - customer support-approved refund, - return/refund workflow, - renewal refund that includes tax, - order adjustment requiring tax return. Refunding tax should be coordinated with the broader refund workflow. If refunding a partial order, AI/MCP should consider: - Product Sale refund, - shipping refund, - tax refund, - whether the payment transaction is being refunded, - whether a pending refund is created, - whether accounting/reporting needs metadata or notes. --- ## Tax Refunds vs Other Refunds Tax refunds are separate from Product Sale refunds and Shipping refunds. | Refund Type | Operation | |---|---| | Product line item refund | `RefundProductSale` | | Shipping refund | `RefundShipping` | | Tax refund | `RefundTax` | | Full Sale refund/void | `VoidSale` where applicable | For partial refunds, refunding tax separately can preserve accurate tax and revenue metrics. For full Sale refunds, tax may be part of the full refund workflow depending on the operation and context. AI/MCP clients should read the relevant Sale/Product Sale/Refund overview before creating complex refund workflows. --- ## Operational Retrieval: GetTaxes `GetTaxes` returns a bounded operational list of Tax records. Required input fields: | Field | Purpose | |---|---| | `date_start` | Start date as Unix timestamp in seconds. | | `date_end` | End date as Unix timestamp in seconds. | | `limit` | Number of objects to return. Limit can range from 1 to 25. | | `page` | Pagination page. | Optional filters include: | Filter | Purpose | |---|---| | `campaign_filter` | Filter by Campaign IDs. | | `currency_filter` | Filter by ISO 4217 currency code. | | `shop_filter` | Filter by User Shop IDs. | | `metadata_filter` | Filter by metadata name/value pairs. | | `customer_id` | Filter to records related to a specific Customer ID. | Use `GetTaxes` for bounded operational review. Do not use it for: - tax reporting, - counting, - aggregation, - metrics, - data mining, - bulk retrieval, - document property search. Use `BigQueryRunQuery` for those use cases. --- ## Operational Retrieval: GetTax `GetTax` retrieves one Tax record by ID. Use this when: - the Tax ID is known, - support needs details for a specific tax record, - AI needs to inspect one tax record, - a refund workflow needs exact Tax context, - an automation needs related record IDs. Example: ```json { "tax_id": "TTTTTTTTTTTTTTTTTTTT" } ``` --- ## Tax Profile Retrieval Use `GetTaxProfiles` to retrieve available Tax Profiles. Required input: | Field | Purpose | |---|---| | `limit` | Number of profiles to return. Limit can range from 1 to 25. | | `page` | Pagination page. | Use `GetTaxProfile` to retrieve one Tax Profile by ID. Example: ```json { "tax_profile_id": "TTTTTTTTTTTTTTTTTTTT" } ``` AI/MCP should retrieve and review a Tax Profile before editing it. --- ## CreateTaxProfile Use `CreateTaxProfile` to create a new Tax Profile. Required fields: | Field | Type | Purpose | |---|---|---| | `name` | string | Unique Tax Profile name. | | `third_party_integration` | string | Existing user third-party integration ID of type `tax`. | Optional fields: | Field | Type | Purpose | |---|---|---| | `description` | string | Human-readable explanation. | | `enabled` | boolean | Whether profile is enabled. | | `campaign_filter` | array[string] | Campaign IDs where this profile should apply. | Example: ```json { "name": "Main US Tax Profile", "description": "Tax calculation profile for main ecommerce campaign.", "enabled": true, "campaign_filter": [ "CCCCCCCCCCCCCCCCCCCC" ], "third_party_integration": "IIIIIIIIIIIIIIIIIIII" } ``` If `campaign_filter` is omitted, the Tax Profile applies broadly to eligible RevCent-calculated tax events. This primarily covers Subscription Renewals, Trial Expiration payments, and custom/API/hosted Sales without external tax calculation; it does not recalculate initial WooCommerce/User Shop Sale tax when the shop has already supplied tax. --- ## EditTaxProfile Use `EditTaxProfile` to edit a previously created Tax Profile. Required field: ```text tax_profile_id ``` Only include fields that should be modified. Example name-only edit: ```json { "tax_profile_id": "TTTTTTTTTTTTTTTTTTTT", "name": "Updated Tax Profile Name" } ``` Editable fields: - `name`, - `description`, - `enabled`, - `campaign_filter`, - `third_party_integration`. Important: ```text Only provide the properties you wish to modify. ``` Do not include fields unnecessarily. Changing a Tax Profile can affect future tax calculation for Sales, Subscription Renewals, and Trial Expiration payments associated with its scope. --- ## Tax Profile Setup Workflow Recommended AI/MCP workflow: ```text 1. Confirm user wants to configure tax calculation. 2. Confirm whether the merchant needs Tax Profiles for renewals, trial expirations, or custom/non-shop flows. 3. Confirm initial WooCommerce/User Shop Sales should use shop-calculated tax rather than Tax Profiles. 4. Retrieve available tax-type third-party integrations. 5. Confirm the correct tax integration. 6. Decide whether the profile should apply to all campaigns or specific campaigns. 7. If campaign-specific, retrieve/confirm Campaign IDs. 8. CreateTaxProfile with name, description, enabled state, campaign_filter if needed, and third_party_integration. 9. Test relevant Sale / Subscription Renewal / Trial Expiration payment flow where appropriate. 10. Use GetTaxProfile to verify saved configuration. 11. Use GetTax or bounded operational review to verify created tax records. 12. Use BigQuery for tax reporting. ``` --- ## Tax Profile Edit Workflow Recommended AI/MCP workflow: ```text 1. Retrieve the Tax Profile with GetTaxProfile. 2. Identify what needs to change. 3. Confirm whether the change affects all campaigns or only campaign-filtered activity. 4. Confirm the tax third-party integration if changing it. 5. Confirm enabled/disabled state if changing it. 6. Call EditTaxProfile with only intended fields. 7. Verify with GetTaxProfile. 8. Monitor/test tax calculation where appropriate. ``` --- ## Reporting and Metrics Use: ```text BigQueryRunQuery ``` for all tax reporting, metrics, aggregation, and data mining. Examples of tax reports: - tax collected by day/week/month, - tax collected by campaign, - tax collected by shop, - tax collected by Product, - tax collected by Product Group, - tax collected by payment type, - tax collected by country/state/customer geography, - tax refunds by date, - tax refunds by product, - tax on Subscription Renewals, - tax on Trial Expiration payments, - tax by Tax Profile, - tax by third-party tax integration, - refund-adjusted tax, - tax by live/test mode, - tax associated with chargebacks, - tax recovery/refund trends. Correct operation choice: | Need | Correct Operation | |---|---| | Retrieve one Tax record | `GetTax` | | Retrieve bounded operational Tax list | `GetTaxes` | | Refund a Tax record | `RefundTax` | | Create/edit tax calculation config | `CreateTaxProfile` / `EditTaxProfile` | | Generate tax report/metrics | `BigQueryRunQuery` | Do not use `GetTaxes` for reporting or aggregation. --- ## Example BigQuery Report Ideas Before running production queries, use `GetBigQueryTables` to confirm exact table and column names. ### Tax by Day ```sql SELECT DATE(TIMESTAMP_SECONDS(created_date_unix)) AS tax_day, iso_currency, COUNT(*) AS tax_count, SUM(amount_total) AS tax_amount FROM `revcent.user.tax` WHERE created_date_unix >= UNIX_SECONDS(TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 90 DAY)) GROUP BY tax_day, iso_currency ORDER BY tax_day DESC ``` ### Tax by Campaign ```sql SELECT campaign_id, campaign_name, iso_currency, COUNT(*) AS tax_count, SUM(amount_total) AS tax_amount FROM `revcent.user.tax` GROUP BY campaign_id, campaign_name, iso_currency ORDER BY tax_amount DESC ``` ### Tax by Shop ```sql SELECT third_party_shop.id AS shop_id, third_party_shop.name AS shop_name, iso_currency, COUNT(*) AS tax_count, SUM(amount_total) AS tax_amount FROM `revcent.user.tax` WHERE third_party_shop.id IS NOT NULL GROUP BY shop_id, shop_name, iso_currency ORDER BY tax_amount DESC ``` ### Refunded Tax ```sql SELECT DATE(TIMESTAMP_SECONDS(updated_date_unix)) AS refund_activity_day, iso_currency, COUNT(*) AS tax_records_with_refunds, SUM(amount_refunded) AS refunded_tax_amount FROM `revcent.user.tax` WHERE amount_refunded > 0 GROUP BY refund_activity_day, iso_currency ORDER BY refund_activity_day DESC ``` --- ## AI Assistants and Tax AI Assistants can help with tax-related operational workflows. Examples: - review tax-related refund requests, - summarize tax records for support, - create AI Memos for unusual tax amounts, - detect missing tax on certain campaigns/shops, - run scheduled BigQuery tax reports, - notify support/accounting via Functions, - review Tax Profile configuration before changes, - prepare internal tax/refund summaries. AI Assistants should not provide tax/legal advice. They should use RevCent data and route compliance/accounting questions to the merchant's tax professional. --- ## AI Voice Agents and Tax AI Voice Agents may encounter customer questions involving tax. Inbound examples: - “Why was I charged tax?” - “Can you refund the tax?” - “What tax was applied to my order?” - “Why is my subscription renewal taxed?” - “Was tax refunded?” Voice Agents should: - retrieve the relevant Sale/Tax/Subscription/Renewal context, - explain what RevCent records show, - avoid giving tax/legal advice, - escalate complex tax questions, - only refund tax if the business has explicitly enabled and authorized refund actions. --- ## Tax Compliance Note RevCent provides tools for calculating, storing, refunding, and reporting tax-related transaction data. Tax configuration and tax compliance decisions remain the responsibility of the merchant. AI/MCP clients should not provide legal or tax advice. For questions about whether tax should be charged, tax jurisdictions, exemptions, filings, or legal compliance, direct the user to their tax advisor/accountant or tax provider. --- ## Best Practices 1. Do not use Tax Profiles to recalculate initial WooCommerce/User Shop Sale tax that was already supplied by the storefront. 2. Create Tax Profiles before relying on automatic tax calculation. 3. Verify the third-party integration is type `tax`. 4. Use clear Tax Profile names. 5. Use campaign filters intentionally. 6. Understand that omitted campaign filters apply broadly. 7. Create disabled profiles when still testing. 8. Retrieve and review Tax Profiles before editing. 9. Only include fields being changed in `EditTaxProfile`. 10. Use `RefundTax` for tax-specific refunds. 11. Coordinate tax refunds with Product Sale, Shipping, and Sale refund workflows. 12. Use BigQuery for tax reporting and metrics. 13. Do not use `GetTaxes` for aggregation/data mining. 14. Keep tax records connected to Sales, Renewals, Trials, Shops, Customers, and Payments. 15. Avoid tax/legal advice in AI/voice workflows. 16. Escalate compliance questions to tax professionals. --- ## Common Mistakes to Avoid Do not: - use Tax Profiles to recalculate initial WooCommerce/User Shop Sale tax when the shop already calculated tax, - assume initial WooCommerce Sale tax and renewal tax use the same tax source, - reuse initial Sale tax as the tax source for future Subscription Renewals or Trial Expirations, - create a Tax Profile with the wrong third-party integration, - use a non-tax third-party integration for tax calculation, - omit campaign filters accidentally when the profile should only apply to specific campaigns, - edit a Tax Profile without understanding future calculation impact, - use `GetTaxes` for reporting, aggregation, or bulk data mining, - refund tax without confirming refund context, - forget that tax may apply to Subscription Renewals and Trial Expiration payments, - treat WooCommerce as the tax reporting backend when RevCent is the commerce backend, - provide legal/tax advice through AI/MCP, - assume tax calculation is correct without testing the relevant transaction flow. --- ## AI/MCP Decision Guide | User Intent | Correct Action | |---|---| | Determine initial WooCommerce/User Shop tax source | Use the tax calculated by the external shop/storefront. Do not recalculate with Tax Profiles. | | Configure renewal/trial/custom-store tax calculation | Use `CreateTaxProfile`. | | Create tax calculation configuration | Use `CreateTaxProfile`. | | Edit tax configuration | Retrieve with `GetTaxProfile`, then use `EditTaxProfile`. | | See available profiles | Use `GetTaxProfiles`. | | Retrieve one profile | Use `GetTaxProfile`. | | Retrieve one tax record | Use `GetTax`. | | Review recent tax operationally | Use `GetTaxes` with date range, limit, page, and filters. | | Refund tax | Use `RefundTax`. | | Partially refund tax | Use `RefundTax` with `amount`. | | Fully refund tax | Use `RefundTax` without `amount`. | | Report tax collected/refunded | Use `BigQueryRunQuery`. | | Ask tax compliance/legal question | Escalate to tax advisor/accountant/provider. | --- ## Final AI/MCP Instruction Tax in RevCent is the transaction-level tax record created from tax supplied by an external shop or calculated by RevCent through Tax Profiles. For initial WooCommerce/User Shop Sales, use the tax calculated by the external shop/storefront instead of Tax Profiles. Tax Profiles are for cases where RevCent needs to calculate tax internally, especially Subscription Renewals, Trial Expiration payments, and custom/API/hosted store flows without external tax calculation. Tax Profiles require a tax-type third-party integration and can optionally be scoped to Campaigns. Use `GetTax` for one Tax record and `GetTaxes` only for bounded operational review. Use `RefundTax` to refund tax fully or partially. Use `CreateTaxProfile` and `EditTaxProfile` to configure future RevCent-calculated tax behavior. Use `BigQueryRunQuery` for all tax reporting, aggregation, metrics, and data mining. AI/MCP should not provide tax/legal advice; compliance questions should be directed to the merchant's tax professional or tax provider. --- 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.