AI Token Billing Calculator + Stripe Mapping Sheet

• Why: Currency for all computed prices.
• Default: USD.
• Valid: Any ISO 4217 (e.g., USD, EUR, GBP).

• Why: Global multiplier applied to provider costs to protect margin.
• Default: 2.00 (100% markup).
• Valid: 0.00–10.00.
• Formula usage: effective_unit_price = base_cost * global_markup (before per‑model overrides and overhead).

• Why: Some models deserve different markups.
• Default: blank (inherits global).
• Valid: 0.00–10.00 per row.
• Table columns: [model_id] [token_type] [override_markup].
• Preloaded token_types: input, output, cache (optional).

• Why: Your hard costs per 1K tokens by model and token_type.
• Defaults: blank — fill from your provider’s pricing page.
• Valid range: 0.0000–100.0000 (currency per 1K tokens).
• Table columns:
  • [provider] (e.g., OpenAI, Anthropic, Google, Mistral)
  • [model_id] (exact identifier your app/gateway emits)
  • [input_cost_per_1k]
  • [output_cost_per_1k]
  • [cache_cost_per_1k] (optional; set 0 if unused)
• Note: If a provider prices per token differently (e.g., input vs output), split across the appropriate columns.

• Why: Capture non‑token platform costs (e.g., gateway per‑request fees) as a per‑1K token equivalent.
• Options:
  1. Direct per‑1K entry: [overhead_per_1k] (default 0.00).
  2. Derived from request cost: [gateway_cost_per_request] / [avg_tokens_per_request] * 1000.
• Valid ranges:
  • overhead_per_1k: 0.00–10.00
  • gateway_cost_per_request: 0.000–5.000
  • avg_tokens_per_request: 50–200,000

• Why: Offer monthly included tokens that expire at period end.
• Default: 0.
• Valid: 0–10,000,000 (in 1K‑token units for convenience).
• Two fields:
  • [monthly_free_1k_tokens_total] (applies across all models/types)
  • Optional per‑meter credit: [monthly_free_1k_tokens_by_meter] table.
• Stripe mapping: Configure as a Pricing Plan service action that grants units each period.

• Why: Decide how customers advance through rates.
• Default: volume.
• Valid: flat | volume | graduated.
• Tier table columns (when graduated or volume):
  • [tier_start_1k] (inclusive)
  • [tier_end_1k] (inclusive; use blank for ∞)
  • [discount_pct] (0–100; applied after markup and overhead)

• Why: Friendly price endings and fewer rounding artifacts.
• Default: $0.01.
• Valid: $0.01, $0.05, $0.10.
• Formula: rounded = ROUND(client_unit_price / increment) * increment.

• Why: Ensure your usage events land in the right customer and meter.
• Defaults:
  • [event_name]: ai_tokens
  • [dimension_key_model]: model
  • [dimension_key_token_type]: token_type
  • [customer_id_key]: stripe_customer_id
• Valid: non‑empty strings.
• Notes: Keep keys consistent with your Meter’s "Dimensions" and payload mapping in Stripe Dashboard.

• Optional forecast to sanity‑check margin before shipping rates.
• Fields (per client):
  • [expected_input_1k_tokens]
  • [expected_output_1k_tokens]
  • [expected_cache_1k_tokens] (if used)
• Defaults: 0.
• Valid: 0–100,000,000 per month.

For each [model_id, token_type] row:

1. base = base_cost_per_1k(model_id, token_type)
2. markup = override_markup_or_global(model_id, token_type)
3. price_before_overhead = base * markup
4. unit_overhead = overhead_per_1k (direct) OR (gateway_cost_per_request / avg_tokens_per_request) * 1000
5. pre_tier_unit = price_before_overhead + unit_overhead
6. If tiering = flat: client_unit = pre_tier_unit
   • If volume/graduated: apply [discount_pct] for the tier where usage lands
7. client_unit_rounded = round_to_increment(client_unit)
8. gross_margin_per_1k = client_unit_rounded - (base + unit_overhead)
9. gross_margin_pct = gross_margin_per_1k / client_unit_rounded

Result table columns:

• [provider] [model_id] [token_type] [client_price_per_1k] [gross_margin_pct]

CSV header:

model_id,token_type,currency,unit_amount_decimal,price_type,tier_start_1k,tier_end_1k,rate_card_name

Row rules:

