# Togai MCP > Togai handles usage-based billing and metering right through your AI agent. It ingests raw event data, manages customer accounts, defines complex pricing models via rate cards, and instantly checks entitlements. Your agent can check wallet balances, list invoices, or grant credits without leaving the chat window. ## Overview - **Category:** developer-tools - **Price:** Free - **Tags:** usage-based-billing, metering, fintech, revenue-operations, pricing-strategy ## Description Togai handles all usage-based billing right through your AI agent. Your agent ingests raw event data, manages customer accounts, defines complex pricing models using rate cards, and instantly checks entitlements—all without leaving the chat window. **Tracking Usage Events.** You can send single use events using `ingest_event`, or you'll process large volumes of usage data at once with `ingest_batch_events`. To pull aggregated metrics for reporting across specific time ranges, your agent calls `get_metrics`. **Setting Up Customers and Accounts.** When a new client comes in, you can use `create_customer` to set up their legal entity record. You'll establish the dedicated billing side of things by running `create_account`, and if those details change later, your agent uses `update_account`. To keep the customer profile current without touching billing details, it runs `update_customer`. If you need a full picture of all accounts managed in the system, call `list_accounts`; to see every registered client, use `list_customers`. **Defining Billing Logic and Pricing.** To make sure raw usage data translates into actual dollars, your agent first creates how that aggregation must happen by calling `create_usage_meter`. This tool requires you to specify the event type and computation rules for billable units. Next, you define what those billable units cost using `create_price_plan`, which sets up a whole pricing structure (V2). For review, your agent can pull every defined rate card tied to a price plan by calling `list_rate_cards`. If you need specific financial details for an existing account, you'll use `get_account`; to check the basic profile and metadata of any customer, run `get_customer`. **Controlling Access and Features.** Your agent checks if a user can access a feature by calling `check_entitlement`, which verifies access based on their current plan. For a complete view of all usage limits and feature rights tied to an account, you'll use `get_entitlements`. If the client needs more credits in their wallet, your agent manually adds them using `grant_credit`; they can also check how much credit is available right now by calling `get_wallet_balance`. **Auditing and Reviewing Finances.** To see a full history of charges, your agent pulls a paginated list of generated invoices using `list_invoices`, allowing you to filter that data by date or status. If you need all the current financial details for an account, you'll use `get_account`. You can pull detailed usage metrics across timeframes with `get_metrics`. Your agent also handles necessary setup tools: it runs `create_price_plan` to define new cost structures; and while you might get a list of all customers using `list_customers`, your agent uses specific functions like `create_customer` or `update_customer` when the data actually needs changing. You can retrieve the full details for any known account ID with `get_account`; and if you need to verify current feature access, it calls `check_entitlement`. The server exposes a complete set of tools that lets your agent manage everything from raw event ingestion to final invoice review. ## Tools ### check_entitlement Checks if a customer has access to a specific feature based on their plan. ### create_account Creates a new, dedicated billing account within the system. ### create_customer Sets up a new legal entity record for billing purposes. ### create_price_plan Defines and creates a new pricing structure (V2) that determines costs. ### create_usage_meter Establishes how raw usage data must be aggregated to become billable units, requiring type and computation rules. ### get_account Retrieves all financial details for a specific billing account ID. ### get_customer Retrieves the profile and metadata for a specific customer entity. ### get_entitlements Fetches all current feature access rights and usage limits tied to an account. ### get_metrics Pulls aggregated, calculated metrics across specified time ranges for reporting. ### get_wallet_balance Returns the current available credit balance held by a billing account. ### grant_credit Manually adds credits to an existing account's wallet balance. ### ingest_batch_events Accepts and processes a large batch of usage events simultaneously for bulk ingestion. ### ingest_event Sends a single, detailed usage event object to record consumption in real-time. ### list_accounts Retrieves a list of all billing accounts managed under the system. ### list_customers Provides a list of all customer entities registered in the system. ### list_invoices Retrieves a paginated list of generated invoices, allowing filtering by date or status. ### list_rate_cards Shows all defined rate cards associated with a specific price plan for review. ### update_account Modifies existing details on an active billing account, like contact info or status. ### update_customer Updates non-billing profile information for a customer entity. ## Prompt Examples **Prompt:** ``` List the first 10 customers in my Togai account. ``` **Response:** ``` I've retrieved your customer list. You have customers like 'Acme Corp' (ID: cust_123) and 'Globex' (ID: cust_456). Would you like to see details for any of them? ``` **Prompt:** ``` Ingest a usage event for account 'acc_vink_01' with 50 units of 'api_requests'. ``` **Response:** ``` Successfully ingested the event to Togai. The usage has been recorded for account 'acc_vink_01' under the 'api_requests' schema. ``` **Prompt:** ``` What is the current wallet balance for account 'acc_987'? ``` **Response:** ``` The account 'acc_987' currently has a balance of $150.00 available in their wallet. ``` ## Capabilities ### Track Raw Usage Events Send single (`ingest_event`) or bulk batches of raw usage data to record consumption. ### Manage Billing Accounts Create, read, and update customer records and dedicated billing accounts for tracking revenue. ### Define Pricing Logic Set up how raw events are converted into billable metrics using usage meters and price plans. ### Audit Financial Status Retrieve invoice lists, check current wallet balances, or manually apply credits to an account. ### Check Feature Limits Verify if a customer has access to a specific feature and what their remaining usage limits are. ## Use Cases ### Onboarding a New Partner A new enterprise partner signs up. Your agent first runs `create_customer` and then uses `create_account` to establish their billing record. Next, it calls `create_price_plan` to define the tiered rates, completing the setup in minutes. ### Auditing Overages A customer claims they were overcharged for API requests. Instead of manually digging through logs, your agent runs `get_metrics` and cross-references it with `list_invoices` to quickly pinpoint the exact usage period causing the discrepancy. ### Feature Rollout Testing A Product Manager wants to test a limited beta feature. The agent calls `check_entitlement` with specific parameters, confirming that only users assigned the correct entitlement can access the new tool endpoint. ### Processing Daily Usage Data At midnight, your background job doesn't run a dashboard report. It sends all raw logs to `ingest_batch_events`, which automatically triggers the logic defined by `create_usage_meter` and updates the active account balance. ## Benefits - Automate revenue reconciliation. Instead of exporting data to a spreadsheet, ask your agent to `list_invoices` or `get_wallet_balance` directly from the chat. - Handle usage spikes instantly. Use `ingest_event` or `ingest_batch_events` to push raw consumption data and update billing records in real-time. - Control product access granularly. Check a user's current limits using `get_entitlements` before allowing them to use a premium feature, preventing overages. - Simplify account setup. Your agent can create both the customer profile (`create_customer`) and the billing structure (`create_account`) in two steps. - Adjust finances on the fly. Need to fix an error? Use `grant_credit` to apply credits directly, logging the action without touching a GUI. ## How It Works The bottom line is: you use your AI client to talk to the API directly, making complex billing operations feel like simple conversation. 1. First, subscribe your AI client to the Togai server and provide your required API Key. 2. Next, use tools like `create_customer` or `create_account` to set up the billing structure for a new user or product line. 3. Finally, run commands like `ingest_event` or `check_entitlement`. Your agent sends the request, Togai processes it against your defined pricing rules, and you get back real-time financial status. ## Frequently Asked Questions **How do I check if a user can access a premium feature using check_entitlement?** The `check_entitlement` tool validates feature access instantly. You pass the specific feature ID, and it returns true or false based on their current account limits. **Can I list all invoices and filter them by date using list_invoices?** Yes, `list_invoices` supports optional filters. You can narrow down the results to specific date ranges or status types right in your prompt. **What is the difference between get_metrics and ingest_event?** `ingest_event` pushes new, raw data into the system. `get_metrics` pulls calculated totals—it shows you what has been processed and aggregated for reporting. **How do I make a payment adjustment using grant_credit?** Use the `grant_credit` tool, specifying the target account ID and the credit amount. This action logs the credit application directly to the customer's wallet balance. **What data schema does the `ingest_event` tool require for usage tracking?** The `ingest_event` tool requires an event object containing a schemaName, timestamp, accountId, and at minimum attributes. You must provide these fields to ensure accurate record keeping and proper billing attribution. **Should I use `get_metrics` or `ingest_batch_events` for large amounts of historical data?** Use `ingest_batch_events`. This tool is designed to process many usage records at once, which is vastly more efficient than calling single-event APIs. It handles the volume required for bulk history ingestion. **If a customer changes their legal name or address, should I use `update_customer`?** Yes, you use `update_customer`. This function modifies existing records rather than creating duplicates. It's the proper way to maintain clean data while reflecting necessary business changes. **What happens if my API key lacks permissions when I call `get_wallet_balance`?** The call will return an authorization error, indicating insufficient scope. You'll need to check your server credentials and ensure the associated API key has read access to financial data. **How do I verify if a customer has access to a specific feature?** You can use the `check_entitlement` tool by providing the account ID and the feature ID. The agent will return whether the customer is entitled to use that feature based on their current plan. **Can I check the remaining credit balance for a specific account?** Yes, use the `get_wallet_balance` tool with the target account ID. It will retrieve the current balance, including any granted credits or prepaid amounts. **Is it possible to list all invoices for a customer to check payment status?** Absolutely. Use the `list_invoices` tool. You can filter or browse through the generated invoices to see which ones are paid, pending, or overdue.