Ogni finestra “Nuovo …”, spiegata in parole semplici

Il nome della tua azienda o del tuo team. È solo un’etichetta — puoi cambiarla in seguito.

Dove arriverebbero fatture e comunicazioni di fatturazione per il tuo account MeterFlow. Facoltativa; il formato viene validato, ma non viene inviato nulla per verificarla.

A quale organizzazione appartiene il progetto. Pre-selezionata se ne hai già una attiva.

Il nome del prodotto, es. “PixelForge AI”. Compare in tutta la dashboard e nel selettore di progetto.

Testo libero, per tuo riferimento.

Un’etichetta per ricordarti dove viene usata la chiave — “Backend di produzione”, “Staging”, “Test CI”. Nessun effetto tecnico.

Le chiavi Live iniziano con mf_live_, quelle Test con mf_test_ — e accedono a due set di dati completamente separati nello stesso progetto. Abbonamenti, crediti e utilizzo creati con una chiave Test sono invisibili alle chiavi Live (e viceversa), mentre meter e piani sono condivisi: i test girano sempre sulla tua configurazione di fatturazione reale. Usa le chiavi Test per sviluppo, staging e CI; le Live solo per il traffico reale di produzione.

L’etichetta leggibile mostrata nella dashboard — “Immagini generate”, “Secondi di rendering video”. Serve solo agli occhi umani.

La chiave “per le macchine” — e sì, viene salvata nel database e confrontata alla lettera. Quando la tua applicazione segnala un utilizzo, invia un nome evento; MeterFlow cerca nel progetto il meter attivo il cui event_name corrisponde esattamente, maiuscole/minuscole comprese. Se non esiste, l’evento viene rifiutato con un errore 404 (“No active meter found for event …”) e non viene registrato nulla. Ogni nome evento è unico all’interno di un progetto. Convenzione: minuscolo con punti, es. image.generated.

Come tanti eventi singoli vengono combinati in un unico numero nei riepiloghi di utilizzo. Vedi la tabella qui sotto — è il cuore del meter.

Obbligatorio per Sum, Max, Min e Unique count; rifiutato su Count, che non legge nessuna proprietà. Indica una proprietà dei tuoi eventi. Per Sum, Max e Min è da lì che arriva la quantità quando la tua app omette value — un meter con campo seconds legge properties.seconds; un value inviato dalla tua app vince sempre, e un evento senza nessuno dei due conta 1. Per Unique count è la proprietà di cui si contano i valori distinti — model, per contare i modelli usati da un cliente.

Testo libero per il tuo team.

Il nome della fascia — “Free”, “Pro”, “Enterprise”. Obbligatorio; il pulsante di creazione resta disattivato finché non è compilato.

Testo libero, es. lo slogan della fascia per il marketing.

Il canone ricorrente dell’abbonamento: Price è l’importo (0 va benissimo per una fascia gratuita), Currency un codice come USD, e Billing period la cadenza — mensile, annuale, settimanale o una tantum. Fissi dopo la creazione — modificando il piano in seguito non si possono cambiare (crea piuttosto un nuovo piano, così le condizioni degli abbonati esistenti non cambiano di nascosto).

Giorni gratuiti all’inizio di ogni nuovo abbonamento. Con 14, un nuovo abbonato passa 2 settimane in stato “trialing” prima che inizi il periodo a pagamento. 0 = nessuna prova.

Se il piano esiste per i tuoi clienti. Lasciato spento è una bozza: puoi definirne prezzo, limiti e chiavi funzione con calma e le tue chiavi API non lo vedono mai — è assente dall’elenco piani dell’SDK, un id trapelato risponde 404 e nessuno può esservi abbonato. I nuovi piani nascono pubblicati; spegnilo per prepararne uno in pace e riaccendilo quando va in vendita. Rispegnerlo in seguito chiude la porta ai nuovi abbonati senza toccare quelli già presenti.

Le funzionalità on/off comprese nel piano — chiavi brevi che inventi tu, come sso o priority-support (lettere minuscole, cifre, - e _). La tua app chiede all’SDK entitlements.check(customerId, 'sso') e ottiene sì solo per i clienti abbonati a un piano che elenca quella chiave. Modificabili in qualsiasi momento, su piani nuovi ed esistenti; per le cose che conti usa invece un limite sui meter qui sotto.

