Factures récurrentes

Ce que configure l'indicateur de récurrence, ce qui génère la facture suivante et ce qui ne le fait pas.

Une facture récurrente est une facture classique que Wajub copie dans un nouveau brouillon à chaque cycle. Chaque copie doit encore être envoyée et réglée par le client : rien n'est débité automatiquement.

Marquer une facture comme récurrente

Il n'existe ni endpoint distinct ni ressource d'abonnement. Deux champs de l'appel de création classique couvrent toute la fonctionnalité.

POSThttps://api.wajub.com/invoices

is_recurringbooleanfacultatifdéfaut : false

Marque cette facture comme celle que Wajub copie à chaque cycle. La première copie est due un intervalle après invoice_date. Seule une facture peut être récurrente : sur un devis ou une estimation, true répond 422.

recurring_intervalenumfacultatif

daily, weekly, monthly, quarterly ou yearly. Intervalle entre les copies.

recurring_frequencyenumfacultatif

Accepté à la création comme autre nom de recurring_interval, avec les cinq mêmes valeurs.

customer_idstringfacultatif

Obligatoire ici. Une facture récurrente sans fiche client ne génère jamais rien.

Tout le reste de la facture, notamment les lignes, les totaux et les notes, fonctionne exactement comme sur une facture ponctuelle.

curl https://api.wajub.com/invoices \
  -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_7Kq2mX9vL4tRb3nP8sZcWd1e",
    "customer_name": "Amina Traoré",
    "invoice_date": "2026-09-11",
    "currency": "XAF",
    "items": [
      { "name": "Retainer", "quantity": 1, "unit_price": 250000 }
    ],
    "is_recurring": true,
    "recurring_interval": "monthly"
  }'

La réponse est la même que pour toute autre facture, avec 201 Created, status: "draft", les deux champs de récurrence et rien de plus.

Réponse · 201 Created, abrégée