• unit_amount_decimal = client_price_per_1k
• price_type = flat|volume|graduated
• tier_start_1k/tier_end_1k required for volume/graduated; blank for flat
• rate_card_name optional (e.g., "H0 Token Rates v1")

Example rows:

gpt-4o-mini,input,USD,0.3200,volume,0,1000,H0 Token Rates v1
gpt-4o-mini,output,USD,0.4800,volume,0,1000,H0 Token Rates v1
claude-3-haiku,input,USD,0.1500,volume,0,1000,H0 Token Rates v1

Import: Create a Pricing Plan in Stripe, add a rate card, and paste rows or use the API to create prices that reference your Meter.

CSV header:

dimension_key,allowed_value

Populate with every distinct value your gateway/app will emit so UI filters and alerts work.

Example rows:

model,gpt-4o-mini
model,claude-3-haiku
token_type,input
token_type,output

Dashboard mapping: Meter → Advanced → Dimensions → add model and token_type; paste these values where supported or maintain the list for audits.

Send a meter event per usage chunk (gateway or your app). Use a restricted key with Billing meter events: Write.

HTTP request (v2 synchronous):

POST https://api.stripe.com/v2/billing/meter_events
Headers:
  Authorization: Bearer <restricted_key>
  Idempotency-Key: <uuid-per-client-interval-or-message>
Body (application/json):
{
  "event_name": "ai_tokens",
  "payload": {
    "stripe_customer_id": "cus_123",
    "value": 523,
    "timestamp": "2026-04-13T17:05:00Z",
    "model": "gpt-4o-mini",
    "token_type": "input"
  }
}

Notes:

• value = tokens (not 1K units). Stripe aggregates to your Meter.
• Send a second event for token_type":"output" when applicable.
• Backfill: include historical timestamp within your billing window.

n8n Stripe node → "Create Meter Event"

• Authentication: Restricted API Key (scoped to Meter Events Write)
• Fields:
  • event_name: ai_tokens
  • payload.stripe_customer_id: from CRM lookup
  • payload.value: aggregated tokens (integer)
  • payload.timestamp: ISO8601
  • payload.model: model id
  • payload.token_type: input|output|cache
• Idempotency: set Idempotency-Key header via node options to a stable hash of [customer_id, model, token_type, yyyy-mm-dd-hh].
• Schedule: cron hourly or daily per client.

Make (HTTP module) — POST to /v2/billing/meter_events

• Method: POST
• Headers: Authorization Bearer <restricted_key>; Idempotency-Key <hash>; Content-Type application/json
• Body: same as JSON example
• Error handling: retry 429/5xx with exponential backoff.

Show customers that included units apply and what’s next on invoice.

Per client calculator:

net_billable_1k = max(0, (input_1k * price_in + output_1k * price_out + cache_1k * price_cache) - free_credits_1k * blended_unit_price)
projected_invoice = platform_fee_min + net_billable_1k
gross_margin_estimate = projected_invoice - (input_1k * base_in + output_1k * base_out + cache_1k * base_cache) - (total_1k * overhead_per_1k)

Tips:

• Use the Pricing Plan "Upcoming invoice" preview in Dashboard to validate numbers against your sheet before go‑live.
• Enable Smart Retries in Billing → Revenue recovery to harden cash collection (no code).

Use when you want automatic two‑event metering (input/output) per AI call.

Headers to set on each request through the gateway:

• stripe-customer-id: <cus_123>
• authorization: Bearer <restricted_key_with_meter_events_write>

Behavior:

• Gateway emits two billing.meter_event payloads to Stripe with model and token_type populated.
• Your Meter must define Dimensions model and token_type to match.

Sheet mapping:

• Keep model_id values identical to what the gateway returns (e.g., gpt-4o-mini).
• Prices from the Rate Card CSV will align 1:1 with model + token_type.

• Meter: aggregation = sum; Dimensions: model, token_type.
• Pricing Plan: create rate card, attach Meter, choose price type and tiers.
• Service action: grant [monthly_free_1k_tokens_total] units per period (optional).
• Alerts: configure 50/80/100% usage webhooks; route to Slack.
• Keys: use a restricted API key limited to Meter Events Write.
• Preview: validate a test customer’s upcoming invoice before inviting real clients.
• Preview status: Token Billing is private preview (April 2026). If not enabled, this sheet still works via standard Meters + Pricing Plans.