Skip to content
ABUNA
DocumentationCodes promotionnels

Référence de l'API

Codes promotionnels

Donnez à un coupon des codes que les clients tapent sur la page d'abonnement, chacun avec sa date de fin, sa limite et sa règle pour les nouveaux clients.

Voir en Markdown

Un code promotionnel est le mot qu'un client tape pour obtenir un coupon, comme BLACKFRIDAY. Un coupon peut avoir plusieurs codes, chacun actif ou non, avec sa propre date de fin et sa propre limite. Les codes ignorent la casse : blackfriday fonctionne aussi.

L'objet promotion code

Attributs

  • idstring

    Identifiant unique du code. Les clients tapent le code, pas cet identifiant.
  • app_idstring

    L'application à laquelle le code appartient.
  • codestring

    Le texte que les clients tapent sur la page d'abonnement, comme BLACKFRIDAY.
  • activeboolean

    Si les clients peuvent utiliser le code. Un code désactivé garde ses utilisations et son coupon.
  • expires_attimestampnullable

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

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

    Le nombre d'abonnements qui ont utilisé le code. Il peut dépasser max_redemptions ; voir Lister les codes promotionnels.
  • metadataobject

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

    Quand le code a été créé, en secondes Unix.
  • couponobject

    Le coupon que le code donne.
  • restrictionsobject

    Qui peut utiliser le code.
    Afficher les attributsMasquer les attributs
    • first_time_transactionboolean

      Quand il vaut true, seul un client de cette application qui n'a jamais payé de facture peut l'utiliser. La vérification se fait avec l'adresse e-mail du client.
L'objet promotion code
{
  "id": "Wm9Tb2Xs",
  "app_id": "8ddhXCDW",
  "code": "BLACKFRIDAY",
  "active": true,
  "expires_at": 1798761600,
  "max_redemptions": 100,
  "times_redeemed": 4,
  "metadata": {},
  "created_at": 1727600000,
  "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
  },
  "restrictions": {
    "first_time_transaction": false
  }
}

Créer un code promotionnel

POST/v1/apps/{appID}/promotion-codes

Accepte un en-tête Idempotency-Key.

Crée un code pour l'un des coupons de l'application.

Paramètres

  • couponstringobligatoire

    L'identifiant du coupon que le code donne. Le coupon ne doit pas être supprimé, dépasser son redeem_by, ou être à court d'utilisations.
  • codestring

    Le texte que les clients tapent. Utilisez de 1 à 50 lettres, chiffres, traits d'union ou traits de soulignement. Les codes ignorent la casse et doivent être uniques dans l'application. Omettez ce champ et Abuna crée un code de 8 caractères que vous pouvez lire à voix haute.
  • activeboolean

    Si les clients peuvent l'utiliser tout de suite. Vaut true par défaut.
  • expires_attimestamp

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

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

    Qui peut utiliser le code. Omettez-le pour tout le monde.
    Afficher les paramètresMasquer les paramètres
    • first_time_transactionboolean

      Mettez true pour que seul un client qui n'a jamais payé cette application puisse utiliser le code.
  • metadataobject

    Vos propres clés et valeurs.

Renvoie le code avec son coupon et 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 coupon absent de l'application renvoie 422 avec le code not_found pour coupon. Un coupon qui ne peut pas être utilisé renvoie 422 avec le code invalid pour coupon. Un code déjà pris par un autre code promotionnel de l'application renvoie 409 avec le code code_taken pour code.

POST /v1/apps/{appID}/promotion-codes
curl https://api.abuna.app/v1/apps/8ddhXCDW/promotion-codes \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "coupon": "Kf4Wn7Qa",
    "code": "BLACKFRIDAY",
    "max_redemptions": 100
  }'
Réponse
{
  "id": "Wm9Tb2Xs",
  "app_id": "8ddhXCDW",
  "code": "BLACKFRIDAY",
  "active": true,
  "expires_at": 1798761600,
  "max_redemptions": 100,
  "times_redeemed": 0,
  "metadata": {},
  "created_at": 1727600000,
  "coupon": {
    "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
  },
  "restrictions": {
    "first_time_transaction": false
  }
}

Lister les codes promotionnels

GET/v1/apps/{appID}/promotion-codes

Liste les codes promotionnels de l'application, du plus récent au plus ancien, une page à la fois. Chaque élément porte son coupon.

Paramètres de requête

  • codestring

    Seulement le code avec ce texte. La casse n'a pas d'importance.
  • couponstring

    Seulement les codes de ce coupon.
  • limitinteger

    Combien de codes promotionnels 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.

Un code peut être utilisé par plus d'abonnements que son max_redemptions si des clients payaient déjà au moment où la dernière place s'est remplie. times_redeemed indique le nombre réel.

GET /v1/apps/{appID}/promotion-codes
curl "https://api.abuna.app/v1/apps/8ddhXCDW/promotion-codes?code=BLACKFRIDAY" \
  -H "Authorization: Bearer sk_test_..."
Réponse
{
  "items": [
    {
      "id": "Wm9Tb2Xs",
      "app_id": "8ddhXCDW",
      "code": "BLACKFRIDAY",
      "active": true,
      "expires_at": 1798761600,
      "max_redemptions": 100,
      "times_redeemed": 4,
      "metadata": {},
      "created_at": 1727600000,
      "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
      },
      "restrictions": {
        "first_time_transaction": false
      }
    }
  ],
  "next_cursor": null
}

Lire un code promotionnel

GET/v1/apps/{appID}/promotion-codes/{id}

Renvoie le code et son coupon.

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

GET /v1/apps/{appID}/promotion-codes/{id}
curl https://api.abuna.app/v1/apps/8ddhXCDW/promotion-codes/Wm9Tb2Xs \
  -H "Authorization: Bearer sk_test_..."
Réponse
{
  "id": "Wm9Tb2Xs",
  "app_id": "8ddhXCDW",
  "code": "BLACKFRIDAY",
  "active": true,
  "expires_at": 1798761600,
  "max_redemptions": 100,
  "times_redeemed": 4,
  "metadata": {},
  "created_at": 1727600000,
  "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
  },
  "restrictions": {
    "first_time_transaction": false
  }
}

Mettre à jour un code promotionnel

PATCH/v1/apps/{appID}/promotion-codes/{id}

Active ou désactive le code, change ses métadonnées, ou les deux. Le code, son coupon, sa date de fin et ses limites restent tels que vous les avez créés. Envoyez au moins un champ.

Paramètres

  • activeboolean

    Si les clients peuvent utiliser le code. Envoyez false pour arrêter les nouvelles utilisations. Les abonnements qui l'ont déjà utilisé gardent leur réduction.
  • metadataobject

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

Renvoie le code. Un corps sans aucun des deux champs renvoie 422 avec le code invalid et un élément errors pour active. 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 code avec cet identifiant, renvoie 404 avec le code not_found.

PATCH /v1/apps/{appID}/promotion-codes/{id}
curl https://api.abuna.app/v1/apps/8ddhXCDW/promotion-codes/Wm9Tb2Xs \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -X PATCH \
  -d '{
    "active": false
  }'
Réponse
{
  "id": "Wm9Tb2Xs",
  "app_id": "8ddhXCDW",
  "code": "BLACKFRIDAY",
  "active": false,
  "expires_at": 1798761600,
  "max_redemptions": 100,
  "times_redeemed": 7,
  "metadata": {},
  "created_at": 1727600000,
  "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
  },
  "restrictions": {
    "first_time_transaction": false
  }
}

Étapes suivantes