{

"invoice": {

"id": "inv_LRQqYvlhrgUOE225KMKU",

"invoice_number": null,

"status": "draft",

"currency": "XAF",

"total": 250000,

"is_recurring": true,

"recurring_interval": "monthly"

}

recurring_frequency est un autre nom, pas un multiplicateur

recurring_frequency: "monthly" signifie chaque mois, pas un nombre de mois. La mise à jour ne l'accepte pas : envoyez recurring_interval partout.

Ce que l'API ne peut pas définir

La récurrence possède d'autres réglages. Aucun n'est disponible dans l'API. Une fin après N occurrences, ou un intervalle de N mois, ne peut pas être défini par l'API.

Réglage	Rôle	Emplacement
Une date de début	Place la première copie à la date de votre choix, au lieu d'un intervalle après la facture	Le formulaire du Dashboard
Une date de fin	Le dernier jour pour lequel un cycle est généré	Le formulaire du Dashboard
Une fin après un nombre de copies	Arrête la génération après ce nombre de copies	Non disponible
Un multiple de l'intervalle	Tous les deux mois, toutes les trois semaines	Non disponible

Une date de fin saisie dans le Dashboard est appliquée : le cycle qui tombe ce jour-là est le dernier généré, puis la série s'arrête définitivement. Une récurrence créée par l'API n'a aucune règle de fin : elle court jusqu'à ce que vous l'arrêtiez.

Ce qui est renvoyé et ce qui ne l'est pas

Quatre champs de récurrence reviennent sur l'objet facture.

Champ	Sur une facture récurrente	Sur une copie générée
`is_recurring`	`true` tant que la série court, `false` une fois arrêtée	`false` : une copie ne génère rien
`recurring_interval`	`daily`, `weekly`, `monthly`, `quarterly` ou `yearly`	Celui du modèle, recopié
`next_invoice_date`	La date de la prochaine copie, `YYYY-MM-DD`. `null` une fois la série arrêtée ou la facture annulée	`null`
`recurring_parent`	`null`	L'`id` de la facture récurrente dont elle a été générée

Une copie est donc la facture dont recurring_parent est renseigné. La règle de fin ne figure pas dans la réponse, et GET /invoices n'a pas de filtre de récurrence, contrairement à la liste du Dashboard.

Déroulement d'un cycle

La première copie est due un intervalle après l'invoice_date de la facture, jamais dans le passé : une facture antidatée ne produit donc pas les cycles écoulés avant qu'elle soit récurrente. Un cycle n'est jamais généré deux fois, même pour une série désactivée puis réactivée. Une copie ne peut pas devenir récurrente elle-même (422), et le duplicata d'une facture récurrente est un simple brouillon, qui ne se répète que si vous le décidez.

À la date de chaque cycle, Wajub copie chaque facture récurrente non annulée, sauf si sa date de fin est passée ou si votre plan n'inclut pas la fonctionnalité.

La copie hérite	La copie a en propre
Les lignes, avec leurs quantités, prix et taxes	Aucun `invoice_number` avant son envoi, comme tout brouillon
La devise et la remise globale de la facture	`invoice_date`, définie sur la date du cycle arrivé à échéance
Les notes, les conditions, le pied de page et les instructions de paiement	`due_date`, trente jours plus tard
Le modèle, la langue et les réglages d'affichage	Le bloc client, relu depuis la fiche du client
Les moyens de paiement acceptés	`is_recurring: false`. Une copie est une facture ordinaire et ne génère jamais ses propres copies

Chaque cycle produit exactement une copie. Une série mensuelle, trimestrielle ou annuelle ne saute jamais un mois : un mois après le 31 janvier, c'est le 28 février, et la série continue à partir du 28. Les dates des cycles sont en UTC.

Deux de ces points méritent votre attention. Le bloc client est repris depuis la fiche actuelle à chaque cycle. Une adresse ou un nom d'entreprise corrigé sur la fiche apparaît donc dans le document suivant sans modifier les précédents. Par ailleurs, due_date est toujours fixée à trente jours après la date de la copie, quelles que soient les conditions de la facture d'origine.

Une copie est un brouillon, pas un débit

Chaque facture générée arrive au statut draft, avec amount_paid remis à zéro. Elle n'est ni ouverte au paiement, ni envoyée par e-mail, ni payée, et elle reste un brouillon après son échéance : seule une facture envoyée passe overdue. Quelqu'un doit encore appeler /send et transmettre l'URL à chaque cycle, exactement comme pour une facture ponctuelle. La récurrence vous évite seulement de rédiger le document.

Sans fiche client, aucune copie

Une facture sans customer_id ne génère jamais rien. Une facture adressée uniquement à un customer_name, ce qui est parfaitement valide pour une facture ponctuelle, ne produit aucune copie et ne signale rien. Envoyez customer_id lorsque vous définissez is_recurring.

Arrêter une récurrence

Une date de fin, quand le Dashboard en a enregistré une, arrête la série d'elle-même. Sinon, vous l'arrêtez, à tout moment et quel que soit le statut de la facture, payée comprise.

POSThttps://api.wajub.com/invoices/{id}/stop-recurring

Arrêter la série et conserver le document

curl -X POST https://api.wajub.com/invoices/inv_LRQqYvlhrgUOE225KMKU/stop-recurring \
  -H "Authorization: sk.xxxxxxxxxxxxxxxx…"

L'appel ne prend pas de corps. La facture revient avec is_recurring: false et next_invoice_date: null, rien d'autre ne change, et invoice.updated est émis. Aucune copie n'est générée après cet appel, et les copies déjà générées restent telles quelles : chacune est une facture à part entière, à envoyer, annuler ou supprimer comme une autre. Arrêter une série déjà arrêtée répond 200 sans rien changer. Dans le Dashboard, la même action s'appelle Arrêter la récurrence, dans le menu d'actions de la facture.

Appelez-le sur la facture récurrente, pas sur une copie. Une copie n'a pas de série propre : l'appel y répond 400, avec l'identifiant du modèle dans recurring_parent :

Réponse · 400 sur une copie générée

{

"code": 400,

"status": "Bad Request",

"message": "This invoice was generated by a recurring invoice. Stop the series on that one.",

"recurring_parent": "inv_LRQqYvlhrgUOE225KMKU"

}

Deux autres appels touchent la série, et tous deux sont plus restreints. PUT /invoices/{id} avec is_recurring: false l'arrête aussi, mais seulement tant que la facture est un brouillon, puisque seul un brouillon est modifiable. Annuler la facture arrête aussi la génération, et efface next_invoice_date, mais l'annulation est refusée une fois la facture payée.

Coût selon le plan

La récurrence nécessite la fonctionnalité Facturation récurrente, disponible à partir de Growth.

Le Dashboard refuse d'enregistrer une facture récurrente sans cette fonctionnalité. Sans le plan, la génération est ignorée et le document n'est pas modifié. Après le passage à un plan inférieur, la génération reprend donc automatiquement si le compte revient à un plan supérieur, avec les cycles arrivés à échéance entre-temps. POST /invoices ne vérifie pas le plan. La création d'une facture récurrente par l'API réussit avec tous les plans, mais ne génère simplement rien.

Pages associées