Abonnements

L’API Subscriptions permet de lister et récupérer des instances d’abonnement (un client sur un plan récurrent). Elles sont en général créées lorsque des clients souscrivent à un produit récurrent via une session ou un lien de paiement.

Détail d’abonnement à remplacer

Les SDK peuvent exposer à la fois des helpers /subscriptions et des méthodes /customer-subscriptions. Exemples par route et transitions de statut : Abonnements. Les champs immuables et les règles d’annulation suivent les descriptions OpenAPI de chaque opération.

Pour les parcours d’inscription (essais, types de premier paiement, montants de session), voir Comportement du tunnel — Abonnements.

Lister les abonnements

Récupère tous les abonnements de votre organisation.

Paramètres de requête

Paramètre	Type	Description
`page`	`number`	Page (défaut : `1`)
`pageSize`	`number`	Taille de page (défaut : `50`)

import { LomiSDK } from '@lomi./sdk';

const lomi = new LomiSDK({
  apiKey: process.env.LOMI_API_KEY!,
  environment: 'live',
});

const subscriptions = await lomi.subscriptions.list({
  page: 1,
  pageSize: 20,
});

subscriptions.forEach(sub => {
  console.log(`${sub.id}: ${sub.status} - ${sub.amount} ${sub.currency_code}`);
});

from lomi import LomiClient
import os

client = LomiClient(
    api_key=os.environ["LOMI_API_KEY"],
    environment="test"
)

subscriptions = client.subscriptions.list(page=1, pageSize=20)

for sub in subscriptions:
    print(f"{sub['id']}: {sub['status']}")

curl -X GET "https://api.lomi.africa/subscriptions?page=1&pageSize=20" \
  -H "X-API-KEY: $LOMI_API_KEY"

Abonnements d’un client

Récupère les abonnements d’un client donné.

const customerSubs = await lomi.subscriptions.findByCustomer('cus_abc123...');

customer_subs = client.subscriptions.get_by_customer('cus_abc123...')

curl -X GET "https://api.lomi.africa/subscriptions/customer/cus_abc123..." \
  -H "X-API-KEY: $LOMI_API_KEY"

Obtenir un abonnement

Récupère le détail d’un abonnement.

const subscription = await lomi.subscriptions.get('sub_abc123...');
console.log(`Status: ${subscription.status}`);
console.log(`Next billing: ${subscription.current_period_end}`);

subscription = client.subscriptions.get('sub_abc123...')
print(f"Status: {subscription['status']}")

curl -X GET "https://api.lomi.africa/subscriptions/sub_abc123..." \
  -H "X-API-KEY: $LOMI_API_KEY"

Cycle de vie d’un abonnement

Les abonnements sont créés lorsqu’un client finalise le tunnel pour un produit récurrent (tunnel hébergé, lien de paiement, vitrine ou session API avec product_type: recurring). Statuts typiques :

Statut	Signification
`pending`	Créé mais pas encore actif (rare à l’inscription).
`trial`	Essai gratuit en cours ; pas de prélèvement avant la fin de l’essai.
`active`	Payant et renouvelé selon l’échéance.
`past_due`	Échec de renouvellement ; nouvelles tentatives ou action marchande.
`paused`	Facturation en pause (p. ex. après échec si le produit est configuré pour pauser).
`cancelled`	Annulé par le marchand ou le client.
`expired`	Durée fixe terminée ou essai converti sans moyen de paiement.

Le premier paiement est défini sur le produit via first_payment_type :

Valeur	Premier prélèvement au tunnel
`initial`	Tarif récurrent complet (ou montant au prorata selon les règles).
`non_initial`	0 à l’inscription ; premier prélèvement à la première échéance.
`prorated`	Montant partiel pour le reste de la période en cours.

Essais (trial_enabled + trial_period_days) : montant à l’inscription 0. le processeur carte enregistre la carte pour la facturation ultérieure ; le mobile money peut finaliser sans paiement immédiat. Après l’essai, le statut passe à active et la facturation démarre à next_billing_date.

Renouvellements automatiques avec moyen carte enregistré. Sans moyen (fréquent en mobile money), lomi. peut basculer vers un lien de renouvellement manuel pour le client.

Annuler un abonnement

Annule un abonnement actif. C’est la seule modification permise.

Corps de la requête

Champ	Type	Obligatoire	Description
`cancel_at_period_end`	`boolean`	Non	Si `true`, annulation fin de période. Si `false`, annulation immédiate (défaut).
`reason`	`string`	Non	Motif d’annulation

const cancelled = await lomi.subscriptions.cancel('sub_abc123...');

const scheduledCancel = await lomi.subscriptions.cancel('sub_abc123...', {
  cancel_at_period_end: true,
  reason: 'Customer requested cancellation',
});

console.log(`Subscription will cancel at: ${scheduledCancel.cancel_at}`);

cancelled = client.subscriptions.cancel('sub_abc123...')

scheduled_cancel = client.subscriptions.cancel('sub_abc123...', {
    "cancel_at_period_end": True,
    "reason": "Customer requested cancellation"
})

curl -X POST "https://api.lomi.africa/subscriptions/sub_abc123.../cancel" \
  -H "X-API-KEY: $LOMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cancel_at_period_end": true,
    "reason": "Customer requested cancellation"
  }'

Objet Subscription

Champ	Type	Description
`id`	`string`	Identifiant unique
`customer_id`	`string`	Client
`product_id`	`string`	Produit
`price_id`	`string`	Tarif
`status`	`string`	`pending`, `trial`, `active`, `past_due`, `paused`, `cancelled`, `expired`
`amount`	`number`	Montant récurrent
`currency_code`	`string`	Devise
`billing_interval`	`string`	`day`, `week`, `month`, `year`
`next_billing_date`	`string`	Prochaine date de prélèvement (ISO 8601)
`start_date`	`string`	Début de l’abonnement
`end_date`	`string`	Fin pour durée fixe ou essai (nullable)
`cancel_at_period_end`	`boolean`	Annulation planifiée en fin de période
`cancel_at`	`string`	Date d’annulation planifiée
`cancelled_at`	`string`	Annulation effective
`created_at`	`string`	Création
`updated_at`	`string`	Dernière mise à jour

Les réponses API peuvent utiliser subscription_id plutôt que id. Voir Abonnements pour la forme de liste canonique.

Webhooks

Abonnez-vous à ces événements en SCREAMING_SNAKE_CASE (comme sur Webhooks) :

Événement	Description
`SUBSCRIPTION_CREATED`	Nouvel abonnement après inscription réussie (y compris essai).
`SUBSCRIPTION_RENEWED`	Cycle de facturation renouvelé avec succès.
`SUBSCRIPTION_CANCELLED`	Abonnement annulé.

Les échecs de paiement au renouvellement n’émettent pas de webhook abonnement dédié. Écoutez PAYMENT_FAILED sur la transaction du renouvellement et surveillez le status (past_due, paused, etc.) via l’API.

L’enregistrement de carte en essai (setup_intent.succeeded) est interne ; SUBSCRIPTION_CREATED est émis à la fin de l’inscription, pas au chargement du formulaire carte.

Notifications client : les inscriptions en essai ou à 0 € (sans transaction de paiement complétée) déclenchent un e-mail de confirmation d’inscription si customer_notifications.subscription_signups.email est activé (par défaut : oui). Les inscriptions avec premier paiement reçoivent le reçu de transaction standard.

Réponses d’erreur

Statut	Description
`401`	Clé API invalide ou manquante
`404`	Abonnement ou client introuvable

Abonnements

Sur cette page