MeterFlow Hier starten: das große Ganze
MeterFlow beantwortet für dein Produkt genau eine Frage: „Wer hat wie viel wovon genutzt — und was kostet ihn das?“ Alles im Dashboard existiert, um diese Frage zu beantworten.
user-842 oder eine E-Mail).Wie die Teile zusammenspielen
Warum sind manche „Erstellen“-Buttons ausgegraut?
Jeder Dialog deaktiviert seinen Bestätigen-Button, bis alle Pflichtfelder (mit * markiert) ausgefüllt sind — z. B. bleibt „Create plan“ deaktiviert, bis der Plan einen Namen hat. Wenn ein Button festzuhängen scheint, suche weiter oben nach einem leeren Pflichtfeld.
Neue Organisation Container
Der äußerste Container — normalerweise dein Unternehmen. Alles andere (Projekte, Meter, Pläne…) lebt innerhalb einer Organisation. Eine hast du bei der Registrierung automatisch bekommen.
📍 Dashboard → der Button „New organization“ (wird auch beim ersten Login angeboten, wenn du noch keine hast)
- Name *
Der Name deines Unternehmens oder Teams. Reines Etikett — du kannst ihn später ändern.
- Billing email
Wohin Rechnungen und Abrechnungshinweise für dein MeterFlow-Konto gehen würden. Optional; das Format wird geprüft, aber es wird nichts zur Bestätigung verschickt.
finance@acme.dev. Ihre zwei Produkte werden darin zu zwei Projekten.Neues Projekt Container
Ein Projekt = ein Produkt oder eine Umgebung, die du messen willst. Jeder Meter, Plan, API-Schlüssel, Kundensaldo und jedes Nutzungsereignis gehört zu genau einem Projekt — Projekte sehen niemals die Daten der anderen.
📍 Dashboard → der Button „New project“ im Kopf der Projects-Tabelle
- Organization *
Zu welcher Organisation das Projekt gehört. Vorausgewählt, wenn bereits eine aktiv ist.
- Name *
Der Produktname, z. B. „PixelForge AI“. Erscheint überall im Dashboard und im Projektumschalter.
- Description
Freitext für deine eigene Referenz.
API-Schlüssel erzeugen Zugang
Der Berechtigungsnachweis, mit dem deine Anwendung mit MeterFlow spricht. Dein Backend übergibt ihn dem SDK; jedes Nutzungsereignis, jede Credit-Operation und jeder Abonnement-Aufruf wird durch diesen Schlüssel authentifiziert — und auf genau ein Projekt begrenzt.
📍 Projekt öffnen → API Keys → der Button im Tabellenkopf
- Key name *
Ein Etikett, damit du weißt, wo der Schlüssel verwendet wird — „Produktions-Backend“, „Staging“, „CI-Tests“. Ohne technische Wirkung.
- Environment
Live-Schlüssel beginnen mit
mf_live_, Test-Schlüssel mitmf_test_— und sie greifen auf zwei vollständig getrennte Datensätze im selben Projekt zu. Abonnements, Guthaben und Verbrauch, die mit einem Test-Schlüssel erzeugt wurden, sind für Live-Schlüssel unsichtbar (und umgekehrt), während Meter und Pläne geteilt werden — Tests laufen also immer gegen deine echte Abrechnungskonfiguration. Nutze Test-Schlüssel für Entwicklung, Staging und CI; Live-Schlüssel nur für echten Produktionsverkehr.
mf_live_a1b2… und legst ihn in die Umgebungsvariablen deines Servers: new MeterFlow({ apiKey: process.env.METERFLOW_KEY }). Die Dashboard-Liste zeigt für immer nur das Präfix und die letzten 4 Zeichen.Neuer Meter Kernkonzept
Ein Meter ist die Definition eines benannten Zählers: Er erklärt eine Sache in deinem Produkt für messenswert und legt fest, wie rohe Ereignisse in eine Zahl verwandelt werden. Stell ihn dir wie eine neue Spalte in einem Nutzungsbericht vor, bevor es überhaupt Daten gibt.
📍 Projekt öffnen → Meters → der Button im Tabellenkopf
- Name *
Das menschenfreundliche Etikett im Dashboard — „Erzeugte Bilder“, „Video-Render-Sekunden“. Nur für menschliche Augen.
- Event name *
Der Maschinenschlüssel — und ja, er wird in der Datenbank gespeichert und exakt abgeglichen. Wenn deine Anwendung Nutzung meldet, sendet sie einen Ereignisnamen; MeterFlow sucht in dem Projekt den aktiven Meter, dessen
event_nameexakt übereinstimmt, Groß-/Kleinschreibung inklusive. Existiert keiner, wird das Ereignis mit einem 404-Fehler abgelehnt („No active meter found for event …“) und nichts wird erfasst. Jeder Ereignisname ist innerhalb eines Projekts eindeutig. Konvention: klein mit Punkten, z. B.image.generated. - Aggregation type
Wie viele einzelne Ereignisse in den Nutzungsübersichten zu einer Zahl zusammengefasst werden. Siehe Tabelle unten — das ist das Herz des Meters.
- Aggregation field
Pflicht für jeden Typ außer Count. Es benennt, welches numerische Feld des Ereignisses die zu aggregierende Menge trägt — die Antwort auf „Summe wovon?“. In der Praxis sendet deine App die Zahl im
value-Feld des Ereignisses, und genau das wird aggregiert; das Aggregation field dokumentiert, was dieser Wert bedeutet (z. B.seconds,tokens,megabytes), damit jeder, der den Meter liest, die Einheit kennt. Für Count ist es irrelevant — zum Zählen genügt, dass das Ereignis existiert. - Description
Freitext für dein Team.
Die Aggregationstypen, an einem Beispiel
Angenommen, der Kunde user-842 löst diesen Monat 4 Ereignisse mit den Werten 3, 10, 2, 10 aus. Pro Meter wird eine Zahl gemeldet — welche, hängt vom Aggregationstyp ab:
| Typ | Welche Frage er beantwortet | Ergebnis für 3, 10, 2, 10 | Typische Verwendung |
|---|---|---|---|
| Count | Wie oft ist es passiert? (Werte ignoriert) | 4 | Erzeugte Bilder, API-Aufrufe, Exporte |
| Sum | Wie viel insgesamt? | 25 | Gerenderte Sekunden, verbrauchte Tokens, übertragene GB |
| Max | Was war der größte Einzelwert? | 10 | Spitze gleichzeitiger Jobs, größter Upload |
| Min | Was war der kleinste Einzelwert? | 2 | Selten zur Abrechnung — eher Diagnose |
| Unique count | Wie viele verschiedene Werte kamen vor? | 3 (3, 10, 2) | Verschiedene aktive Tage, verschiedene berührte Dokumente |
video.rendered · Aggregation Sum · Aggregation field seconds.Deine App rendert einen 42-Sekunden-Clip für
user-842 fertig und meldet das Ereignis video.rendered mit dem Wert 42. Ein paar Mal wiederholt, zeigt die Nutzungsseite des Kunden eine Zeile: Video render seconds — 3 Ereignisse — 117.Muss der Ereignisname zu dem passen, was meine App sendet? Was passiert bei einem Tippfehler?
Ja — exakt, inklusive Groß-/Kleinschreibung. Der Ereignisname des Meters wird in der Datenbank gespeichert und wirkt wie das Adressetikett für eingehende Ereignisse. Sendet deine App video.render, der Meter heißt aber video.rendered, antwortet die API mit 404 „No active meter found for event 'video.render' in this project“ und das Ereignis wird nicht gespeichert. Das ist Absicht: Ein stiller Tippfehler würde für immer unabgerechnete Nutzung durchsickern lassen. Erst den Meter anlegen, dann Ereignisse mit demselben Namen senden.
Kann ich den Aggregationstyp später ändern?
Nein — nach der Erstellung sind nur Name, Beschreibung und Aktiv-Flag änderbar. Die Aggregation definiert, was die gespeicherte Historie bedeutet; sie rückwirkend zu ändern, würde die Vergangenheit umschreiben. Brauchst du eine andere Rechnung, lege einen neuen Meter mit neuem Ereignisnamen an.
Warum ist „Aggregation field“ im Formular optional, wenn es doch Pflicht sein soll?
Das Formular lässt es leer, weil es nur für Nicht-Count-Typen Pflicht ist — der Server erzwingt diese Regel. Wählst du Sum/Max/Min/Unique count und lässt es leer, wird die Erstellung mit einem klaren Validierungsfehler abgelehnt; bei Count kannst du das Feld komplett ignorieren.
Neuer Plan Kernkonzept
Ein Plan ist eine Preisstufe — „Free“, „Pro für 29 $/Monat“… Er bündelt einen wiederkehrenden Preis mit einer Reihe von Meter-Limits, die festlegen, wie viel jeder gemessenen Funktion inklusive ist und was darüber hinaus passiert. Kunden werden über ein Abonnement an einen Plan gebunden.
📍 Projekt öffnen → Plans → der Button im Tabellenkopf
- Name *
Der Name der Stufe — „Free“, „Pro“, „Enterprise“. Pflicht; der Erstellen-Button bleibt deaktiviert, bis er ausgefüllt ist.
- Description
Freitext, z. B. der Marketing-Einzeiler der Stufe.
- Price / Currency / Billing period
Die wiederkehrende Abogebühr: Price ist der Betrag (0 ist für eine Gratis-Stufe völlig in Ordnung), Currency ein Code wie
USD, und Billing period der Rhythmus — monatlich, jährlich, wöchentlich oder einmalig. Nach der Erstellung fest — späteres Bearbeiten des Plans kann sie nicht ändern (lege stattdessen einen neuen Plan an, damit sich die Konditionen bestehender Abonnenten nicht stillschweigend ändern). - Trial days
Gratistage am Anfang jedes neuen Abonnements. Mit
14verbringt ein neuer Abonnent 2 Wochen im Status „trialing“, bevor die bezahlte Periode beginnt.0= keine Testphase. - Public
Ob der Plan für deine Anwendung über die Planliste des SDK sichtbar ist (z. B. um deine Preisseite zu rendern). Nicht angehakt = intern/versteckt — nützlich für maßgeschneiderte Enterprise-Deals oder Pläne im Entwurfsstadium.
Meter-Limits — der Abschnitt „+ Add limit“
Jede Limit-Zeile verbindet diesen Plan mit einem Meter und beantwortet: Wie viel davon ist inklusive, und was passiert darüber hinaus?
- Meter *
Auf welche gemessene Größe sich dieses Limit bezieht. Das Dropdown listet die Meter, die du in diesem Projekt angelegt hast — nicht mehr, nicht weniger. Es ist kein fester Katalog: Jede neue Produktfähigkeit braucht nur zuerst einen neuen Meter, und er erscheint hier sofort.
- Included units
Das im Planpreis enthaltene Kontingent, pro Abrechnungszeitraum. „Pro enthält 500 Bilder pro Monat“ →
500. - Overage rate
Der Preis in Credits pro Einheit, sobald der Kunde die inkludierten Einheiten überschreitet.
0.5heißt: Jede zusätzliche Einheit kostet einen halben Credit vom Guthaben des Kunden. Nur beim Limit-Typ Metered von Bedeutung. - Limit type
Hard (blockieren) — Nutzung über die inkludierten Einheiten hinaus soll abgelehnt werden; der Kunde stößt an eine Wand. Soft (warnen) — die Nutzung läuft weiter, aber du wirst benachrichtigt und kannst den Kunden zum Upgrade bewegen. Metered (abrechnen) — die Nutzung läuft weiter und jede zusätzliche Einheit wird automatisch zum Mehrverbrauchssatz vom Credit-Guthaben des Kunden abgebucht. Metered ist die „Pay-as-you-go“-Option und die einzige, die von selbst Geld (Credits) bewegt.
USD · Monatlich · 14 Testtage · Public ✓Limit 1: Meter Erzeugte Bilder, inklusive 500, Typ Hard → nach 500 Bildern ist die Erzeugung bis zum nächsten Monat oder einem Upgrade blockiert.
Limit 2: Meter Video-Render-Sekunden, inklusive 1 000, Mehrverbrauch 0,02, Typ Metered → jenseits von 1 000 Sekunden kostet jede weitere Sekunde stillschweigend 0,02 Credits aus dem Guthaben des Kunden.
Warum ist „+ Add limit“ ausgegraut?
Weil das Projekt noch keine Meter hat — ein Limit ist immer eine Obergrenze auf einem Meter; ohne Meter gibt es nichts, woran man es hängen könnte. Der Dialog zeigt den Hinweis „Create meters first to attach limits to this plan.“ Gehe zu Meters → New meter, lege mindestens einen an und öffne diesen Dialog erneut.
Warum zeigt das Meter-Dropdown nur wenige Optionen? Was, wenn mein Produkt etwas Neues hat?
Das Dropdown zeigt schlicht deine eigenen Meter des aktuell gewählten Projekts. In den Demo-Daten sind das zufällig „Upscales processed“, „Video render seconds“ und „Images generated“ — aber diese Liste gehört dir und wächst mit. Sie beschränkt nicht, was Kunden tun können: Kunden wählen nie Meter aus; du definierst Meter für alles, was dein Produkt tut. Morgen ein neues Feature? Lege einen Meter dafür an, und er taucht hier auf.
Warum kann ich Preis oder Limits eines bestehenden Plans nicht bearbeiten?
Absichtlich: Bestehende Abonnenten haben zu diesen Konditionen abgeschlossen, deshalb werden Preis, Währung, Abrechnungszeitraum und Meter-Limits bei der Erstellung eingefroren. Beim Bearbeiten eines Plans lassen sich nur Name, Beschreibung, Testtage, Sichtbarkeit und Aktiv-Flag ändern. Zum Umbepreisen legst du einen neuen Plan an (z. B. „Pro 2026“) und führst neue Kunden dorthin.
Neues Abonnement verbindet Kunde ⇄ Plan
Ein Abonnement bindet einen deiner Kunden an einen Plan. Ab diesem Moment wird seine Nutzung an den Meter-Limits dieses Plans gemessen. In Produktion erstellt dein Backend es üblicherweise per SDK, sobald jemand beim Checkout eine Stufe wählt — der Dialog macht dasselbe von Hand.
📍 Projekt öffnen → Subscriptions → der Button im Tabellenkopf
- Customer ID *
Dein eigener Bezeichner für den Endkunden — eine beliebige Zeichenkette deiner Wahl: eine Nutzer-ID aus deiner Datenbank (
user-842), eine E-Mail, ein Tenant-Kürzel. MeterFlow validiert sie gegen nichts; was du sendest, ist, wem das Abonnement gehört. Verwende überall dieselbe ID (Abonnements, Credits, Nutzung), sonst finden die Teile nicht zueinander. - Plan *
Auf welcher Preisstufe er ist — das Dropdown listet die Pläne dieses Projekts. Hat der Plan Testtage, startet das Abonnement im Status „trialing“, sonst „active“.
user-842 klickt in deiner App auf „Upgrade auf Pro“ → dein Backend ruft subscriptions.create({ customer_external_id: 'user-842', plan_id: … }) auf. Jedes Nutzungsereignis von user-842 wird nun gegen die Limits von Pro geprüft.Was, wenn ein Kunde kein Abonnement hat — gehen seine Ereignisse verloren?
Nein. Ereignisse werden immer gespeichert und erscheinen immer in den Nutzungsübersichten. Aber ohne aktives Abonnement gibt es keine Plan-Limits anzuwenden — nichts wird blockiert, nichts abgerechnet; die Nutzung wird einfach erfasst. Die Abrechnungslogik schaltet sich in dem Moment ein, in dem ein Abonnement existiert.
Credits gutschreiben / abziehen das Guthaben
Credits sind ein vorausbezahltes Guthaben pro Kunde (pro Projekt) — wie ein Portemonnaie oder eine Prepaid-Karte. Du entscheidest, was ein Credit in deiner Preisgestaltung wert ist. „Metered“-Mehrverbrauch bedient sich automatisch aus diesem Guthaben; die beiden Dialoge bewegen Credits von Hand.
📍 Projekt öffnen → Credits → einen Kunden nachschlagen → „Grant“ / „Deduct“
- Amount *
Wie viele Credits hinzukommen (Grant) oder abgehen (Deduct). Muss größer als null sein — die Richtung bestimmt der Button, der den Dialog geöffnet hat, nicht ein Minuszeichen.
- Description
Ein optionaler Vermerk auf dem Journaleintrag — „Willkommensbonus“, „Erstattung wegen Ausfall“, „Support-Kulanz“. Dein zukünftiges Ich wird es dir danken.
user-842 erhält eine Gutschrift von 100 („Willkommensbonus“). Er rendert 2 500 Videosekunden auf einem Plan mit 1 000 inklusive und 0,02 Metered-Mehrverbrauch → 1 500 × 0,02 = 30 Credits werden automatisch abgezogen. Guthaben: 70.Nutzungsereignis erfassen Kernkonzept
Ein Nutzungsereignis = „Dieser Kunde hat gerade diese Sache getan, in dieser Menge.“ In Produktion sendet deine Anwendung sie automatisch über das SDK, tausende Male am Tag; der Dialog existiert, damit du eins von Hand einspeisen kannst — für Tests und Demos.
📍 Projekt öffnen → Usage → einen Kunden nachschlagen → „Record event“
- Event name *
Muss exakt dem Ereignisnamen eines existierenden, aktiven Meters in diesem Projekt entsprechen (Groß-/Kleinschreibung zählt). Über diese Übereinstimmung weiß MeterFlow, welchen Zähler dieses Ereignis speist. Kein passender Meter → die API lehnt das Ereignis mit 404 ab und nichts wird gespeichert. Die exakte Schreibweise findest du auf der Meters-Seite.
- Customer ID *
Welcher deiner Kunden es getan hat — dieselbe frei wählbare ID-Zeichenkette wie bei Abonnements und Credits. Konsistenz ist alles:
user-842undUSER-842sind zwei verschiedene Kunden. - Value
Die Menge, Standard
1. Ihre Bedeutung hängt von der Aggregation des Meters ab: Bei einem Count-Meter wird der Wert ignoriert (jedes Ereignis zählt als ein Vorkommnis); bei Sum ist er die zu addierende Menge (42 Sekunden, 1 300 Tokens); bei Max/Min die zu vergleichende Messgröße; bei Unique count das Ding, dessen verschiedene Werte gezählt werden.
video.rendered → „Video render seconds“. 2. Das Ereignis wird dauerhaft gespeichert (roh — aggregiert wird später, beim Lesen). 3. Im Hintergrund prüft MeterFlow, ob der Kunde ein aktives Abonnement hat und ob dieser Plan ein Limit auf diesem Meter führt. 4. Ist das Limit Metered mit Mehrverbrauchssatz, wird die Belastung (Wert × Satz) vom Credit-Guthaben des Kunden abgebucht und eine Journalzeile geschrieben. 5. Die Nutzungsübersicht auf dieser Seite wird aus den Rohereignissen mit dem Aggregationstyp des Meters neu berechnet.Ich habe ein Ereignis erfasst und einen Fehler bekommen — warum?
Fast immer liegt es am Ereignisnamen: Er stimmt mit keinem aktiven Meter dieses Projekts exakt überein. Der Fehler sagt es wörtlich — „No active meter found for event '…' in this project.“ Kopiere den Ereignisnamen von der Meters-Seite, statt ihn neu zu tippen. Beachte auch: Meter gelten pro Projekt — ein Meter aus einem anderen Projekt zählt nicht.
Wenn meine App eine Anfrage wiederholt, wird das Ereignis doppelt gezählt?
Nicht bei korrekter SDK-Nutzung: Jeder Schreibvorgang akzeptiert einen Idempotenzschlüssel — eine eindeutige Markierung für „genau diese Aktion“. Kommt derselbe Schlüssel zweimal an (ein Retry nach einem Netzwerkschluckauf), erkennt MeterFlow ihn und liefert das ursprüngliche Ergebnis zurück, statt ein Duplikat zu speichern. Der manuelle Dialog sendet keinen — zweimal von Hand auf Record zu drücken erzeugt also wirklich zwei Ereignisse.
Mitglied einladen Team-Zugriff
Fügt deiner Organisation einen Kollegen hinzu, damit er ihre Projekte in diesem Dashboard sehen (oder verwalten) kann. Die Person muss bereits ein MeterFlow-Konto haben — erst die Registrierung, dann die Einladung.
📍 Dashboard → Organizations-Tabelle → Zeilenaktion „Invite member“
- Email *
Die E-Mail, unter der ihr MeterFlow-Konto registriert ist.
- Role
Admin — volle Verwaltung: Projekte, Meter, Pläne, Schlüssel, Mitglieder. Member — das Tagesgeschäft. Viewer — nur lesen. Beachte: Eine „owner“-Option fehlt mit Absicht — Eigentümerschaft lässt sich nicht per Einladung vergeben.
dana@acme.dev als Viewer ein, damit das Finanzteam Nutzung und Salden beobachten kann, ohne Preise ändern zu können.