Logo GenukaGenuka Pay
Référence APIAbonnements

Catalogue

Créez les produits que vous vendez et les formules tarifaires auxquelles vos clients s'abonnent.

Le catalogue a deux niveaux :

  • un produit décrit ce que vous vendez, par exemple « Salle de sport, accès illimité » ;
  • une formule (price) fixe le montant, la devise et le rythme de facturation d'un produit. Un produit peut avoir plusieurs formules : mensuelle, trimestrielle, annuelle avec essai, etc.

Un abonnement est toujours créé sur une formule, jamais directement sur un produit.

Retrouver un identifiant

Dans le dashboard, la page Abonnements → Catalogue affiche le product_id et le price_id de chaque produit et formule, avec un bouton de copie.

Endpoints

  • GET /api/v1/products
  • POST /api/v1/products
  • PATCH /api/v1/products/{id}
  • GET /api/v1/prices
  • POST /api/v1/prices
  • POST /api/v1/prices/{id}/archive

Le catalogue n'émet aucun webhook. Il n'existe ni route de lecture d'un seul produit, ni suppression : désactivez un produit ou archivez une formule.

Produits

Créer un produit

POST /api/v1/products
ParamètreTypeRequisDescription
namestringOuiNom du produit, 255 caractères au plus
descriptionstringNon5 000 caractères au plus
activebooleanNontrue par défaut
metadataobjectNonDonnées libres, renvoyées telles quelles
curl -X POST "https://api-pay.genuka.com/api/v1/products" \
  -H "X-Public-Key: YOUR_PUBLIC_KEY" \
  -H "X-Timestamp: UNIX_TIMESTAMP" \
  -H "X-Signature: HMAC_SHA256_SIGNATURE" \
  -H "Idempotency-Key: product-gym-unlimited" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Salle de sport, accès illimité",
    "description": "7 jours sur 7",
    "metadata": { "sku": "GYM-1" }
  }'

Réponse 201 :

{
  "data": {
    "id": "01k79y7a2b4c6d8e0f2g4h6j8k",
    "object": "product",
    "name": "Salle de sport, accès illimité",
    "description": "7 jours sur 7",
    "active": true,
    "metadata": { "sku": "GYM-1" },
    "created_at": "2026-10-01T07:00:00.000000Z"
  }
}

Modifier un produit

PATCH /api/v1/products/{id}

Envoyez seulement les champs à changer : name, description, active, metadata. null efface description ou metadata. metadata est remplacé, pas fusionné.

Désactiver un produit ("active": false) empêche tout nouvel abonnement sur ses formules. Les abonnements en cours continuent d'être facturés.

Lister les produits

GET /api/v1/products
ParamètreDescription
filter[active]true ou false
includeprices pour joindre les formules de chaque produit, archivées comprises
sortcreated_at ou name, préfixe - pour l'ordre décroissant. Par défaut -created_at.
page, per_pagePagination, voir la vue d'ensemble

La clé prices n'apparaît dans la réponse qu'avec include=prices.

Formules

Créer une formule

POST /api/v1/prices
ParamètreTypeRequisDescription
product_idstringOuiProduit de la même application
amountintegerOuiMontant par période, en unité mineure. En XAF et XOF, 15000 vaut 15 000 FCFA.
currencystringOuiXAF ou XOF
intervalstringOuiweek, month, quarter ou year
interval_countintegerNonNombre d'intervalles par période, de 1 à 100. 1 par défaut. "interval": "month", "interval_count": 3 facture tous les 3 mois.
cyclesintegerNonNombre de périodes payées avant que l'abonnement se termine, de 1 à 1 000. Vide : sans fin, jusqu'à la résiliation.
trial_daysintegerNonJours d'essai gratuits, de 0 à 365. 0 par défaut.
grace_daysintegerNonJours pendant lesquels l'accès est maintenu après une échéance impayée. 7 par défaut. Voir ci-dessous pour la limite.
renewal_rulestringNonfixed_anchor (par défaut) ou from_payment. Voir la règle de renouvellement.
nicknamestringNonNom de la formule, par exemple « Mensuel »
metadataobjectNonDonnées libres

