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/productsPOST /api/v1/productsPATCH /api/v1/products/{id}GET /api/v1/pricesPOST /api/v1/pricesPOST /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ètre | Type | Requis | Description |
|---|---|---|---|
| name | string | Oui | Nom du produit, 255 caractères au plus |
| description | string | Non | 5 000 caractères au plus |
| active | boolean | Non | true par défaut |
| metadata | object | Non | Donné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ètre | Description |
|---|---|
| filter[active] | true ou false |
| include | prices pour joindre les formules de chaque produit, archivées comprises |
| sort | created_at ou name, préfixe - pour l'ordre décroissant. Par défaut -created_at. |
| page, per_page | Pagination, 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ètre | Type | Requis | Description |
|---|---|---|---|
| product_id | string | Oui | Produit de la même application |
| amount | integer | Oui | Montant par période, en unité mineure. En XAF et XOF, 15000 vaut 15 000 FCFA. |
| currency | string | Oui | XAF ou XOF |
| interval | string | Oui | week, month, quarter ou year |
| interval_count | integer | Non | Nombre d'intervalles par période, de 1 à 100. 1 par défaut. "interval": "month", "interval_count": 3 facture tous les 3 mois. |
| cycles | integer | Non | Nombre de périodes payées avant que l'abonnement se termine, de 1 à 1 000. Vide : sans fin, jusqu'à la résiliation. |
| trial_days | integer | Non | Jours d'essai gratuits, de 0 à 365. 0 par défaut. |
| grace_days | integer | Non | Jours 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_rule | string | Non | fixed_anchor (par défaut) ou from_payment. Voir la règle de renouvellement. |
| nickname | string | Non | Nom de la formule, par exemple « Mensuel » |
| metadata | object | Non | Donné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.
| Formule | grace_days maximal |
|---|---|
| Hebdomadaire | 7 |
| Mensuelle | 30 |
| Trimestrielle | 90 |
| Annuelle | 365 |
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}/archiveSans 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ètre | Description |
|---|---|
| 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. |
| sort | created_at ou amount, préfixe - pour l'ordre décroissant. Par défaut -created_at. |
| page, per_page | Pagination |
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ègle | Paiement le 15 novembre | Échéance suivante |
|---|---|---|
fixed_anchor | La période reste du 10 novembre au 10 décembre : les jours de retard sont perdus. | 10 décembre |
from_payment | La 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 HTTP | Cas |
|---|---|
404 | Produit ou formule inconnu, d'une autre entreprise ou de l'autre environnement |
422 | Champ invalide : produit inconnu, montant nul ou décimal, devise non supportée, interval inconnu, grace_days au-delà d'une période, etc. |
400 | Filtre, tri ou include non autorisé |
How is this guide?
Last updated on