Every “New …” dialog, explained in plain language

Your company or team name. Purely a label — you can change it later.

Where invoices and billing notices for your MeterFlow account would go. Optional; format is validated, but nothing is sent to verify it.

Which organization the project belongs to. Pre-selected if you already have one active.

The product’s name, e.g. “PixelForge AI”. Shown across the dashboard and in the project switcher.

Free text for your own reference.

A label so you remember where the key is used — “Production backend”, “Staging”, “CI tests”. Has no technical effect.

Live keys start with mf_live_, Test keys with mf_test_ — and they access two fully separate datasets inside the same project. Subscriptions, credits and usage created with a Test key are invisible to Live keys (and vice versa), while your meters and plans are shared, so tests always run against your real billing configuration. Use Test keys for development, staging and CI; Live keys only for real production traffic.

The human-friendly label shown in the dashboard — “Images generated”, “Video render seconds”. For people’s eyes only.

The machine key — and yes, it is stored in the database and matched exactly. When your application reports usage, it sends an event name; MeterFlow looks up the active meter in that project whose event_name is an exact, case-sensitive match. If none exists, the event is rejected with a 404 error (“No active meter found for event …”) and nothing is recorded. Each event name is unique within a project. Convention: lowercase dotted, e.g. image.generated.

How many individual events get combined into one number in usage summaries. See the table below — this is the heart of the meter.

Required for Sum, Max, Min and Unique count; refused on Count, which reads no property. It names a property of your events. For Sum, Max and Min it is where the quantity comes from when your app leaves value out — a meter whose field is seconds reads properties.seconds; a value your app sends always wins, and an event with neither counts as 1. For Unique count it is the property whose distinct values are counted — model, to count the models a customer used.

Free text for your team.

The tier name — “Free”, “Pro”, “Enterprise”. Required; the Create button stays disabled until it’s filled.

Free text, e.g. the marketing one-liner for the tier.

The recurring subscription fee: Price is the amount (0 is fine for a free tier), Currency a code like USD, and Billing period how often it recurs — monthly, yearly, weekly, or one-time. Fixed after creation — editing a plan later cannot change these (create a new plan instead, so existing subscribers’ terms don’t silently change).

Free days at the start of each new subscription. With 14, a new subscriber spends 2 weeks in a “trialing” status before the paid period starts. 0 = no trial.

Whether the plan exists for your customers at all. Left off it is a draft: you can set the price, the limits and the feature keys over several sittings and your API keys never see it — it is absent from the SDK’s plan list, a plan id that leaked answers 404, and nobody can be subscribed to it. New plans are published; switch it off to prepare one in peace and on when it goes on sale. Switching it off again later closes the door to new subscribers without touching the ones already on it.

The on/off perks the plan includes — short keys you invent, like sso or priority-support (lowercase letters, digits, - and _). Your app asks the SDK entitlements.check(customerId, 'sso') and gets yes only for customers on a plan that lists the key. Editable at any time, on new and existing plans; for things you count use a meter limit below instead.

Which measured thing this limit applies to. The dropdown lists the meters you created in this project — nothing more, nothing less. It is not a fixed catalogue: any new product capability just needs a new meter first, and it appears here immediately.

The allowance bundled into the plan’s price, per billing period. “Pro includes 500 images a month” → 500. On a Hard or Soft row a figure is required before the plan can be created — a blank allowance would cap nothing — unless you tick Unlimited below to say that is what you meant. On a Metered row a blank is its own answer: pay-as-you-go from the first unit.

Only on Hard and Soft rows, and the explicit way to say “no cap on this meter”. Ticking it switches Included units off and empties it; leaving it off keeps that figure required. Metered rows have no switch, because there a blank already means something.

The price in credits per unit once the customer goes past the included units — 0.5 means each extra unit costs half a credit from their balance. It belongs to the Metered type only: the form asks for it on a Metered row and hides it on Hard and Soft, and the API refuses a rate on a Hard or Soft row (422). A Metered row with neither included units nor a rate would refuse every unit, so the API refuses that row too (422).

What the SDK’s entitlements.check() answers once the included units are used up — the call your app makes before doing the work. Hard (block) — check() answers no (hard_limit_reached) and your app refuses the action; the customer hits a wall until the next period or an upgrade. Soft (warn) — check() still answers yes, flagged soft_limit_exceeded, so your app lets it through and nudges the customer to upgrade. Metered (charge) — check() answers yes while the customer’s credits cover the extra units, and each extra unit is charged from their balance at the overage rate; when the balance can’t cover it, the answer is no (insufficient_credits). Metered is the “pay-as-you-go” option and the only one that moves money (credits) by itself. A Metered limit is refused on a Max or Min meter (422): a highest or lowest value cannot be billed by the unit. On a Metered row, a spend cap on the customer’s subscription can make check() answer no before the balance runs out (spend_cap_reached). Hard and Soft both fire the limit.reached webhook once per billing period, the first time the line is crossed. In every case MeterFlow keeps recording the events your app sends — the gate is check(), in your code.

