Tarification (Prices)

Qu’est-ce qu’un Price ?

Un Price (Prix) définit comment un produit est facturé. Il peut s’agir d’un paiement unique ou d’un abonnement récurrent avec différentes périodicités.

Format de l’identifiant : price_ suivi de 36 caractères alphanumériques.Exemple : price_abc123def456ghi789jkl012mno345

Relation Produit → Price

Un prix est rattaché à un produit via productId, et un produit peut porter plusieurs prix pour différentes stratégies tarifaires :

Produit "Formation Pro"
├── Price 25 000 XAF one-time (paiement unique)
├── Price 5 000 XAF/mois (abonnement mensuel)
├── Price 50 000 XAF/an (abonnement annuel avec économie)
└── Price 39 EUR one-time (marché européen)

Cette flexibilité permet de proposer plusieurs options de paiement pour le même produit et de gérer plusieurs devises.

Attributs du Price

Attributs principaux

Attribut	Type	Description
`id`	string	Identifiant unique du prix
`productId`	string	Référence au produit parent
`skuId`	string \| null	Hérité. Lien vers une variante historique. `null` pour tout prix créé au niveau produit — ce n’est plus une façon de créer un prix, voir la note ci-dessous
`amount`	string	Montant dans l’unité principale de la devise, renvoyé sous forme de chaîne décimale (`"25000.00"`)
`currency`	string	Code devise, renvoyé en minuscules (`"xaf"`)
`type`	enum	`one_time` ou `recurring`
`active`	boolean	Prix actif et utilisable

Attributs récurrents (abonnements)

Attribut	Type	Description
`billingInterval`	enum	`day`, `week`, `month`, `year`
`billingIntervalCount`	number	Nombre d’intervalles (ex: 3 = tous les 3 mois)
`trialPeriodDays`	number \| null	Jours d’essai gratuit

Créer un prix

Un premier prix se pose à la création du produit avec defaultPriceData (voir Produits). POST /v1/prices est la porte du second prix — un tarif annuel à côté du mensuel, ou une seconde devise — en indiquant dans le corps le produit auquel il se rattache.

Corps de la requête

string

Identifiant du produit auquel le prix se rattache. productId ou skuId est requis — aucun des deux n’est individuellement obligatoire côté validateur, mais la requête est refusée si les deux sont absents. skuId est une forme héritée, conservée pour compatibilité ; productId reste la voie normale.

number

requis

Montant dans l’unité principale de la devise. Strictement positif et au maximum 99999999.99.

string

requis

Code devise, stocké et renvoyé en minuscules. Obligatoire — il n’y a pas de devise par défaut. Limité à xaf et eur, voir la section Devises supportées plus bas.

enum

défaut:"one_time"

one_time ou recurring.

enum

day, week, month ou year. Prix récurrents uniquement.

number

Nombre d’intervalles par cycle de facturation. Strictement positif.

number

Jours d’essai gratuit, 0 ou plus.

boolean

défaut:"true"

Passez false pour créer le prix déjà désactivé.

Un prix est immuable. PUT /v1/prices/{id} ne modifie que le champ active — aucun autre champ n’est lu, même s’il est présent dans le corps. Pour changer un montant, une devise ou une cadence, créez un nouveau prix : à dimensions égales (produit × devise × type × cadence), l’ancien prix actif est désactivé automatiquement. Détail de cette règle de remplacement plus bas, dans la section Réponse API.

Types de tarification

Paiement unique
Abonnement récurrent

One-Time (`one_time`)

Le client paie une seule fois pour accéder au produit.Cas d’usage :

Achats ponctuels
Produits physiques
Téléchargements numériques
Accès à vie

curl -X POST https://buy.api.yabetoopay.com/v1/prices \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "prod_abc123",
    "amount": 25000,
    "currency": "xaf",
    "type": "one_time"
  }'

Recurring (`recurring`)

Le client est facturé automatiquement à intervalles réguliers.Cas d’usage :

Abonnements SaaS
Services continus
Accès premium
Maintenance

curl -X POST https://buy.api.yabetoopay.com/v1/prices \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "prod_abc123",
    "amount": 5000,
    "currency": "xaf",
    "type": "recurring",
    "billingInterval": "month",
    "billingIntervalCount": 1,
    "trialPeriodDays": 14
  }'

Intervalles de facturation

Pour les prix récurrents, définissez la fréquence de facturation :

Interval	Count	Description	Exemple
`day`	1	Quotidien	Facturé chaque jour
`week`	1	Hebdomadaire	Facturé chaque semaine
`week`	2	Bi-hebdomadaire	Facturé toutes les 2 semaines
`month`	1	Mensuel	Facturé chaque mois
`month`	3	Trimestriel	Facturé tous les 3 mois
`month`	6	Semestriel	Facturé tous les 6 mois
`year`	1	Annuel	Facturé chaque année

