Le moteur d’abonnements de lahsab, c’est Stripe où collectionMethod vaut toujours send_invoice : on émet une facture datée, on relance, et le client paie par virement CCP / BaridiMob quand il veut. Il n’y a pas de carte à débiter, donc rien ne se prélève tout seul, et la mécanique tout entière découle de là.

La règle d’or

Stripe-carte peut avancer l’horloge dès le renouvellement, parce qu’il a une carte à débiter : le paiement est présumé. lahsab n’a rien à débiter. Avancer la période sur une facture émise mais non payée, ce serait accorder de l’accès contre une promesse, et vous laisser croire qu’un client est à jour alors que l’argent n’est jamais arrivé.

Donc l’horloge ne bouge jamais sur une promesse. Elle bouge sur un paiement.

En pratique, votre code d’entitlement se réduit à une comparaison :

const aAcces = user.paidUntil && user.paidUntil > new Date();

où paidUntil est le currentPeriodEnd que vous avez écrit en recevant invoice.paid.

Qui possède quoi

C’est la frontière à avoir en tête avant d’écrire la première ligne.

lahsab ne sait pas ce que débloque votre plan « Pro » : ni combien de projets il autorise, ni quelles fonctionnalités il ouvre. Exactement comme Stripe. On vous dit « payé jusqu’au 13 septembre » ; ce que vous en faites vous regarde.

Le modèle

Cinq objets, empruntés à Stripe : si vous connaissez l’un, vous connaissez l’autre.

Souscrire, en un appel

POST /subscriptions est le point d’entrée du parcours d’achat. En un seul appel, il crée l’abonnement, émet immédiatement la première facture, et vous renvoie le lien sur lequel rediriger l’acheteur. C’est votre Stripe Checkout.

# 1. Le client existe-t-il déjà ?
curl "https://api.lahsab.com/customers?externalId=user_abc123" \
  -H "x-api-key: lsk_live_CLE"

# 2. Sinon, on le crée.
curl -X POST https://api.lahsab.com/customers \
  -H "x-api-key: lsk_live_CLE" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: cust-user_abc123" \
  -d '{
    "externalId": "user_abc123",
    "name": "Yacine B.",
    "phone": "0770000000",
    "defaultMethod": "baridimob"
  }'

async function upsertCustomer(user) {
  const found = await api(
    `/customers?externalId=${encodeURIComponent(user.id)}`,
  );
  if (found.length) return found[0];

  return api("/customers", {
    method: "POST",
    headers: { "Idempotency-Key": `cust-${user.id}` },
    body: JSON.stringify({
      externalId: user.id,
      name: user.fullName,
      phone: user.phone,
      defaultMethod: "baridimob",
    }),
  });
}

curl -X POST https://api.lahsab.com/subscriptions \
  -H "x-api-key: lsk_live_CLE" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: sub-user_abc123-pro-mensuel" \
  -d '{
    "customerId": "c0ffee00-1111-4222-8333-444455556666",
    "priceId": "9f8e7d6c-5b4a-4321-9876-543210fedcba",
    "daysUntilDue": 7
  }'

const res = await fetch("https://api.lahsab.com/subscriptions", {
  method: "POST",
  headers: {
    "x-api-key": process.env.LAHSAB_API_KEY,
    "content-type": "application/json",
    "Idempotency-Key": `sub-${user.id}-pro-mensuel`,
  },
  body: JSON.stringify({
    customerId: customer.id,
    priceId: PRO_MENSUEL,
    daysUntilDue: 7,
  }),
});
const subscription = await res.json();

// Un seul appel : l'abonnement existe, la 1re facture est émise.
window.location.href = subscription.latestInvoice.hostedInvoiceUrl;

<?php
$ch = curl_init("https://api.lahsab.com/subscriptions");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "x-api-key: " . getenv("LAHSAB_API_KEY"),
    "content-type: application/json",
    "Idempotency-Key: sub-" . $userId . "-pro-mensuel",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "customerId" => $customerId,
    "priceId" => PRO_MENSUEL,
    "daysUntilDue" => 7,
  ]),
]);
$subscription = json_decode(curl_exec($ch), true);

header("Location: " . $subscription["latestInvoice"]["hostedInvoiceUrl"]);

import os, requests

res = requests.post(
    "https://api.lahsab.com/subscriptions",
    headers={
        "x-api-key": os.environ["LAHSAB_API_KEY"],
        "Idempotency-Key": f"sub-{user.id}-pro-mensuel",
    },
    json={
        "customerId": customer.id,
        "priceId": PRO_MENSUEL,
        "daysUntilDue": 7,
    },
)
subscription = res.json()

redirect(subscription["latestInvoice"]["hostedInvoiceUrl"])

Réponse 201, l’abonnement avec sa première facture déjà émise :

{
  "id": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
  "environment": "live",
  "status": "incomplete",
  "collectionMethod": "send_invoice",
  "daysUntilDue": 7,
  "invoiceLeadDays": 7,
  "currentPeriodStart": "2026-07-13T00:00:00.000Z",
  "currentPeriodEnd": "2026-08-13T00:00:00.000Z",
  "cancelAtPeriodEnd": false,
  "latestInvoice": {
    "id": "f1e2d3c4-b5a6-4978-8b1c-2d3e4f5a6b7c",
    "number": "LSB-2026-0042",
    "status": "open",
    "amountDue": 2500,
    "dueDate": "2026-07-20T00:00:00.000Z",
    "hostedInvoiceUrl": "https://dashboard.lahsab.com/invoice/f1e2d3c4-b5a6-4978-8b1c-2d3e4f5a6b7c"
  },
  "createdAt": "2026-07-13T10:00:00.000Z"
}

Les états

Facture

Abonnement

Numérotation

À la finalisation, chaque facture reçoit un numéro : LSB-{ANNÉE}-{séquence}.

LSB-2026-0001
LSB-2026-0002
LSB-2026-0003

La séquence est sans trou, et propre à chaque (marchand, environnement, année). Elle repart à 0001 au 1er janvier.

Impayés

lahsab ne relance pas votre client à votre place. Quand l’échéance est dépassée et que la facture reste open, il émet invoice.overdue : le payload porte le nom, le téléphone, le montant, l’échéance et le lien de paiement, de quoi composer votre propre rappel (un message, un appel) sans un appel API de plus. Ensuite, deux réglages du marchand, dans les réglages du tableau de bord, pilotent la suite :

En fin de grâce, la facture devient uncollectible, lahsab émet invoice.marked_uncollectible, et l’abonnement suit le réglage :

Le portail client

POST /portal-sessions renvoie une URL à durée de vie courte (1 heure) où votre client retrouve son abonnement, ses factures et un bouton pour payer. C’est la page « gérer mon abonnement » que vous n’avez pas à construire.

{
  "url": "https://dashboard.lahsab.com/portal/ps_7f3c2e1a9b4d4e6a8c1f2d3e",
  "expiresAt": "2026-07-13T11:00:00.000Z"
}

Et ensuite ?

• Brancher invoice.paid et vérifier les signatures : Webhooks.
• Tous les endpoints, champs et erreurs : Référence API.