Your own identifier for the end customer — any string you choose: a user ID from your database (user-842), an email, a tenant slug. MeterFlow never validates it against anything; whatever you send is who the subscription belongs to. Use the same ID everywhere (subscriptions, credits, usage) or the pieces won’t connect.

Which pricing tier they’re on — the dropdown lists this project’s plans. If the plan has trial days, the subscription starts in “trialing”; otherwise “active”.

Their balance and every ledger line behind it, with Grant and Deduct — the dialogs explained below.

What they used, meter by meter.

The plan they are on and its status, with Cancel or Reactivate.

What their plan grants, feature by feature: what is left of each metered allowance, and the reason a feature is refused, exactly as entitlements.check() would give it.

How many credits to add (Grant) or remove (Deduct). Must be greater than zero — the direction is decided by which button opened the dialog, not by a minus sign.

An optional memo stored on the ledger entry — “Welcome bonus”, “Refund for outage”, “Support goodwill”. Your future self will thank you.

Lasts 60 minutes unless you set expires_in_minutes — 24 hours at most — and cannot be withdrawn before then. It opens one customer’s page, read only: it cannot change anything or show another customer. A link made with a test key (mf_test_…) shows test data, under a Test data badge.

Open a project → Portal: your company name, logo, light / dark / auto theme, colours and corner radius, and the default Buy more URL, Back URL and link lifetime for links that leave them out. One tick applies the look to every project of the organization.

On the Customers table, the Create a portal link row action makes a link for that customer without any code — so does Portal link on their Credits tab.

Must exactly match the event name of an existing, active meter in this project (case-sensitive). That match is how MeterFlow knows which counter this event feeds. No matching meter → the API rejects the event with a 404 and nothing is stored. Check the Meters page for the exact spelling.

Which of your customers did it — same free-form ID string used for subscriptions and credits. Consistency is everything: user-842 and USER-842 are two different customers.

The quantity — optional. Left out, a Sum, Max or Min meter reads it from the event property its aggregation field names (your app sends it under properties), and otherwise the event counts as 1. Its meaning depends on the meter’s aggregation: for a Count meter the value is ignored (each event counts as one occurrence); for Sum it’s the amount to add (42 seconds, 1 300 tokens); for Max/Min it’s the measurement being compared; a Unique count meter counts the distinct values of its aggregation field.

Where MeterFlow sends the events, e.g. https://api.acme.dev/meterflow.

Which events this endpoint hears about: usage.recorded, credit.granted, credit.deducted (a deduction, or a metered usage charge — its transaction_type says which), subscription.created, .updated, .renewed and .canceled, limit.reached, cap.reached, balance.exhausted, and the two below.

A balance, in credits. Set it and the endpoint also receives balance.low when a customer’s balance drops below it and balance.topped_up when it climbs back over; clear it and both stop. The two events come and go with the threshold, because without a line an endpoint cannot be told about a crossing.

Which of the five your customers pay through.

Live — your provider’s production account, writing live data; Test — its sandbox, writing test data. One connector per provider and account.

The secret your provider signs its webhooks with — for Chargebee, which signs nothing, the username and password it sends instead. It is checked on every call and never shown back: the table shows its last four characters only.

Shown as soon as the connector is created: paste it into your provider’s webhook settings.

Which of your provider’s prices — a product on Polar, a variant on Lemon Squeezy, a plan on Chargebee and Razorpay — puts a customer on which of your plans. An event for a price with no mapping is recorded and changes nothing.

Every event the connector received, with what it did in a sentence: what was applied, and why the rest was ignored.

Where the invitation goes. MeterFlow emails a link that works once, for 7 days, for that address only: the person opens it and joins — from their account, or by creating one through the link.

Admin — organization settings, invitations, API keys, webhooks, connectors, projects and billing. Member — the day-to-day writer: meters, plans and the Subscriptions, Usage and customer pages. Viewer — read-only. There is deliberately no “owner” option: ownership is not handed out by invitation.

Listed on the Members page until accepted, revoked or expired. Revoke stops the link at once.

On each member’s row, for owners and admins. The owner’s membership and your own cannot be changed there. Removing someone takes away their access; their account, and what they created, stays.