Skip to content
ABUNA
DocumentationCoupons

Référence de l'API

Coupons

Créez les réductions que les clients obtiennent avec un code promotionnel, pour un paiement, quelques mois, ou chaque paiement.

Voir en Markdown

Un coupon est une réduction : un pourcentage ou un montant fixe, pour un paiement, un nombre de mois, ou chaque paiement. Les clients l'utilisent avec un code promotionnel. Vous pouvez aussi appliquer un coupon vous-même quand vous créez une session checkout ou un abonnement. Pour organiser une vente de bout en bout, voyez Organiser une vente avec des codes promotionnels.

L'objet coupon

Attributs

  • idstring

    Identifiant unique du coupon.
  • app_idstring

    L'application à laquelle le coupon appartient.
  • namestringnullable

    Un nom pour vous, jusqu'à 100 caractères. La page d'abonnement l'affiche sur la ligne de réduction quand aucun code n'a apporté le coupon.
  • percent_offintegernullable

    Le pourcentage retiré, de 1 à 99. Null quand le coupon retire un montant fixe.
  • amount_offintegernullable

    Le montant fixe retiré, dans la plus petite unité de la devise. Null quand le coupon retire un pourcentage.
  • currencystringnullable

    XAF, XOF ou USD. Défini avec amount_off, et null avec percent_off.
  • durationstring

    once : la première période facturée. repeating : les périodes comprises dans duration_in_months. forever : chaque période. Voir Combien de temps dure une réduction.
  • duration_in_monthsintegernullable

    Le nombre de mois d'un coupon repeating, comptés depuis le début de l'abonnement. Null pour once et forever.
  • max_redemptionsintegernullable

    Le nombre maximum d'abonnements qui peuvent utiliser le coupon. Null pour aucune limite.
  • redeem_bytimestampnullable

    Le dernier moment où le coupon peut être utilisé, en secondes Unix. Null pour aucune fin.
  • times_redeemedinteger

    Le nombre d'abonnements qui l'ont utilisé, par l'un de ses codes ou par une réduction que vous avez définie.
  • metadataobject

    Vos propres clés et valeurs. {} quand il n'y en a pas.
  • created_attimestamp

    Quand le coupon a été créé, en secondes Unix.
  • applies_toobjectnullable

    Les produits auxquels le coupon s'applique, sous la forme { "products": [...] }. Null quand il s'applique à tous les produits.
  • validboolean

    Si un nouvel abonnement peut utiliser le coupon maintenant : il n'est pas supprimé, son redeem_by n'est pas passé et il reste sous max_redemptions.
L'objet coupon
{
  "id": "Kf4Wn7Qa",
  "app_id": "8ddhXCDW",
  "name": "Black Friday",
  "percent_off": 25,
  "amount_off": null,
  "currency": null,
  "duration": "repeating",
  "duration_in_months": 3,
  "max_redemptions": 100,
  "redeem_by": 1798761600,
  "times_redeemed": 4,
  "metadata": {},
  "created_at": 1727600000,
  "applies_to": {
    "products": [
      "pR4dWx9K"
    ]
  },
  "valid": true
}

Créer un coupon

POST/v1/apps/{appID}/coupons

Accepte un en-tête Idempotency-Key.

Crée un coupon. Envoyez percent_off ou amount_off, pas les deux, et une duration.

Paramètres

  • namestring

    Un nom pour vous, jusqu'à 100 caractères. La page d'abonnement l'affiche sur la ligne de réduction quand aucun code n'a apporté le coupon.
  • percent_offinteger

    Le pourcentage à retirer, de 1 à 99. Arrondi à la plus petite unité de la devise, vers le bas.
  • amount_offinteger

    Le montant fixe à retirer, dans la plus petite unité de la devise, par exemple 1000 pour 1 000 FCFA. Envoyez currency avec.
  • currencystring

    XAF, XOF ou USD. Obligatoire avec amount_off, et interdit avec percent_off.
  • durationstringobligatoire

    once, repeating ou forever.
  • duration_in_monthsinteger

    Obligatoire avec repeating : le nombre de mois de la réduction, à partir de 1. Interdit avec les autres durées.
  • max_redemptionsinteger

    Le nombre maximum d'abonnements qui peuvent utiliser le coupon, au moins 1. Omettez-le pour aucune limite.
  • redeem_bytimestamp

    Le dernier moment où le coupon peut être utilisé, en secondes Unix. Il doit être dans le futur.
  • applies_toobject

    Les produits auxquels le coupon s'applique. Omettez-le pour couvrir tous les produits.
    Afficher les paramètresMasquer les paramètres
    • productsarray

      Des identifiants de produit, jusqu'à 100. Une liste vide couvre tous les produits.
  • metadataobject

    Vos propres clés et valeurs.

Renvoie le coupon avec le statut 201. Un champ manquant ou incorrect renvoie 422 avec le code invalid et un élément errors pour ce champ. Un identifiant de produit absent de l'application renvoie 422 avec un élément errors pour applies_to.products et le code not_found.

POST /v1/apps/{appID}/coupons
curl https://api.abuna.app/v1/apps/8ddhXCDW/coupons \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Black Friday",
    "percent_off": 25,
    "duration": "once"
  }'
