Metered billing

Metered Billing

Metered billing lets you charge customers based on actual usage rather than a flat seat count. Your software reports a usage event every time a customer performs a billable action — calling an API, exporting a file, generating a report. PermitCore records every event and, with Stripe connected, automatically charges customers at the end of each billing period. No spreadsheets, no manual invoicing.

Recording a usage event — SDK call

POST /api/v1/meter — no authentication required. Rate limited to 60 requests/minute per IP.

curl -X POST https://api.permitcore.dev/api/v1/meter \
  -H "Content-Type: application/json" \
  -d '{"licenseKey":"PERMIT-XXXX-XXXX-XXXX-XXXX","eventName":"api_call","quantity":1}'

await fetch('https://api.permitcore.dev/api/v1/meter', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    licenseKey: 'PERMIT-XXXX-XXXX-XXXX-XXXX',
    eventName:  'api_call',
    quantity:   1
  })
});

import requests
requests.post('https://api.permitcore.dev/api/v1/meter', json={
    'licenseKey': 'PERMIT-XXXX-XXXX-XXXX-XXXX',
    'eventName':  'api_call',
    'quantity':   1,
})

Request fields

Response

{ "recorded": true }

Choosing event names

Event names are normalised to lowercase and matched exactly. Choose them carefully up front — they appear in your Stripe Dashboard, invoices, and customer billing pages.

Meter Usage dashboard

Go to Meter Usage in the admin sidebar. The dashboard shows:

• Total events — sum of all events in the selected period (7 / 30 / 90 days)
• Unique event types — count of distinct event names
• Average events / day — total ÷ days in period
• Daily bar chart — volume per calendar day, useful for identifying traffic spikes
• Event breakdown table — each event type, total count, and share percentage

Buttons at the top of the page:

• Pricing — configure per-event Stripe pricing (see below)
• Stripe Setup — retroactive backfill wizard for existing customers

Stripe Auto-Charge for Metered Usage

Connect PermitCore to Stripe to have customers billed automatically based on their usage — no manual invoicing, no exports, no scripts. When a Store customer triggers their first meter event, PermitCore creates the Stripe mapping and subscription item automatically. You configure prices once and everything else runs itself.

Prerequisites

• A Stripe account (live or test mode)
• Your Stripe Secret Key added to PermitCore under Settings → Company → Payment Settings
• Customers who bought via your PermitCore Store — their Stripe cus_xxx ID is captured automatically on checkout

Step 1 — Configure pricing for each event name

Go to Meter Usage → Pricing. This page shows all event names that have been recorded, plus any you configure in advance.

Click Add Event Price and fill in:

Click Save & Create in Stripe. PermitCore immediately:

1. Calls the Stripe Billing Meters API to create a new Billing Meter with your event name, aggregation formula (sum), and value key (value).
2. Creates a recurring metered Price linked to that meter (monthly interval).
3. Stores the Stripe Price ID (price_xxx) in your database.

You will see a green Stripe status badge next to the event name showing the Price ID. This confirms Stripe is ready.

Step 2 — What happens on the first meter event (fully automatic)

After Step 1, everything else is automatic. Here is exactly what happens when a customer's software calls POST /api/v1/meter for the first time for a given event:

For customers who didn't buy via the Store

If a customer's license was not sold through the PermitCore Store (e.g. sold offline, via a reseller, or via a custom flow), their Stripe customer ID (cus_xxx) is not automatically available. You need to configure the mapping manually.

Go to Licenses → View for the relevant license key. Scroll down to the Stripe Metered Billing card.

You can add multiple mappings per license — one per event name if different events should go to different Stripe customers (rare, but supported).

Retroactive backfill — customers who used meter before setup

If you had customers using POST /api/v1/meter before you configured pricing, those events were already recorded in PermitCore but never forwarded to Stripe. To backfill:

1. Go to Meter Usage → Stripe Setup.
2. The wizard shows all event names with existing meter events, how many licenses are auto-mappable (have Store orders with cus_xxx), and how many need manual setup.
3. Click Backfill Now to auto-create LicenseMeterStripeConfig records for all historical Store-purchased licenses.
4. Any remaining licenses with no cus_xxx are listed in Step 3 of the wizard with direct links to their license detail pages for manual mapping.

End-to-end example — $0.01 per API call

A vendor sells an API gateway product. Customers pay a base subscription plus $0.01 per API call.

client.meter(license_key, "api_call", quantity=1)

How to confirm it actually worked

After sending a test POST /api/v1/meter call, check these three places — in order, since the first one confirms the fastest and the mapping/Stripe steps only run once per customer:

What you see in Stripe Dashboard

After setup, in your Stripe account you can see:

• Billing → Meters — your meter(s) with event name, current period usage, and aggregated totals
• Customers → [customer] → Subscriptions — the subscription now has a metered line item showing usage
• Billing → Invoices — at period end, a draft invoice is generated then auto-paid

Stripe auto-charge API reference