A quale grandezza misurata si applica il limite. Il menu elenca i meter che hai creato in questo progetto — niente di più, niente di meno. Non è un catalogo fisso: per ogni nuova funzionalità del prodotto basta creare prima un nuovo meter, e compare qui immediatamente.

La quantità compresa nel prezzo del piano, per periodo di fatturazione. “Pro include 500 immagini al mese” → 500. Su una riga Hard o Soft la cifra è obbligatoria prima di creare il piano — una quantità vuota non limiterebbe nulla — a meno che tu non spunti Unlimited qui sotto per dire che è proprio ciò che intendevi. Su una riga Metered il vuoto è già una risposta: pay-as-you-go dalla prima unità.

Solo sulle righe Hard e Soft, ed è il modo esplicito di dire “nessun limite su questo meter”. Spuntandolo, Included units si disattiva e si svuota; lasciandolo spento, quella cifra resta obbligatoria. Le righe Metered non hanno l’interruttore, perché lì il vuoto significa già qualcosa.

Il prezzo in crediti per unità quando il cliente supera le unità incluse — 0.5 significa che ogni unità extra costa mezzo credito dal suo saldo. Appartiene solo al tipo Metered: il modulo lo chiede su una riga Metered e lo nasconde su Hard e Soft, e l’API rifiuta una tariffa su una riga Hard o Soft (422). Una riga Metered senza unità incluse né tariffa rifiuterebbe ogni unità, quindi l’API rifiuta anche quella riga (422).

Cosa risponde entitlements.check() dell’SDK una volta esaurite le unità incluse — la chiamata che la tua app fa prima di eseguire il lavoro. Hard (blocca) — check() risponde no (hard_limit_reached) e la tua app rifiuta l’azione; il cliente trova un muro fino al periodo successivo o a un upgrade. Soft (avvisa) — check() risponde comunque sì, segnalando soft_limit_exceeded, così la tua app lascia passare e spinge il cliente verso l’upgrade. Metered (addebita) — check() risponde sì finché i crediti del cliente coprono le unità extra, e ogni unità extra viene addebitata dal suo saldo alla tariffa di eccedenza; quando il saldo non basta, la risposta è no (insufficient_credits). Metered è l’opzione “pay-as-you-go” ed è l’unica che muove denaro (crediti) da sola. Un limite Metered viene rifiutato su un meter Max o Min (422): un valore massimo o minimo non si può addebitare a unità. Su una riga Metered, un tetto di spesa sull’abbonamento del cliente può far rispondere no a check() prima che il saldo finisca (spend_cap_reached). Hard e Soft fanno scattare il webhook limit.reached una volta per periodo di fatturazione, la prima volta che la soglia viene superata. In ogni caso MeterFlow continua a registrare gli eventi che la tua app invia — il cancello è check(), nel tuo codice.

Il tuo identificativo per il cliente finale — una stringa qualsiasi scelta da te: un ID utente del tuo database (user-842), un’email, uno slug del tenant. MeterFlow non lo verifica contro nulla; ciò che invii è ciò a cui appartiene l’abbonamento. Usa lo stesso ID ovunque (abbonamenti, crediti, utilizzo), altrimenti i pezzi non si collegano.

Su quale fascia di prezzo si trova — il menu elenca i piani di questo progetto. Se il piano ha giorni di prova, l’abbonamento parte in stato “trialing”; altrimenti “active”.

Il saldo e ogni riga di registro che lo compone, con Grant e Deduct — le finestre spiegate più sotto.

Cosa ha usato, meter per meter.

Il suo piano e lo stato, con Cancel o Reactivate.

Cosa concede il suo piano, funzionalità per funzionalità: quanto resta di ogni allowance a consumo e il motivo per cui una funzionalità è rifiutata, esattamente come lo darebbe entitlements.check().

Quanti crediti aggiungere (Grant) o togliere (Deduct). Deve essere maggiore di zero — la direzione la decide il pulsante che ha aperto la finestra, non il segno meno.

Una nota facoltativa salvata sulla riga del registro — “Bonus di benvenuto”, “Rimborso per il disservizio”, “Cortesia del supporto”. Il te stesso del futuro ringrazierà.