Limite du délai de grâce. grace_days ne peut pas dépasser une période de la formule, ni 365 jours. Une période compte 7 jours pour week, 30 pour month, 90 pour quarter et 365 pour year, multipliés par interval_count.

Formulegrace_days maximal
Hebdomadaire7
Mensuelle30
Trimestrielle90
Annuelle365
curl -X POST "https://api-pay.genuka.com/api/v1/prices" \
  -H "X-Public-Key: YOUR_PUBLIC_KEY" \
  -H "X-Timestamp: UNIX_TIMESTAMP" \
  -H "X-Signature: HMAC_SHA256_SIGNATURE" \
  -H "Idempotency-Key: price-gym-yearly" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "01k79y7a2b4c6d8e0f2g4h6j8k",
    "nickname": "Annuel",
    "amount": 100000,
    "currency": "XAF",
    "interval": "year",
    "trial_days": 7,
    "grace_days": 30
  }'

Réponse 201 :

{
  "data": {
    "id": "01k79y8m0n2p4q6r8s0t2v4w6x",
    "object": "price",
    "product_id": "01k79y7a2b4c6d8e0f2g4h6j8k",
    "nickname": "Annuel",
    "amount": 100000,
    "currency": "XAF",
    "interval": "year",
    "interval_count": 1,
    "cycles": null,
    "trial_days": 7,
    "grace_days": 30,
    "renewal_rule": "fixed_anchor",
    "archived": false,
    "metadata": null,
    "created_at": "2026-10-01T07:00:00.000000Z"
  }
}

Une formule ne se modifie pas

Le montant, la devise et le rythme d'une formule sont figés à sa création : il n'existe pas de route de modification. Pour changer de tarif, archivez la formule et créez-en une nouvelle. Les abonnements existants restent sur l'ancienne formule.

Archiver une formule

POST /api/v1/prices/{id}/archive

Sans corps. Une formule archivée ("archived": true) n'accepte plus de nouvel abonnement ; ceux qui existent continuent d'être facturés à son montant. Archiver une seconde fois ne change rien. Il n'y a pas de désarchivage.

Lister les formules

GET /api/v1/prices
ParamètreDescription
filter[product_id]Formules d'un ou plusieurs produits, séparés par des virgules
filter[archived]true : seulement les archivées. false : seulement les actives. Absent : les deux.
sortcreated_at ou amount, préfixe - pour l'ordre décroissant. Par défaut -created_at.
page, per_pagePagination

Règle de renouvellement

renewal_rule décide du début de la nouvelle période quand le client paie en retard. Exemple avec une formule mensuelle, période en cours du 10 octobre au 10 novembre, échéance suivante le 10 novembre :

RèglePaiement le 15 novembreÉchéance suivante
fixed_anchorLa période reste du 10 novembre au 10 décembre : les jours de retard sont perdus.10 décembre
from_paymentLa période devient du 15 novembre au 15 décembre, et le jour d'échéance passe au 15.15 décembre

Un paiement en avance ne déplace jamais la période. fixed_anchor convient aux écoles et aux logiciels, from_payment aux salles de sport ou aux services consommés à partir du paiement.

Pour les formules mensuelles, trimestrielles et annuelles, le jour d'échéance est conservé d'un mois à l'autre et ramené au dernier jour des mois plus courts : 31 janvier, 28 ou 29 février, 31 mars.

Erreurs

Code HTTPCas
404Produit ou formule inconnu, d'une autre entreprise ou de l'autre environnement
422Champ invalide : produit inconnu, montant nul ou décimal, devise non supportée, interval inconnu, grace_days au-delà d'une période, etc.
400Filtre, tri ou include non autorisé

How is this guide?

Last updated on