Facturation à l'usage

La facturation à l'usage permet de facturer selon une consommation mesurée (appels API, sièges, crédits, etc.) sur des produits usage_based. Chaque étape ci-dessous correspond à un endpoint REST public dans openapi.json.

Créer un compteur et un abonnement d’usage

POST /meters

En-tête X-API-KEY. Variable : LOMI_SECRET_KEY. Hôte sandbox : sandbox.api.lomi.africa.

Then POST /usage/subscriptions and POST /usage/events.

curl -sS -X POST "https://sandbox.api.lomi.africa/meters" \
  -H "X-API-Key: $LOMI_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "api_calls",
    "product_id": "prod_...",
    "filter": { "code": "api_calls" },
    "aggregation": { "type": "sum", "property": "quantity" }
  }'

Ouvrir la référence REST

Configurer le compteur depuis le code

lomi.meters.create

new LomiSDK({ apiKey: process.env.LOMI_SECRET_KEY, environment: "sandbox" }).

const meter = await lomi.meters.create({
  name: 'api_calls',
  product_id: 'prod_...',
  filter: { code: 'api_calls' },
  aggregation: { type: 'sum', property: 'quantity' },
});
await lomi.usage.createSubscription({
  customer_id: 'cus_...',
  product_id: 'prod_...',
});

Ouvrir le SDK TypeScript

Pas de commande CLI d’usage ; utilisez REST ou MCP

lomi

lomi login, puis la CLI envoie X-API-KEY depuis la session.

# No usage create command in the CLI yet.
# Use REST POST /meters and POST /usage/subscriptions, or MCP lomi_meters / lomi_usage.

Ouvrir le guide CLI

Créer le compteur et inscrire le client

lomi_meters action=create

MCP hébergé sur https://mcp.lomi.africa/mcp. OAuth ou x-lomi-api-key.

{
  "action": "create",
  "body": {
    "name": "api_calls",
    "product_id": "prod_...",
    "filter": { "code": "api_calls" },
    "aggregation": { "type": "sum", "property": "quantity" }
  }
}

Ouvrir le jumeau MCP

Pour la configuration produit (product_type: usage_based, tarifs, agrégation), voir Produits. Les abonnements à l'usage sont distincts des abonnements checkout récurrents, utilisez POST /usage/subscriptions pour inscrire un client sur un plan à l'usage.

Hors périmètre

Il n’y a pas d’identifiant de cycle de facturation côté marchand, ni d’API pour changer le montant avant la date de facture. L’usage est ingéré, puis facturé sur la période. Créez d’abord le produit et le tarif, inscrivez avec POST /usage/subscriptions, puis envoyez les événements. Voir Produits.

Étapes

Créer un produit à l'usage

Créez un produit avec product_type: usage_based et un prix récurrent. Voir Produits.

Créer un compteur (meter)

Définissez le code de métrique facturable que votre application enverra à chaque événement d'usage.

curl -X POST "https://sandbox.api.lomi.africa/meters" \
  -H "Authorization: Bearer $LOMI_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "api_calls",
    "product_id": "prod_...",
    "filter": { "code": "api_calls" },
    "aggregation": { "type": "sum", "property": "quantity" }
  }'

→ Créer un compteur

Inscrire le client (abonnement à l'usage)

Avant d'ingérer de l'usage pour un client, inscrivez-le sur le produit à l'usage.

curl -X POST "https://sandbox.api.lomi.africa/usage/subscriptions" \
  -H "Authorization: Bearer $LOMI_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_...",
    "product_id": "prod_..."
  }'

→ Créer un abonnement à l'usage

Enregistrer les événements d'usage

Envoyez l'usage au fil de l'eau. Utilisez un transaction_id stable par événement logique pour l'idempotence.

curl -X POST "https://sandbox.api.lomi.africa/usage/events" \
  -H "Authorization: Bearer $LOMI_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "evt_unique_123",
    "code": "api_calls",
    "customer_id": "cus_...",
    "subscription_id": "sub_...",
    "quantity": 1
  }'

Retourne 202 Accepted ; le traitement est asynchrone.

→ Enregistrer un événement d'usage

Consulter soldes et périodes

Objectif	Endpoint
Portefeuille compteur client	Solde compteur
Usage de la période en cours	Usage abonnement
Périodes historiques	Lister les périodes
Crédits prépayés	Créditer le portefeuille
Contrôle d'accès fonctionnel	Vérifier une entitlement

Réconciliation

Lister ou récupérer les événements d'usage si les webhooks sont en retard : Lister, Récupérer.
Reporting revenus MRR + usage + ponctuel : Métriques revenus combinées.

Référence : facturation lomi. Radar

lomi. Radar facture chaque paiement filtré lorsque le produit est activé sur votre organisation. Chaque évaluation appelle enqueue_usage_event avec le code compteur radar_screen (agrégation : count).

Activez Radar via PATCH /organizations/radar-settings (enabled: true). Un compteur radar_screen est créé automatiquement si un produit à l'usage correspondant existe.
Chaque paiement filtré (carte, MTN, Wave) enregistre une unité d'usage tant que Radar est actif.
Consultez soldes et périodes comme pour les autres compteurs (Solde compteur, Périodes).

Voir aussi

Radar: produit de filtrage des transactions
Abonnements: abonnements checkout récurrents (distincts des abonnements à l'usage)
Produits: catalogue et configuration usage_based
Vérifier les paiements: confirmer le statut avant d'accorder l'accès

Facturation à l'usage

Sur cette page