# OpenMeter MCP > OpenMeter connects your AI agent directly to a high-performance billing system. It lets you track usage events, manage customer access limits, and automate subscription billing for any cloud service or API. You can handle everything from initial user sign-up (`create_customer`) to recording token counts (`ingest_event`), all without manual dashboard intervention. ## Overview - **Category:** cloud-infrastructure - **Price:** Free - **Tags:** usage-metering, ai-billing, cloudevents, finops, saas-billing ## Description You use OpenMeter to run usage-based billing logic right through your AI client. It handles the whole customer life cycle—from defining what gets charged to taking the cash. You don't need some clunky dashboard; you just call the tool. **Defining Your System and Resources** When you start, you gotta define what counts as usage. Use `create_feature` to register a new resource that needs tracking in your billing system. Then, if you’re dealing with multiple entities tied to that feature, use `upsert_subjects` or `delete_subject`. The `upsert_subjects` tool lets you update or add whole batches of subject records at once. If you gotta fix data or clean up an old entry, call `delete_subject` by its unique internal key. **Managing Customers and Usage Tracking** To get started with a new user, you hit the gas on billing setup by calling `create_customer`, which creates that billable record in your metering system. Need to check what a customer's current status is? Just call `get_customer` using their ID or external key; it pulls all their usage and billing details right up. The core of tracking is the `ingest_event` tool: you send raw data—like 150 tokens used or how many API calls were made—and that tool immediately records that specific usage event, keeping your consumption totals accurate. To set hard limits for a customer on a feature, use `create_entitlement`. This sets up the specific quota or access rights they're allowed. **Billing and Payment Orchestration** When it comes to money, OpenMeter handles all the complexity. You link customers to recurring charges by calling `create_subscription`, which manages their entire billing cycle. If you need them to pay now for a one-time service or renew immediately, use `create_stripe_checkout` to start that payment session on Stripe. These tools manage collecting funds and starting paid subscriptions right from your agent’s workflow. You can also define the specific access rules by calling `create_feature` first, then linking those rights to an existing customer via `create_entitlement`. If you need a brand new billing structure or service that wasn't planned for, run through `create_feature` to register it. **The Workflow in Action** Your agent acts like your dedicated billing specialist. You let the client call `get_customer` to verify data. Then, when usage happens, you fire off an `ingest_event`. The system uses that event count and compares it against the limits set up by a prior call to `create_entitlement`. If everything looks good, you can then initiate the whole payment process with `create_stripe_checkout`, or if they're on a recurring plan, you trigger `create_subscription`. ## Tools ### create_customer Creates a new billable customer record within the metering system. ### create_entitlement Sets up specific usage limits or access rights for an existing customer regarding a feature. ### create_feature Defines and registers a new, measurable resource that can be tracked in the billing system. ### create_stripe_checkout Initiates a payment session on Stripe for collecting funds or starting a paid subscription. ### create_subscription Links an existing customer to a specific, recurring billing plan. ### delete_subject Removes a subject (a tracked entity) by its unique internal key for cleanup or data correction. ### get_customer Retrieves full billing and usage details for a customer using their ID or external key. ### ingest_event Records a specific usage event (e.g., 150 tokens used) into the metering pipeline, updating consumption totals. ### upsert_subjects Updates or adds multiple subject records simultaneously in OpenMeter's data store. ## Prompt Examples **Prompt:** ``` Ingest a 'tokens' event for subject 'cust_99' with 150 tokens from source 'gpt-wrapper'. ``` **Response:** ``` I've successfully ingested the usage event. Event ID: `evt_01H...`. 150 tokens have been recorded for customer `cust_99`. ``` **Prompt:** ``` Create a new feature called 'Image Generation' with key 'img_gen' and meter slug 'images_total'. ``` **Response:** ``` Feature 'Image Generation' (img_gen) has been created and linked to the 'images_total' meter. You can now assign entitlements for this feature to your customers. ``` **Prompt:** ``` Get the details for customer with key 'acme-corp-001'. ``` **Response:** ``` Retrieved customer: ACME Corp (ID: `cust_abc123`). Usage is attributed to subjects: `['acme-corp-001']`. ``` ## Capabilities ### Ingest Usage Events Record raw usage data (e.g., token count, API calls) using `ingest_event` so your billing records stay accurate. ### Manage Customer Profiles Create new billable customer accounts via `create_customer` or check existing user details with `get_customer`. ### Define Feature Limits and Rights Set specific usage quotas or access rights for a feature using `create_entitlement` or define the resource itself with `create_feature`. ### Orchestrate Subscriptions Link customers to payment plans by calling `create_subscription`, which manages their billing cycle. ### Process Payments Start the checkout process for a customer using `create_stripe_checkout` to collect payments immediately. ## Use Cases ### A user hits their token limit. The system detects high usage. Instead of showing a generic error, the agent runs `get_customer` to check the remaining balance and then calls `create_entitlement` to inform the user they need to upgrade, prompting them for payment via `create_stripe_checkout`. ### Onboarding a new enterprise client. The sales team signs Acme Corp. The agent first runs `create_customer`, then defines their specific usage rules with `create_entitlement`, and finally executes `create_subscription` to start the billing cycle. ### Tracking API call volume. Every time the service makes an external API call, it runs `ingest_event` with the source and count. This logs the event data—for example, 50 calls from 'GPT-wrapper'—keeping a perfect audit trail. ### Removing old or incorrect usage records. A billing correction is needed for an old client. The agent uses `delete_subject` to remove the erroneous data, ensuring future reports are accurate and compliant. ## Benefits - Stop relying on manual dashboard checks. By calling `ingest_event`, you instantly update the customer's consumption record, ensuring that usage-based limits are enforced in real time. - Onboard new users faster than ever. Use `create_customer` and then immediately call `create_entitlement` to define their access rights, all through a single agent conversation. - Collect payments seamlessly. The `create_stripe_checkout` tool handles the payment initiation flow, allowing your AI client to guide the user right from the usage warning screen. - Manage feature definitions in code. Product Engineers use `create_feature` to register new resources—like 'Image Generation'—and immediately follow up with `create_entitlement` to meter it. - Query billing data naturally. You can ask your agent for a customer's status (using `get_customer`) and get the usage details back, instead of building complex SQL queries. ## How It Works The bottom line is: Your AI client handles billing operations by making specific API calls when needed, keeping your entire system auditable. 1. First, subscribe to the OpenMeter server and provide your API Key. 2. Next, when a user performs an action (like making an API call), tell your AI client to run `ingest_event` with the usage data. 3. Finally, if the usage hits a limit, prompt the agent to use `get_customer` or `create_entitlement` to check status and manage access. ## Frequently Asked Questions **How does OpenMeter use `ingest_event`?** `ingest_event` records a usage event (like token counts) directly into the metering pipeline. You pass it the subject key, the metric type, and the count used. **Can I create a new feature using `create_feature`?** Yes. Calling `create_feature` registers a new resource (e.g., 'Video Generation') in your system's billing catalog so you can start tracking usage for it. **Do I need to call `get_customer` before creating a subscription?** It’s best practice. Use `get_customer` first to verify the customer exists and get their current ID or key, ensuring your `create_subscription` call targets the correct record. **What is the difference between `create_entitlement` and `create_feature`?** `create_feature` registers the resource (the 'what'). `create_entitlement` defines how much of that resource a customer can actually use (the 'how much'). **How do I start billing for a user using OpenMeter?** You first run `create_customer`. Then, you define their access with `create_entitlement`, and finally, initiate payment flow by calling `create_stripe_checkout`. **What is `upsert_subjects` and how does it handle multiple customer accounts?** It creates or updates several subject profiles in a single API call. You provide an array of subject objects, letting your agent set up many customers efficiently without calling `create_customer` repeatedly. **How do I use `create_stripe_checkout` to handle customer payments?** This tool generates a secure Stripe checkout session URL. Your AI client uses this link, allowing the user to pay immediately and start a new subscription without needing manual dashboard intervention. **When should I use `delete_subject` instead of just updating data?** Use this tool when you need to fully decommission a customer profile. It removes the subject entirely by key, which is necessary for maintaining accurate billing records and cleaning up old data. **How do I record that a user just consumed 500 tokens in an AI prompt?** Use the `ingest_event` tool. Provide the event type (e.g., 'prompt'), the subject (customer ID), and a JSON payload containing the count (e.g., `{"tokens": 500}`). OpenMeter will handle the aggregation automatically. **Can I check the current status and metadata of a specific billable customer?** Yes! Use the `get_customer` tool with the customer's ID or Key. It will return the customer's name, usage attribution settings, and internal identifiers. **How do I set a usage limit or entitlement for a customer?** Use the `create_entitlement` tool. You'll need the `customerId` and a JSON configuration defining the feature and the limit (e.g., a hard limit of 1000 units per month).