Référence de l'API
Produits
Créez, listez et renommez ce que vous vendez, et copiez-le entre Test et Production.
Les produits représentent ce que vous vendez. Vous fixez ce que paie le client avec un ou plusieurs prix par produit.
L'objet product
Attributs
idstringIdentifiant unique du produit.app_idstringL'application à laquelle appartient le produit.namestringLe nom du produit.slugstringUn nom utilisable dans une URL, unique au sein de l'application. Il ne change pas quand vous renommez le produit, donc votre code peut s'appuyer dessus. Il change seulement si vous en définissez un nouveau.created_attimestampQuand le produit a été créé, en secondes Unix.archived_attimestampnullableQuand le produit a été archivé, ou null. Un produit archivé ne démarre aucun nouvel abonnement sur ses prix.
{
"id": "pR4dWx9K",
"app_id": "8ddhXCDW",
"name": "Pro plan",
"slug": "pro-plan",
"created_at": 1727600000,
"archived_at": null
}Créer un produit
POST/v1/apps/{appID}/products
Accepte un en-tête Idempotency-Key.
Crée un produit.
Paramètres
namestringobligatoireLe nom du produit.slugstringLe slug à utiliser : lettres minuscules et chiffres, avec des tirets simples entre eux, jusqu'à 100 caractères. Sans slug, Abuna le construit à partir dename. Si ce slug est pris, il ajoute-2,-3, et ainsi de suite, donc un produit créé sans slug n'entre jamais en conflit.
Renvoie le produit avec le statut 201. Un slug de forme incorrecte renvoie 422 avec le code invalid et un élément errors pour slug. Si un autre produit de l'application a le slug que vous avez envoyé, renvoie 409 avec le code slug_taken et un élément errors pour slug.
curl https://api.abuna.app/v1/apps/8ddhXCDW/products \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{"name": "Pro plan"}'{
"id": "pR4dWx9K",
"app_id": "8ddhXCDW",
"name": "Pro plan",
"slug": "pro-plan",
"created_at": 1727600000,
"archived_at": null
}Lister les produits
GET/v1/apps/{appID}/products
Liste les produits de l'application, y compris archivés, du plus récent au plus ancien, une page à la fois.
Paramètres de requête
limitintegerCombien de produits renvoyer, de 1 à 100. Par défaut : 50.cursorstringLa valeurnext_cursorde la page précédente. Envoyez les mêmes filtres avec.
Renvoie items et next_cursor, comme décrit dans Listes et filtres. Une valeur non autorisée, comme un limit supérieur à 100, renvoie 422 avec le code invalid et le nom du paramètre dans errors.
curl https://api.abuna.app/v1/apps/8ddhXCDW/products \
-H "Authorization: Bearer sk_test_..."{
"items": [
{
"id": "pR4dWx9K",
"app_id": "8ddhXCDW",
"name": "Pro plan",
"slug": "pro-plan",
"created_at": 1727600000,
"archived_at": null
}
],
"next_cursor": null
}Modifier un produit
PATCH/v1/apps/{appID}/products/{id}
Change le nom du produit, son slug, ou les deux. Envoyez-en au moins un. Un nouveau nom conserve le slug actuel.
Paramètres
namestringLe nouveau nom.slugstringLe nouveau slug, dans la même forme qu'à la création.
Renvoie le produit. Un corps sans aucun des deux champs, ou un name vide, renvoie 422 avec le code invalid et un élément errors pour name. Un slug de forme incorrecte renvoie 422 avec un élément errors pour slug. Si un autre produit de l'application a le nouveau slug, renvoie 409 avec le code slug_taken et un élément errors pour slug. Si l'application n'a aucun produit avec cet ID, renvoie 404 avec le code not_found.
curl https://api.abuna.app/v1/apps/8ddhXCDW/products/pR4dWx9K \
-X PATCH \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{"name": "Team plan"}'{
"id": "pR4dWx9K",
"app_id": "8ddhXCDW",
"name": "Team plan",
"slug": "pro-plan",
"created_at": 1727600000,
"archived_at": null
}Archiver un produit
POST/v1/apps/{appID}/products/{id}/archive
Accepte un en-tête Idempotency-Key.
Archive le produit. Ses prix ne démarrent aucun nouvel abonnement, et leurs liens d'abonnement affichent « Cette formule n'est plus disponible. » Les abonnements qui utilisent déjà ses prix continuent de se renouveler. Chaque prix garde son propre état d'archivage. Archiver un produit déjà archivé ne change rien. Pour revenir en arrière, désarchivez le produit.
Renvoie le produit. Si l'application n'a aucun produit avec cet ID, renvoie 404 avec le code not_found.
curl https://api.abuna.app/v1/apps/8ddhXCDW/products/pR4dWx9K/archive \
-X POST \
-H "Authorization: Bearer sk_test_..."{
"id": "pR4dWx9K",
"app_id": "8ddhXCDW",
"name": "Pro plan",
"slug": "pro-plan",
"created_at": 1727600000,
"archived_at": 1727686400
}Désarchiver un produit
POST/v1/apps/{appID}/products/{id}/unarchive
Accepte un en-tête Idempotency-Key.
Désarchive le produit. Ses prix non archivés peuvent de nouveau démarrer des abonnements, et leurs liens d'abonnement fonctionnent de nouveau. Les prix que vous avez archivés vous-même restent archivés. Désarchiver un produit qui n'est pas archivé ne change rien.
Renvoie le produit. Si l'application n'a aucun produit avec cet ID, renvoie 404 avec le code not_found.
curl https://api.abuna.app/v1/apps/8ddhXCDW/products/pR4dWx9K/unarchive \
-X POST \
-H "Authorization: Bearer sk_test_..."{
"id": "pR4dWx9K",
"app_id": "8ddhXCDW",
"name": "Pro plan",
"slug": "pro-plan",
"created_at": 1727600000,
"archived_at": null
}Copier entre Test et Production
Vous pouvez copier des produits et leurs prix du mode Test de votre application vers son mode Production, et de Production vers Test. Appelez l'endpoint sur l'application vers laquelle vous copiez : copier depuis Test sur l'application en production, ou copier depuis Production sur l'application Test. Les deux prennent le même corps et renvoient la même réponse.
Une nouvelle copie d'un produit reçoit son nom et son slug. Une nouvelle copie d'un prix reçoit son nom, sa devise, son montant et sa période de facturation. Copier à nouveau aligne le nom et le slug d'un produit, et le nom et le montant d'un prix, sur l'application d'où vous copiez.
Les copies sont liées dans les deux sens
Une fois un produit copié, lui et sa copie restent liés, quel que soit le sens de la copie suivante. Copier l'un met à jour l'autre et ne crée jamais de nouveau produit. Les prix sont liés de la même façon.
Par exemple, créez un produit en Test et copiez-le vers Production. Renommez-le en Production, puis copiez-le de Production vers Test. Le produit Test d'origine prend le nouveau nom, et aucun deuxième produit Test n'apparaît. Un produit créé en Production puis copié vers Test fonctionne de la même façon.
Ce sur quoi vous pouvez compter, dans les deux sens :
- La copie se fait seulement quand vous l'appelez, et seulement vers l'application du chemin.
- Elle copie uniquement les produits et les prix. Les clients, les abonnements et les réglages restent tels quels.
- Copier à nouveau met à jour les copies déjà faites, dans un sens comme dans l'autre. Elle ne crée jamais de deuxième copie.
- Elle ne supprime, n'archive et ne désarchive jamais rien dans l'application vers laquelle vous copiez. Un produit ou un prix qui n'existe plus dans l'application d'où vous copiez, ou un prix archivé là-bas, reste tel quel.
- Un montant modifié ne s'applique jamais tout de suite, en Test comme en Production, et les abonnés en cours gardent ce qu'ils paient. Voir Montants modifiés.
- Elle copie tout ou rien : une requête qui échoue ne change rien. Les produits et prix ignorés ne la font pas échouer.
- Avec
dry_run, elle renvoie ce que ferait la copie et ne change rien. - Une nouvelle tentative avec le même en-tête
Idempotency-Keyrenvoie la première réponse et ne copie rien de plus.
Copier les produits de Test vers Production
POST/v1/apps/{appID}/products/copy-from-test
Accepte un en-tête Idempotency-Key.
Copie des produits et leurs prix de l'application Test vers l'application en production. Appelez-le avec l'ID de l'application en production, live_app_id, et une clé secrète Production. Une clé Test ne peut pas l'appeler et reçoit 404 avec le code not_found. Voir Copier entre Test et Production pour ce que change une copie.
Paramètres
productsarrayLes ID des produits Test à copier, de 1 à 100. Envoyezproductsouall, pas les deux.allbooleantruecopie tous les produits de l'application Test.dry_runbooleanRenvoyer ce que ferait la copie, avec les mêmes statuts, sans rien changer. Par défautfalse.
Attributs de la réponse
dry_runbooleantruequand c'était un essai à blanc et que rien n'a changé.productsarrayUn élément par produit, dans l'ordre où vous les avez envoyés. Avecall, les produits de l'application d'où vous copiez, du plus ancien au plus récent, puis les copies dont le produit n'y existe plus.Afficher les attributsMasquer les attributs
test_idstringnullableL'ID du produit en Test. Null quand vous copiez depuis Production et que le produit n'a pas encore de copie Test.live_idstringnullableL'ID du produit en Production. Null quand vous copiez depuis Test et que le produit n'a pas encore de copie en Production.namestringLe nom du produit.statusstringreasonstringnullablePourquoi le produit a été ignoré :not_found,deletedouslug_taken. Null sauf sistatusvautskipped.pricesarrayLes prix du produit, chacun avec les attributs ci-dessous.Afficher les attributsMasquer les attributs
test_idstringnullableL'ID du prix en Test. Null quand vous copiez depuis Production et que le prix n'a pas encore de copie Test.live_idstringnullableL'ID du prix en Production. Null quand vous copiez depuis Test et que le prix n'a pas encore de copie en Production.namestringLe nom du prix.statusstringcreated,updated,unchangedouskipped.reasonstringnullablePourquoi le prix a été ignoré :archived,deletedoupending_change. Null sauf sistatusvautskipped.price_changeobjectnullableLe changement de montant que cette copie a programmé dans l'application vers laquelle vous copiez, ou null si elle n'en a programmé aucun.Afficher les attributsMasquer les attributs
amountintegerLe nouveau montant, dans la plus petite unité de la devise.currencystringXAF,XOFouUSD.effective_attimestampMinuit au début du jour où le nouveau montant s'applique, dans le fuseau horaire de votre application.
Renvoie 200. Sans products ni all, renvoie 422 avec le code invalid et un élément errors pour products avec le code required. Envoyer les deux, une liste vide, plus de 100 ID ou un ID vide renvoie 422 avec un élément errors pour products avec le code invalid. Un ID d'application Test dans le chemin renvoie 400 avec le code live_app_required. Si l'application n'a pas de mode Test, renvoie 409 avec le code test_app_missing. Tant que le propriétaire de l'équipe n'a pas vérifié son e-mail, renvoie 403 avec le code email_unverified. Si le forfait de votre équipe a mis l'application en production en lecture seule, renvoie 403 avec le code plan_read_only.
curl https://api.abuna.app/v1/apps/Q7mKp2Rt/products/copy-from-test \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: b7e2c1d4-8f3a-4e6b-9c5d-1a2f3e4b5c6d" \
-d '{
"all": true
}'{
"dry_run": false,
"products": [
{
"test_id": "pR4dWx9K",
"live_id": "Lq2VnB8s",
"name": "Pro plan",
"status": "updated",
"reason": null,
"prices": [
{
"test_id": "Zt6YbN3q",
"live_id": "Hm5RcT9w",
"name": "Monthly",
"status": "updated",
"reason": null,
"price_change": {
"amount": 6000,
"currency": "XAF",
"effective_at": 1792450800
}
},
{
"test_id": "Yc3KfP7d",
"live_id": "Ub8NsE2x",
"name": "Yearly",
"status": "created",
"reason": null,
"price_change": null
},
{
"test_id": "Wk9DgA4m",
"live_id": null,
"name": "Weekly",
"status": "skipped",
"reason": "archived",
"price_change": null
}
]
}
]
}Copier les produits de Production vers Test
POST/v1/apps/{appID}/products/copy-from-live
Accepte un en-tête Idempotency-Key.
Copie des produits et leurs prix de l'application en production vers l'application Test. Appelez-le avec l'ID de l'application Test, test_app_id, et une clé secrète Test. Une clé Production ne peut pas l'appeler et reçoit 404 avec le code not_found. Voir Copier entre Test et Production pour ce que change une copie.
Il prend le même corps et renvoie la même réponse que la copie depuis Test, avec Production et Test inversés. products prend des ID de produits en production, et all copie tous les produits de l'application en production. Dans la réponse, live_id est toujours renseigné : c'est le produit ou le prix que vous avez copié. test_id est sa copie Test, ou null s'il n'en a pas encore.
Il ne fait que lire en Production, il fonctionne donc même avant que le propriétaire de l'équipe ait vérifié son e-mail, et quand le forfait de votre équipe a mis l'application en production en lecture seule.
Renvoie 200. Le corps est vérifié comme pour la copie depuis Test, avec les mêmes erreurs 422. Un ID d'application en production dans le chemin renvoie 400 avec le code test_app_required.
curl https://api.abuna.app/v1/apps/8ddhXCDW/products/copy-from-live \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 4f9a2c7e-1b3d-4e8f-a6c5-9d2e7b1f3a8c" \
-d '{
"all": true
}'{
"dry_run": false,
"products": [
{
"test_id": "pR4dWx9K",
"live_id": "Lq2VnB8s",
"name": "Team plan",
"status": "updated",
"reason": null,
"prices": [
{
"test_id": "Zt6YbN3q",
"live_id": "Hm5RcT9w",
"name": "Monthly",
"status": "unchanged",
"reason": null,
"price_change": null
},
{
"test_id": "Jr7WqC5v",
"live_id": "Fs4HxM8p",
"name": "Daily",
"status": "created",
"reason": null,
"price_change": null
}
]
}
]
}Résultats de la copie
Ci-dessous, la copie d'un produit ou d'un prix est son équivalent dans l'application vers laquelle vous copiez. Quand vous recopiez quelque chose vers l'endroit d'où il vient, sa copie est l'original. Chaque produit de la réponse a l'un de ces statuts :
created: le produit n'avait pas de copie, et il en a une maintenant.updated: le nom ou le slug de sa copie a changé, ou l'un de ses prix a été créé ou mis à jour.unchanged: rien n'a changé, même si certains de ses prix ont pu être ignorés.skipped, avec unereason:not_found: l'ID envoyé n'est pas un produit de l'application d'où vous copiez.deleted: avecallseulement. Le produit n'existe plus dans l'application d'où vous copiez. Sa copie reste telle quelle.slug_taken: un autre produit de l'application vers laquelle vous copiez a déjà le slug de ce produit. Rien n'est copié pour ce produit ni pour ses prix. Changez l'un des deux slugs, puis copiez à nouveau.
Chaque prix a l'un de ces statuts :
created: le prix n'avait pas de copie, et il en a une maintenant sous la copie du produit.updated: sa copie a été renommée, a reçu un changement de montant programmé, ou les deux.unchanged: rien n'a changé.skipped, avec unereason:archived: le prix est archivé dans l'application d'où vous copiez. Sa copie, s'il en a une, reste telle quelle.deleted: le prix n'existe plus dans l'application d'où vous copiez. Sa copie reste telle quelle.pending_change: sa copie a déjà un changement programmé vers un autre montant. Rien n'est copié pour ce prix. Pour copier le montant, annulez ce changement, puis copiez à nouveau.
Montants modifiés
Quand le montant d'un prix diffère de celui de sa copie, Abuna programme un changement de prix sur la copie, avec keep_current_subscribers. Cela fonctionne de la même façon en Test et en Production. Le nouveau montant démarre le premier jour permis, 14 jours après aujourd'hui dans le fuseau horaire de votre application. Toutes les personnes abonnées avant ce jour continuent de payer le montant actuel, et les clients qui s'abonnent à partir de ce jour paient le nouveau. Abuna enregistre un événement price_change.scheduled dans l'application vers laquelle vous copiez, et le price_change du prix dans la réponse indique le nouveau montant et le jour où il démarre.
Un prix qui a déjà un changement programmé est copié avec ce changement : Abuna compare le montant vers lequel il va, et la copie passe à ce montant le même jour, ou le premier jour permis s'il est plus tard. Une nouvelle copie démarre au montant actuel avec le même changement programmé. Copier un prix en sens inverse avant le début de son changement laisse donc l'original tel quel.
Si la copie a déjà un changement programmé, Abuna ne le remplace ni ne l'annule jamais. Si ce changement va vers le même montant, il n'y a rien de plus à faire. S'il va vers un autre montant, le prix est ignoré avec pending_change.