// Facturation trimestrielle
{
  "productId": "prod_abc123",
  "type": "recurring",
  "billingInterval": "month",
  "billingIntervalCount": 3,
  "amount": 15000,
  "currency": "xaf"
}

Périodes d’essai

Offrez une période d’essai gratuit pour attirer de nouveaux clients :

{
  "productId": "prod_abc123",
  "type": "recurring",
  "billingInterval": "month",
  "billingIntervalCount": 1,
  "amount": 9000,
  "currency": "xaf",
  "trialPeriodDays": 14
}

Début de l'abonnement

Le client s’inscrit et démarre sa période d’essai gratuite

Période d'essai

Pendant 14 jours, le client a accès complet sans être facturé

Fin de l'essai

À la fin de la période d’essai, le premier paiement est prélevé automatiquement

Cycle récurrent

Les paiements suivants sont prélevés selon l’intervalle défini

Assurez-vous d’informer clairement vos clients sur la durée de l’essai et le montant qui sera facturé après.

Gestion multi-devises

Créez un prix par devise pour le même produit. Chaque prix correspond à un appel POST /v1/prices distinct :

curl -X POST https://buy.api.yabetoopay.com/v1/prices \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "prod_abc123",
    "amount": 39,
    "currency": "eur",
    "type": "one_time"
  }'

Devises supportées

La liste est fermée, pas indicative. currency est validée contre une énumération — toute autre valeur, y compris un code ISO 4217 réel comme XOF ou USD, est refusée en 422. Il n’y a que deux devises acceptées aujourd’hui.

Code	Devise	Pays/Région
`XAF`	Franc CFA BEAC	Afrique Centrale
`EUR`	Euro	Europe

Tous les montants sont exprimés dans l’unité principale de la devise, jamais en centimes. Par exemple : 25000 XAF = 25 000 XAF, 39 EUR = 39 €.

Réponse API

GET /v1/prices/{id} expose product et sku à la racine de l’objet.

string

Identifiant du produit parent.

object

Le produit parent, toujours présent.

string | null

Hérité. null pour un prix créé au niveau produit — la voie normale aujourd’hui.

object | null

Hérité. La variante dont provient le prix, pour les prix créés avant que le SKU quitte le contrat de création. null sinon.

price.sku peut valoir un objet non nul. Un prix créé par l’ancien chemin (rattaché à une variante) le porte encore et le portera tant qu’il n’a pas été remplacé par un nouveau prix. Toute intégration qui déréférence price.sku — par exemple price.sku.product — doit se prémunir contre null, dans les deux sens : ne pas planter s’il est absent, et ne pas supposer qu’il l’est toujours.

{
  "id": "price_abc123def456ghi789",
  "productId": "prod_xyz789abc123def456",
  "product": {
    "id": "prod_xyz789abc123def456",
    "name": "Formation Pro"
  },
  "skuId": null,
  "sku": null,
  "amount": "25000.00",
  "currency": "xaf",
  "type": "one_time",
  "billingInterval": null,
  "billingIntervalCount": null,
  "trialPeriodDays": null,
  "active": true,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

Règle de remplacement. La création d’un prix désactive automatiquement le prix qui était actif pour le même produit, la même devise, le même type et la même cadence (billingInterval + billingIntervalCount). C’est ce qui rend un prix immuable : au lieu de modifier un prix existant, on en crée un nouveau, et le remplacement se fait tout seul.Conséquence à connaître : un prix mensuel et un prix annuel ont le même type (recurring) mais une cadence différente, donc ils coexistent sans se remplacer — c’est ainsi qu’on propose les deux options sur le même produit.

Opérations courantes

Créer un prix

curl -X POST https://buy.api.yabetoopay.com/v1/prices \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "prod_abc123",
    "amount": 9000,
    "currency": "xaf",
    "type": "recurring",
    "billingInterval": "month",
    "billingIntervalCount": 1
  }'

Récupérer un prix

curl https://buy.api.yabetoopay.com/v1/prices/price_abc123 \
  -H "Authorization: Bearer sk_live_..."

Lister les prix d’un produit

curl "https://buy.api.yabetoopay.com/v1/prices?productId=prod_abc123" \
  -H "Authorization: Bearer sk_live_..."

GET /v1/prices accepte les filtres suivants, combinables entre eux :

Filtre	Description
`productId`	Uniquement les prix de ce produit
`skuId`	Hérité. Uniquement les prix rattachés à cette variante historique
`type`	`one_time` ou `recurring`
`active`	`true` ou `false`

Désactiver un prix

🛑 Cette page a longtemps affirmé que « les prix ne peuvent pas être supprimés s’ils sont associés à des abonnements actifs » — c’est faux, et ce n’est pas nuancé : il n’y a aucune condition du tout. DELETE /v1/prices/{id} ne supprime rien et ne consulte jamais la moindre souscription — il désactive inconditionnellement le prix (active: false) et renvoie {"message": "Price deactivated"}. PUT produit le même effet, et c’est le seul changement qu’il accepte.