Réponse
{
  "id": "Kf4Wn7Qa",
  "app_id": "8ddhXCDW",
  "name": "Black Friday",
  "percent_off": 25,
  "amount_off": null,
  "currency": null,
  "duration": "once",
  "duration_in_months": null,
  "max_redemptions": null,
  "redeem_by": null,
  "times_redeemed": 0,
  "metadata": {},
  "created_at": 1727600000,
  "applies_to": null,
  "valid": true
}

Lister les coupons

GET/v1/apps/{appID}/coupons

Liste les coupons de l'application, du plus récent au plus ancien, une page à la fois. Les coupons supprimés ne sont pas listés.

Paramètres de requête

  • limitinteger

    Combien de coupons renvoyer, de 1 à 100. Par défaut : 50.
  • cursorstring

    La valeur next_cursor de 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.

GET /v1/apps/{appID}/coupons
curl https://api.abuna.app/v1/apps/8ddhXCDW/coupons \
  -H "Authorization: Bearer sk_test_..."
Réponse
{
  "items": [
    {
      "id": "Kf4Wn7Qa",
      "app_id": "8ddhXCDW",
      "name": "Black Friday",
      "percent_off": 25,
      "amount_off": null,
      "currency": null,
      "duration": "repeating",
      "duration_in_months": 3,
      "max_redemptions": 100,
      "redeem_by": 1798761600,
      "times_redeemed": 4,
      "metadata": {},
      "created_at": 1727600000,
      "applies_to": {
        "products": [
          "pR4dWx9K"
        ]
      },
      "valid": true
    }
  ],
  "next_cursor": null
}

Lire un coupon

GET/v1/apps/{appID}/coupons/{id}

Renvoie le coupon. Un coupon supprimé est introuvable.

Si l'application n'a pas de coupon avec cet identifiant, renvoie 404 avec le code not_found.

GET /v1/apps/{appID}/coupons/{id}
curl https://api.abuna.app/v1/apps/8ddhXCDW/coupons/Kf4Wn7Qa \
  -H "Authorization: Bearer sk_test_..."
Réponse
{
  "id": "Kf4Wn7Qa",
  "app_id": "8ddhXCDW",
  "name": "Black Friday",
  "percent_off": 25,
  "amount_off": null,
  "currency": null,
  "duration": "repeating",
  "duration_in_months": 3,
  "max_redemptions": 100,
  "redeem_by": 1798761600,
  "times_redeemed": 4,
  "metadata": {},
  "created_at": 1727600000,
  "applies_to": {
    "products": [
      "pR4dWx9K"
    ]
  },
  "valid": true
}

Mettre à jour un coupon

PATCH/v1/apps/{appID}/coupons/{id}

Change le nom du coupon, ses métadonnées, ou les deux. La réduction reste telle que vous l'avez créée : pour changer le pourcentage, le montant ou la durée, créez un autre coupon. Envoyez au moins un champ.

Paramètres

  • namestring

    Le nouveau nom, jusqu'à 100 caractères. Envoyez null pour le retirer.
  • metadataobject

    Vos propres clés et valeurs. Il remplace les métadonnées définies avant.

Renvoie le coupon. Un corps sans aucun des deux champs renvoie 422 avec le code invalid et un élément errors pour name. Tout autre champ renvoie 400 avec le code invalid_json et un élément errors avec le code unknown_field. Si l'application n'a pas de coupon avec cet identifiant, renvoie 404 avec le code not_found.

PATCH /v1/apps/{appID}/coupons/{id}
curl https://api.abuna.app/v1/apps/8ddhXCDW/coupons/Kf4Wn7Qa \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -X PATCH \
  -d '{
    "name": "Black Friday sale"
  }'
Réponse
{
  "id": "Kf4Wn7Qa",
  "app_id": "8ddhXCDW",
  "name": "Black Friday sale",
  "percent_off": 25,
  "amount_off": null,
  "currency": null,
  "duration": "repeating",
  "duration_in_months": 3,
  "max_redemptions": 100,
  "redeem_by": 1798761600,
  "times_redeemed": 4,
  "metadata": {},
  "created_at": 1727600000,
  "applies_to": {
    "products": [
      "pR4dWx9K"
    ]
  },
  "valid": true
}

Supprimer un coupon

DELETE/v1/apps/{appID}/coupons/{id}

Supprime le coupon. Aucun nouvel abonnement ne peut l'utiliser, ni ses codes promotionnels. Un abonnement qui le détient déjà garde sa réduction, et ses nouvelles factures l'affichent encore. Vous ne pouvez pas annuler la suppression.

Renvoie l'identifiant du coupon, deleted: true, et la date de suppression. Si l'application n'a pas de coupon avec cet identifiant, ou si le coupon est déjà supprimé, renvoie 404 avec le code not_found.

DELETE /v1/apps/{appID}/coupons/{id}
curl -X DELETE https://api.abuna.app/v1/apps/8ddhXCDW/coupons/Kf4Wn7Qa \
  -H "Authorization: Bearer sk_test_..."
Réponse
{
  "id": "Kf4Wn7Qa",
  "deleted": true,
  "deleted_at": 1727686400
}

Étapes suivantes