From d470ea1860b812831a4bfc20f9d04d45e52ec435 Mon Sep 17 00:00:00 2001 From: "Dave (translate via Sonnet 4.6)" Date: Mon, 6 Jul 2026 14:17:40 -0600 Subject: [PATCH] docs: document metered AI usage --- docs/addons/gratis-ai-agent/index.mdx | 6 + .../metered-plans/ai-usage-metering.mdx | 193 ++++++++++++++++++ docs/addons/metered-plans/changelog.md | 19 ++ .../hooks/Filters/wu_ai_token_rates.md | 31 ++- .../wu_connector_enforcement_option_keys.md | 17 +- docs/addons/metered-plans/index.mdx | 27 ++- .../index.mdx | 6 + .../ultimate-ai-connector-webllm/index.mdx | 6 + 8 files changed, 292 insertions(+), 13 deletions(-) create mode 100644 docs/addons/metered-plans/ai-usage-metering.mdx diff --git a/docs/addons/gratis-ai-agent/index.mdx b/docs/addons/gratis-ai-agent/index.mdx index bd9b969a50..ca343add54 100644 --- a/docs/addons/gratis-ai-agent/index.mdx +++ b/docs/addons/gratis-ai-agent/index.mdx @@ -106,6 +106,12 @@ All settings are under **Gratis AI Agent → Settings** in the WordPress admin: | **Ability Timeout** | Maximum seconds an individual ability can run (default 30) | | **Debug Logging** | Log ability calls and agent reasoning to the WordPress debug log | +## Metered AI Usage + +On multisite networks, Gratis AI Agent can be paired with [Metered Plans AI Usage Metering](../metered-plans/ai-usage-metering) so customer sites receive an included AI allowance and pay for usage above that allowance. + +When Metered Plans is active, AI requests made through the WordPress AI Client SDK can be attributed to the current subsite, customer, membership, provider, and model. The AI Agent UI can also use the Metered Plans payment-method status endpoint to warn no-card customers before they reach their AI allowance. + ## Options Management Safety Blocklist The Options Management ability includes a built-in blocklist that prevents the agent from reading or writing sensitive WordPress options. The default blocklist covers: diff --git a/docs/addons/metered-plans/ai-usage-metering.mdx b/docs/addons/metered-plans/ai-usage-metering.mdx new file mode 100644 index 0000000000..fdaaa88451 --- /dev/null +++ b/docs/addons/metered-plans/ai-usage-metering.mdx @@ -0,0 +1,193 @@ +--- +title: "AI Usage Metering" +sidebar_position: 2 +--- + +# AI Usage Metering + +Use AI usage metering when you want to sell AI features to customer sites without absorbing unpredictable provider costs. Metered Plans records each completed AI generation request, converts prompt and completion tokens into a currency value, applies the customer's included allowance, and bills only the overage. + +This works especially well for networks that offer [Gratis AI Agent](../gratis-ai-agent/), OpenAI-compatible connectors, Anthropic/Google/OpenAI OAuth-pool providers, Ollama, or other WordPress AI Client SDK integrations. + +## What You Can Sell + +Common commercial models include: + +| Model | How to configure it | +|---|---| +| Included AI allowance | Give each plan an AI Usage allowance such as 5, 10, or 25 in your site currency per billing cycle. | +| Pass-through usage | Set the AI Usage Overage Markup to `1.0` so customers pay roughly the provider cost above their allowance. | +| Marked-up usage | Set the markup above `1.0`, such as `1.5`, to add margin on overage spend. | +| Premium AI plan | Give higher-tier plans a larger allowance and optionally make more expensive models available by adding rates for them. | +| Free trial with upgrade prompt | Enable Hard Cutoff so customers without a payment method are stopped at the allowance and prompted to add billing details. | + +## How Billing Works + +AI usage is tracked as the `ai_spend` metered resource. + +For every completed AI request, Metered Plans stores: + +- site ID +- customer ID +- membership ID +- provider ID +- model ID +- input tokens +- output tokens +- calculated request cost +- current billing period + +The request cost is calculated from the model's configured rates: + +```text +input_cost = input_tokens / 1,000,000 × input_rate +output_cost = output_tokens / 1,000,000 × output_rate +request_cost = input_cost + output_cost +``` + +At billing time, overage is calculated against the plan allowance: + +```text +billable_overage = max(0, current_ai_spend - allowance) × overage_markup +``` + +### Example + +Suppose a plan includes 10.00 of AI usage per month and charges a `1.5` markup on overage. + +If the customer uses 14.20 of AI provider cost during the billing period: + +```text +overage_spend = 14.20 - 10.00 = 4.20 +billable_overage = 4.20 × 1.5 = 6.30 +``` + +The customer is billed 6.30 as AI Usage overage for that period. + +## Setup Checklist + +### 1. Configure AI Connector Access + +Configure AI providers on the main site or network-approved connector screen before selling AI usage to subsites. + +Metered Plans enforces connector settings from the main site to subsites. Customer sites inherit the approved provider configuration instead of storing their own provider keys. This keeps billing, provider access, and model availability under network-owner control. + +### 2. Configure Per-Model Token Rates + +1. Open **Network Admin → Multisite Ultimate → AI Token Billing**. +2. Review the seeded model rates. +3. Add every model you want customers to be able to use. +4. Enter separate **Input Rate** and **Output Rate** values per 1 million tokens. +5. Save the rate table. + +Use the exact model IDs returned by your connector where possible, such as `gpt-4o`, `gpt-4o-mini`, or `claude-sonnet-4`. + +Metered Plans also supports prefix matching. A rate for `claude-sonnet-4` can match a versioned model ID that starts with that prefix. + +### 3. Enable AI Usage on a Product or Membership + +1. Open the product or membership in Multisite Ultimate. +2. Open the **Metered Plans** section. +3. Enable **Metered Plans**. +4. Enable **AI Usage Metering**. +5. Set the **AI Usage Allowance** in your site currency for each billing cycle. +6. Set **AI Usage Overage Markup**. +7. Decide whether to enable **Hard Cutoff for AI Usage**. +8. Save the product or membership. + +### 4. Test the Customer Path + +Before launching a paid AI plan: + +1. Create or assign a test membership on a customer subsite. +2. Confirm the subsite can use the approved AI provider. +3. Run a small AI request. +4. Open **Dashboard → AI Usage** on the subsite. +5. Confirm current spend, allowance, remaining allowance, token totals, and projected overage update as expected. +6. Test the no-payment-method path if you sell free trials. + +## Hard Cutoff and Payment Methods + +The Hard Cutoff option is designed for free-to-paid conversion. + +When Hard Cutoff is enabled: + +- Customers with no payment method are warned at about 80% of their allowance. +- Customers with no payment method can be blocked once they reach the allowance. +- Blocked customers are prompted to add a payment method through checkout. +- Customers with a payment method can continue using AI and pay overage instead of being blocked. + +This lets you offer a safe free AI allowance while allowing paying customers to keep working without interruption. + +## Model Availability and Unpriced Models + +Only priced models should be available on customer subsites. + +On subsites, Metered Plans filters the AI Agent provider response so unpriced models do not appear in model pickers. It also blocks generation requests for unpriced models at runtime. This prevents a customer from selecting or programmatically requesting a model with no billing rate, which would otherwise produce zero-cost usage. + +Network admins can still see and configure unpriced models on the main site so new models can be added deliberately. + +## Customer Experience + +Customers can open **Dashboard → AI Usage** on their subsite to see: + +- current AI spend for the billing period +- included allowance +- remaining allowance +- overage amount when allowance is exceeded +- usage progress percentage +- input token count +- output token count +- total token count +- last model used +- projected overage based on current usage rate + +The current storage model keeps cumulative token totals for the period and the latest provider/model identifiers on the usage record. Treat detailed per-request or per-model analytics as an operational enhancement rather than a current billing requirement. + +## AI Agent UI Integration + +Metered Plans exposes a REST status endpoint for companion AI interfaces: + +```text +GET /wp-json/sd-metered/v1/payment-method-status +``` + +The response tells the UI whether the current subsite is metered, whether a payment method exists, current usage, allowance, usage ratio, severity, checkout URL, and membership hash. + +Use this endpoint to show in-product warnings before a customer is blocked or to send them directly to checkout to add a payment method. + +## Developer Hooks and Helpers + +Use [`wu_ai_token_rates`](./hooks/Filters/wu_ai_token_rates) to modify the final model-rate table before costs are calculated. + +Use [`wu_connector_enforcement_option_keys`](./hooks/Filters/wu_connector_enforcement_option_keys) when a custom AI provider stores credentials in additional WordPress options that should inherit from the main site. + +Useful helper functions: + +```php +// Current billing-period AI spend for a site. +$spend = wu_get_current_ai_spend($site_id); + +// Cumulative token and cost breakdown for the current period. +$breakdown = wu_get_ai_usage_breakdown($site_id); + +// All rates, or a single model's input/output rates. +$all_rates = wu_get_ai_model_rates(); +$gpt_rates = wu_get_ai_model_rates('gpt-4o'); + +// Whether the current site has reached its configured hard cutoff. +$is_blocked = wu_is_ai_hard_cutoff_active($site_id); +``` + +## Launch Checklist + +Before advertising AI usage as a paid feature, confirm: + +- every customer-facing model has an input and output rate +- unpriced experimental models are hidden from subsites +- each paid plan has an AI Usage allowance +- the overage markup matches your margin target +- Hard Cutoff is enabled for free/no-card plans if you do not want unpaid overage +- payment gateways are configured for recurring and overage billing +- the customer AI Usage dashboard is visible on a test subsite +- the AI Agent payment-method banner can read the metered status endpoint when used diff --git a/docs/addons/metered-plans/changelog.md b/docs/addons/metered-plans/changelog.md index a9b5244c07..45f0c1f8b8 100644 --- a/docs/addons/metered-plans/changelog.md +++ b/docs/addons/metered-plans/changelog.md @@ -5,6 +5,25 @@ sidebar_position: 99 # Metered Plans Changelog +Version 1.5.3 - Released on 2026-05-19 +- Fix: OAuth-pool provider plugins now inherit the main-site provider pool early enough for subsite registration, preventing AI Agent setup gates from appearing when the main site has a valid provider pool. +- Improved: Static AI provider option keys are hooked during plugin load, while dynamic Connectors API keys remain discovered after connector registration. + +Version 1.5.2 - Released on 2026-05-12 +- Fix: Prevented recursion in AI connector option write-through when subsite option updates are redirected to the main site. + +Version 1.5.1 - Released on 2026-05-12 +- Fix: Prevented recursion in main-site AI connector option reads on subsites, avoiding excessive blog switching and memory exhaustion. + +Version 1.5.0 - Released on 2026-05-10 +- New: Payment-method-aware hard cutoff for AI usage. Customers without a payment method can be warned or blocked at the allowance, while customers with a payment method can continue as paid overage. +- New: Subsite admin notices prompt customers to add a payment method before AI usage is interrupted. +- New: REST endpoint for companion AI interfaces at `/sd-metered/v1/payment-method-status`. + +Version 1.4.0 - Released on 2026-05-08 +- New: Unpriced AI models are hidden from subsite model pickers and blocked at generation time, preventing unbilled usage for models without configured rates. +- Improved: Model rate lookup uses the same prefix matching for billing and runtime availability checks. + Version 1.1.0 - Released on 2026-05-05 - New: AI token billing for multisite subsites — track and bill AI token usage across customer sites with configurable per-token rates - New: Connector enforcement rebuilt with dynamic limit discovery and write-through, ensuring real-time accuracy across all connectors diff --git a/docs/addons/metered-plans/hooks/Filters/wu_ai_token_rates.md b/docs/addons/metered-plans/hooks/Filters/wu_ai_token_rates.md index b8e4c90779..dabd533056 100644 --- a/docs/addons/metered-plans/hooks/Filters/wu_ai_token_rates.md +++ b/docs/addons/metered-plans/hooks/Filters/wu_ai_token_rates.md @@ -6,7 +6,14 @@ sidebar_label: "wu_ai_token_rates" # Filter: wu_ai_token_rates -Filter the AI token billing rates. +Filter the AI token billing rates before Metered Plans calculates the cost of an AI request. + +Rates are keyed by model ID. Each model entry contains: + +- `input_rate` — price per 1 million prompt/input tokens in your site currency +- `output_rate` — price per 1 million completion/output tokens in your site currency + +Metered Plans first tries an exact model ID match. If no exact match exists, it can use prefix matching, so a key such as `claude-sonnet-4` can match a versioned ID that starts with that prefix. ## Parameters @@ -14,10 +21,30 @@ Filter the AI token billing rates. |------|------|-------------| | $rates | `array` | Model rates from network option. | +## Example + +```php +add_filter('wu_ai_token_rates', function ($rates) { + $rates['custom-premium-model'] = [ + 'input_rate' => 4.00, + 'output_rate' => 12.00, + ]; + + // Prefix match versioned model IDs such as custom-fast-model-2026-07. + $rates['custom-fast-model'] = [ + 'input_rate' => 0.25, + 'output_rate' => 1.00, + ]; + + return $rates; +}); +``` + +Use this filter when rates come from an external pricing service, when a custom connector exposes model IDs not saved in the network rate table, or when you want to apply temporary pricing changes without editing each product. + ### Since - 1.1.0 ### Source Defined in [`inc/managers/class-ai-usage-listener.php`](https://github.com/Ultimate-Multisite/ultimate-multisite-metered-plans/blob/main/inc/managers/class-ai-usage-listener.php#L266) at line 266 - diff --git a/docs/addons/metered-plans/hooks/Filters/wu_connector_enforcement_option_keys.md b/docs/addons/metered-plans/hooks/Filters/wu_connector_enforcement_option_keys.md index 670c86b189..8a2917ec28 100644 --- a/docs/addons/metered-plans/hooks/Filters/wu_connector_enforcement_option_keys.md +++ b/docs/addons/metered-plans/hooks/Filters/wu_connector_enforcement_option_keys.md @@ -10,16 +10,31 @@ Filter the list of AI provider option keys enforced from the main site. Add option keys for custom or third-party AI provider plugins so their settings are also inherited from the main site on subsites. +This is useful when a custom AI provider stores API keys, endpoint URLs, model defaults, OAuth pools, or other provider settings in WordPress options that are not registered through the Connectors API. Enforcing those keys keeps customer subsites on the network-approved provider configuration while Metered Plans bills usage per subsite. + ## Parameters | Name | Type | Description | |------|------|-------------| | $keys | `string[]` | Option key names to enforce (already includes dynamically discovered connector keys and EXTRA_PROVIDER_OPTIONS). | +## Example + +```php +add_filter('wu_connector_enforcement_option_keys', function ($keys) { + $keys[] = 'my_ai_provider_api_key'; + $keys[] = 'my_ai_provider_endpoint_url'; + $keys[] = 'my_ai_provider_default_model'; + + return $keys; +}); +``` + +After adding keys, configure those options on the main site. Subsites will read the main-site values and write updates back through the main site for enforced options. + ### Since - 1.2.0 ### Source Defined in [`inc/managers/class-connector-enforcement.php`](https://github.com/Ultimate-Multisite/ultimate-multisite-metered-plans/blob/main/inc/managers/class-connector-enforcement.php#L206) at line 206 - diff --git a/docs/addons/metered-plans/index.mdx b/docs/addons/metered-plans/index.mdx index 0e848294e8..f20ec36f7b 100644 --- a/docs/addons/metered-plans/index.mdx +++ b/docs/addons/metered-plans/index.mdx @@ -17,7 +17,7 @@ The Ultimate Multisite: Metered Plans addon transforms how you bill your custome * **Overage Management**: Automatically bill for usage exceeding plan limits * **Usage Tracking**: Monitor customer resource consumption in real-time * **Flexible Pricing**: Set custom rates for different resources (storage, bandwidth, sites, etc.) -* **AI Token Billing**: Track and bill input and output tokens for AI usage across customer subsites +* **AI Usage Metering**: Track, price, limit, and bill AI token usage across customer subsites * **Automatic Invoicing**: Generate invoices automatically when usage thresholds are exceeded * **Usage Reports**: Detailed usage analytics and reporting for customers and administrators @@ -39,19 +39,22 @@ The Ultimate Multisite: Metered Plans addon transforms how you bill your custome ## AI Token Billing -Version 1.1.0 adds AI token billing for networks that offer AI features through the WordPress AI Client SDK. Metered Plans listens for completed AI generation requests, records input and output token counts for the current subsite, and converts those tokens into billable AI spend for the customer's current billing period. +AI token billing lets you sell AI features without absorbing unpredictable provider costs. Metered Plans listens for completed AI generation requests, records input and output token counts for the current subsite, and converts those tokens into billable AI spend for the customer's current billing period. -Use AI token billing when you want to offer AI tools on customer sites without absorbing unpredictable model costs. Each request is attributed to the subsite, customer, membership, provider, and model so administrators can audit usage while customers can see how their AI consumption affects their account. +Each request is attributed to the subsite, customer, membership, provider, and model. You can give each plan an included AI allowance, mark up overage above provider cost, block no-card customers at the allowance, and let customers with a payment method continue using AI as paid overage. + +For the complete setup, pricing, customer-experience, and launch checklist, see [AI Usage Metering](./ai-usage-metering). ### Configure Per-Token Rates AI rates are configured per model as separate input and output rates. Rates are calculated per 1 million tokens, which matches common AI provider pricing pages. -1. In the network admin, open **Multisite Ultimate → Settings → Metered Plans**. -2. Enable AI spend metering for the product or membership that should bill AI usage. -3. Add model rate entries using the model IDs returned by your connector, such as `gpt-4o`, `gpt-4o-mini`, or another OpenAI-compatible model identifier. -4. Enter separate **Input Rate** and **Output Rate** values in your site currency per 1 million tokens. -5. Set the customer's included AI spend allowance and overage behaviour for the plan. +1. In the network admin, open **Multisite Ultimate → AI Token Billing**. +2. Add model rate entries using the model IDs returned by your connector, such as `gpt-4o`, `gpt-4o-mini`, or another OpenAI-compatible model identifier. +3. Enter separate **Input Rate** and **Output Rate** values in your site currency per 1 million tokens. +4. Open the product or membership that should bill AI usage. +5. Enable **Metered Plans** and **AI Usage Metering**. +6. Set the customer's included AI spend allowance and overage markup for the plan. When an exact model ID is not configured, Metered Plans can match by model prefix. For example, a rate configured for `claude-sonnet-4` can apply to timestamped model IDs that start with that prefix. Developers can also adjust the final rate table with the [`wu_ai_token_rates`](./hooks/Filters/wu_ai_token_rates) filter. @@ -63,13 +66,13 @@ AI token billing works with connectors that emit WordPress AI Client SDK generat * [Ultimate AI Connector for WebLLM](../ultimate-ai-connector-webllm/) for browser-native WebLLM usage when requests are routed through the AI Client SDK event flow * AI provider connectors used by [Gratis AI Agent](../gratis-ai-agent/) when the selected provider reports prompt and completion token counts through the SDK -Custom connectors can participate by firing the standard `wp_ai_client_before_generate_result` and `wp_ai_client_after_generate_result` events with model, provider, and token usage metadata. Connector settings are enforced from the main site to subsites so customer sites use the network-approved providers and limits. +Custom connectors can participate by firing the standard `wp_ai_client_before_generate_result` and `wp_ai_client_after_generate_result` events with model, provider, and token usage metadata. Connector settings are enforced from the main site to subsites so customer sites use the network-approved providers and limits. Unpriced models are hidden from subsite model pickers and blocked at runtime. ### Customer Account Usage Customers see AI usage alongside their other metered resources in their account area. The AI spend row shows the current billing-period total derived from recorded prompt and completion tokens, the configured model rates, and any included allowance on the plan. -If a customer has a payment method on file, usage above the included allowance is treated as billable overage. If the plan is configured for a hard cutoff and the customer has no payment method available, AI requests can be blocked once the allowance is reached and the customer is prompted to add payment details before continuing. +If a customer has a payment method on file, usage above the included allowance is treated as billable overage. If the plan is configured for a hard cutoff and the customer has no payment method available, AI requests can be blocked once the allowance is reached and the customer is prompted to add payment details before continuing. Customers can monitor current spend, allowance, remaining allowance, token totals, and projected overage from **Dashboard → AI Usage** on their subsite. ## Supported Resources @@ -112,6 +115,10 @@ Customers can view their current usage in their dashboard and receive optional n AI token usage is priced from the model's configured input and output rates per 1 million tokens. Metered Plans multiplies each request's prompt and completion token counts by those rates, adds the result to the customer's current billing-period AI spend, and applies the plan's allowance or overage rules. +## How do I sell AI usage to customers? + +Create a plan with an included AI Usage allowance, configure model rates, and set the AI Usage Overage Markup. Use `1.0` for pass-through cost recovery or a higher multiplier such as `1.5` to add margin. See [AI Usage Metering](./ai-usage-metering) for the full setup and launch checklist. + ## Can I still use hard limits? Yes, metered billing is optional per product. You can mix traditional hard-limit products with metered products. diff --git a/docs/addons/ultimate-ai-connector-compatible-endpoints/index.mdx b/docs/addons/ultimate-ai-connector-compatible-endpoints/index.mdx index e8df54165f..150a1bfbc4 100644 --- a/docs/addons/ultimate-ai-connector-compatible-endpoints/index.mdx +++ b/docs/addons/ultimate-ai-connector-compatible-endpoints/index.mdx @@ -72,6 +72,12 @@ When a request to the primary provider fails — due to a timeout, rate limit, o Fallback is transparent to the calling plugin or theme — they receive either a successful response or a final error, regardless of how many providers were tried. +### Metered Billing + +Pair this connector with [Metered Plans AI Usage Metering](../metered-plans/ai-usage-metering) when you want to resell OpenAI-compatible usage to customer subsites. + +Metered Plans uses the model IDs returned by this connector to calculate input-token and output-token cost. Add each customer-facing model to **Multisite Ultimate → AI Token Billing**, then enable **AI Usage Metering** on the relevant product or membership. Unpriced models are hidden from subsite model pickers and blocked at runtime. + ### Provider Configuration Reference | Field | Required | Description | diff --git a/docs/addons/ultimate-ai-connector-webllm/index.mdx b/docs/addons/ultimate-ai-connector-webllm/index.mdx index 487271d75a..512c5247a2 100644 --- a/docs/addons/ultimate-ai-connector-webllm/index.mdx +++ b/docs/addons/ultimate-ai-connector-webllm/index.mdx @@ -111,6 +111,12 @@ The addon installs an `apiFetch` middleware that intercepts WordPress REST API r This means plugins and themes that use the standard WordPress `apiFetch` API to call AI endpoints will automatically benefit from the browser-side model when it is available, with no code changes required. +## Metered Usage Notes + +If WebLLM requests are routed through the WordPress AI Client SDK event flow and report token usage, they can be tracked by [Metered Plans AI Usage Metering](../metered-plans/ai-usage-metering). + +Because WebLLM runs in the customer's browser and does not usually create provider API cost, decide whether you want to price it as a premium feature, include it for free, or leave it unmetered. If you do meter WebLLM models, add the model IDs to **Multisite Ultimate → AI Token Billing** so the models remain available on subsites. + ## Hooks and Filters ### Filters