curl -X PUT https://buy.api.yabetoopay.com/v1/prices/price_abc123 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "active": false
  }'

Stratégies de tarification

Offre mensuelle vs annuelle

Proposez une réduction pour l’abonnement annuel — deux appels POST /v1/prices sur le même produit, avec deux cadences différentes :

// Prix mensuel
{
  "productId": "prod_saas_pro",
  "amount": 9000,
  "currency": "xaf",
  "type": "recurring",
  "billingInterval": "month",
  "billingIntervalCount": 1
}

// Prix annuel — même produit, cadence différente : les deux coexistent
{
  "productId": "prod_saas_pro",
  "amount": 90000,
  "currency": "xaf",
  "type": "recurring",
  "billingInterval": "year",
  "billingIntervalCount": 1
}

9 000 XAF/mois vs 90 000 XAF/an représente environ 2 mois gratuits, ce qui incite les clients à s’engager sur l’année.

Tarification par paliers

Créez un produit par niveau de service, chacun avec son prix :

Produit "App Cloud — Starter"     → Price 5 000 XAF/mois
Produit "App Cloud — Pro"         → Price 15 000 XAF/mois
Produit "App Cloud — Enterprise"  → Price 50 000 XAF/mois

Getters utiles

Le modèle Price fournit des getters pour faciliter les vérifications :

// Vérifier le type de prix
price.isRecurring  // true si type === 'recurring'
price.isOneTime    // true si type === 'one_time'

Bonnes pratiques

Format des montants

Les montants sont exprimés dans l’unité principale de la devise, jamais en centimes :

XAF : 25000 = 25 000 XAF
EUR : 39 = 39 €

Les décimales sont acceptées et le montant ne peut pas dépasser 99999999.99. L’API le renvoie sous forme de chaîne décimale ("25000.00").

Reprixer un produit

Un prix est immuable : ne comptez jamais sur PUT pour changer un montant, une devise ou une cadence — il ne touche que active
Créez un nouveau prix ; l’ancien prix actif de mêmes dimensions se désactive tout seul
Lisez le produit dans price.product

Prix actifs/inactifs

Désactivez les anciens prix plutôt que de les supprimer
Gardez les prix actifs au minimum nécessaire
Gardez en tête qu’un nouveau prix désactive le prix actif de même produit, devise, type et cadence

Périodes d'essai

7 à 14 jours est généralement optimal
Trop court : pas assez de temps pour évaluer
Trop long : perte de revenus potentielle

Multi-devises

Ajustez les prix pour chaque marché (pas de simple conversion)
Tenez compte du pouvoir d’achat local
Utilisez des prix psychologiques (9 000 XAF plutôt que 8 750 XAF)

Prochaines étapes

Créer des promotions

Appliquez des réductions avec les coupons et codes promo

Gérer les abonnements

Comprenez le cycle de vie des abonnements

Pour commencer

Configuration du compte

Concepts clés

Catalogue Produits

Ressources

Qu’est-ce qu’un Price ?

Relation Produit → Price

Attributs du Price

Attributs principaux

Attributs récurrents (abonnements)

Créer un prix

Corps de la requête

Types de tarification

One-Time (`one_time`)

Recurring (`recurring`)

Intervalles de facturation

Périodes d’essai

Gestion multi-devises

Devises supportées

Réponse API

Opérations courantes

Créer un prix

Récupérer un prix

Lister les prix d’un produit

Désactiver un prix

Stratégies de tarification

Offre mensuelle vs annuelle

Tarification par paliers

Getters utiles

Bonnes pratiques

Prochaines étapes

Créer des promotions

Gérer les abonnements

​Qu’est-ce qu’un Price ?

​Relation Produit → Price

​Attributs du Price

​Attributs principaux

​Attributs récurrents (abonnements)

​Créer un prix

​Corps de la requête

​Types de tarification

​One-Time (one_time)

​Recurring (recurring)

​Intervalles de facturation

​Périodes d’essai

​Gestion multi-devises

​Devises supportées

​Réponse API

​Opérations courantes

​Créer un prix

​Récupérer un prix

​Lister les prix d’un produit

​Désactiver un prix

​Stratégies de tarification

​Offre mensuelle vs annuelle

​Tarification par paliers

​Getters utiles

​Bonnes pratiques

​Prochaines étapes

Créer des promotions

Gérer les abonnements

Qu’est-ce qu’un Price ?

Relation Produit → Price

Attributs du Price

Attributs principaux

Attributs récurrents (abonnements)

Créer un prix

Corps de la requête

Types de tarification

One-Time (`one_time`)

Recurring (`recurring`)

Intervalles de facturation

Périodes d’essai

Gestion multi-devises

Devises supportées

Réponse API

Opérations courantes

Créer un prix

Récupérer un prix

Lister les prix d’un produit

Désactiver un prix

Stratégies de tarification

Offre mensuelle vs annuelle

Tarification par paliers

Getters utiles

Bonnes pratiques

Prochaines étapes