Dura 60 minuti, salvo che tu imposti expires_in_minutes — al massimo 24 ore — e non può essere ritirato prima. Apre la pagina di un solo cliente, in sola lettura: non può modificare nulla né mostrare un altro cliente. Un link creato con una chiave di test (mf_test_…) mostra dati di test, sotto un badge Test data.

Apri un progetto → Portal: nome dell’azienda, logo, tema chiaro / scuro / automatico, colori e raggio degli angoli, e i valori predefiniti — URL di Buy more, URL di Back e durata — per i link che non li indicano. Una spunta applica l’aspetto a tutti i progetti dell’organizzazione.

Nella tabella Customers, l’azione di riga Create a portal link crea un link per quel cliente senza scrivere codice — come fa Portal link nella sua scheda Credits.

Deve corrispondere esattamente al nome evento di un meter esistente e attivo in questo progetto (maiuscole/minuscole comprese). È grazie a questa corrispondenza che MeterFlow sa quale contatore alimenta l’evento. Nessun meter corrispondente → l’API rifiuta l’evento con un 404 e non viene salvato nulla. Controlla la pagina Meters per la grafia esatta.

Quale dei tuoi clienti l’ha fatto — la stessa stringa identificativa libera usata per abbonamenti e crediti. La coerenza è tutto: user-842 e USER-842 sono due clienti diversi.

La quantità — facoltativa. Se la ometti, un meter Sum, Max o Min la legge dalla proprietà dell’evento indicata dal suo campo di aggregazione (la tua app la invia in properties); altrimenti l’evento conta 1. Il significato dipende dall’aggregazione del meter: per un meter Count il valore è ignorato (ogni evento conta come un’occorrenza); per Sum è la quantità da sommare (42 secondi, 1 300 token); per Max/Min è la misura confrontata; un meter Unique count conta i valori distinti del suo campo di aggregazione.

Dove MeterFlow invia gli eventi, es. https://api.acme.dev/meterflow.

Di quali eventi viene informato questo endpoint: usage.recorded, credit.granted, credit.deducted (un addebito, o un utilizzo Metered addebitato — il suo transaction_type dice quale), subscription.created, .updated, .renewed e .canceled, limit.reached, cap.reached, balance.exhausted, e i due qui sotto.

Un saldo, in crediti. Impostalo e l’endpoint riceve anche balance.low quando il saldo di un cliente scende sotto la soglia e balance.topped_up quando risale sopra; cancellalo e smettono entrambi. I due eventi arrivano e se ne vanno con la soglia, perché senza una linea non si può avvisare un endpoint che è stata superata.

Quale dei cinque usano i tuoi clienti per pagare.

Live — l’account di produzione del tuo fornitore, che scrive dati live; Test — la sua sandbox, che scrive dati di test. Un connettore per fornitore e account.

Il segreto con cui il tuo fornitore firma i webhook — per Chargebee, che non firma nulla, il nome utente e la password che invia al suo posto. Viene verificato a ogni chiamata e non viene mai mostrato di nuovo: la tabella ne mostra solo gli ultimi quattro caratteri.

Mostrato appena il connettore è creato: incollalo nelle impostazioni webhook del tuo fornitore.

Quale prezzo del tuo fornitore — un prodotto su Polar, una variante su Lemon Squeezy, un piano su Chargebee e Razorpay — mette un cliente su quale dei tuoi piani. Un evento per un prezzo senza mappatura viene registrato e non cambia nulla.

Ogni evento ricevuto dal connettore, con ciò che ha fatto in una frase: cosa è stato applicato, e perché il resto è stato ignorato.

Dove arriva l’invito. MeterFlow invia un link che funziona una volta, per 7 giorni, solo per quell’indirizzo: la persona lo apre ed entra — dal proprio account, o creandone uno tramite il link.

Admin — impostazioni dell’organizzazione, inviti, chiavi API, webhook, connettori, progetti e fatturazione. Member — chi lavora ogni giorno: meter, piani e le pagine Subscriptions, Usage e cliente. Viewer — sola lettura. Di proposito non c’è l’opzione “owner”: la proprietà non si concede con un invito.

Elencati nella pagina Members finché non vengono accettati, revocati o scadono. Revoke blocca subito il link.

Sulla riga di ogni membro, per owner e admin. L’appartenenza dell’owner e la tua non si possono cambiare lì. Rimuovere qualcuno gli toglie l’accesso; il suo account, e ciò che ha creato, restano.