Extension de Stripe Billing avec une logique de réduction personnaliséeVersion bêta privée

Stripe Billing vous permet de configurer un bon de réduction avec une logique personnalisée afin de calculer le montant de la réduction pour les abonnements et les factures, au-delà de pourcentages fixes ou de montants de réduction. Voici quelques exemples de ce que vous pouvez faire avec un seul bon de réduction :

• Offrez 10 % de réduction pour les abonnés annuels, mais aucune réduction pour les abonnés mensuels.
• Offrir 20 % de réduction, mais jusqu’à un maximum de 1 000 USD. Ne proposer cette réduction qu’à vos meilleurs clients (identifiés à l’aide de métadonnées).
• Offrez des réductions échelonnées (par exemple, 100 USD s’il y a plus de 10 utilisateurs, sinon 30 USD de réduction).

Démarrer

Pour comprendre comment la logique personnalisée s’intègre au flux de facturation, vous pouvez explorer les scripts Stripe proposés aux utilisateurs de Billing dans notre SDK de script.

Vous pouvez vous servir de ces scripts comme base pour construire votre propre logique à l’aide de notre langage de script. Nous vous recommandons de commencer dans un environnement de test.

Utiliser une logique personnalisée créée par Stripe

Vous pouvez créer un bon de réduction avec une logique personnalisée créée par Stripe en accédant à la page Créer un bon de réduction et en sélectionnant le type Pourcentage de réduction jusqu’au maximum. Cela vous donne une idée de la façon dont les scripts logiques personnalisés sont appliqués à un bon de réduction avant de créer votre propre script.

Créer un bon de réduction

Nous vous recommandons de démarrer ce processus dans un environnement de test. Nous ne prenons pas en charge les scripts en mode test. Pour tout test, vous devez utiliser un environnement de test.

Créer un bon de réduction no-code

Vous pouvez créer un bon de réduction avec une logique personnalisée créée par Stripe en accédant à la page de création d’un bon de réduction et en utilisant le type de bon de réduction Percentage off up to maximum, qui utilise un script créé par Stripe.

Créer un bon de réduction à l’aide de l’API

Pour créer des bons de réduction de type script avec l’API, reportez-vous au tableau ci-dessous pour connaître les spécifications du script.

{
  max_discount_amount: {
    amount: number;
    currency: string;
  },
  discount_percent: number;
}

Par exemple, voici à quoi ressemblerait la configuration d’un bon de réduction de 20 % avec plafond de 100 USD à l’aide de l’option Percentage off up to maximum :

curl https://api.stripe.com/v1/coupons \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d duration=forever \
  -d name="My coupon" \
  -d "script[id]"=bfsimpl_61S9T2y7zlKu9YlG116S8pZoN2SQpuwOX348dhXM0R9c \
  -d "script[configuration][max_discount_amount][amount]"=10000 \
  -d "script[configuration][max_discount_amount][currency]"=usd \
  -d "script[configuration][discount_percent]"=20

Appliquer un bon de réduction

Après avoir créé le bon de réduction, appliquez-le aux abonnements ou aux factures en suivant le même processus que pour un bon de réduction standard. Reportez-vous à la section sur les bons de réduction pour obtenir des instructions détaillées.

Limites des bons de réduction de type script

Les bons de réduction de type script présentent les limitations suivantes :

• Vous ne pouvez pas utiliser de bons de réduction de type script sur les bons de réduction de poste de facture.
• Vous ne pouvez pas cumuler des bons de réduction de type script avec d’autres bons de réduction.
• You can’t use script coupons on Quote objects.
• Les bons de réduction de type script ne sont pas pris en charge en mode payment pour les sessions Checkout.
• Les bons de réduction de type script ne sont pris en charge que dans les versions de l’API postérieures à 2025-03-31.preview.

Création d’un script

Pour répondre aux besoins spécifiques de votre entreprise, vous pouvez créer votre logique personnalisée à l’aide de notre langage de script.

Interface du calculateur de réduction

Tous les scripts de bon de réduction doivent respecter l’interface du calculateur de réduction définie par Stripe.

export type DiscountFunction<T> = (
  configuration: T,
  discountableItem: DiscountableItem,
) => DiscountResult;

Configuration

Vous pouvez définir des valeurs de configuration que les utilisateurs doivent fournir lorsqu’ils créent un bon de réduction de type script. Les valeurs de configuration définies pour le bon de réduction sont transmises à la fonction de réduction chaque fois que vous l’appelez.

export type DiscountCalculatorConfiguration = {
  max_discount_amount: {
    amount: number;
    currency: string;
  },
  discount_percent: number;
};

DiscountableItem

Nous transmettons le DiscountableItem dans le calculateur de remise et mettons ces données à votre disposition pour que vous puissiez les utiliser dans votre script. Nous fournissons à votre script les informations suivantes :

export interface DiscountableItem {
  id: string;
  gross_amount: MonetaryAmount;
  line_items: Array<DiscountableLineItem>;
}
export interface DiscountableLineItem {
  id: string;
  subtotal: MonetaryAmount;
  price_id?: string;
  is_free_trial: boolean;
  is_recurring: boolean;
  quantity?: number;
  unit_amount?: MonetaryAmount;
  period?: TimeRange;
}

DiscountResult

Votre script doit renvoyer un résultat de réduction.

export type DiscountStatus = 'APPLIED' | 'NOT_APPLIED';

export type Discount = {
 amount: MonetaryAmount;
 status: DiscountStatus;
 reason?: string;
};

export type ItemDiscount = {
 discountable_item_id: string;
 discount: Discount;
};

export type DiscountResult = {
 discount?: Discount;
 line_item_discounts: Array<ItemDiscount>;
};

Exemple de renvoi d’un résultat de réduction :

return {
  discount: {
    amount: {
      amount: discount_amount,
      currency: item.gross_amount.currency,
    },
    status: discount_amount > 0 ? 'APPLIED' : 'NOT_APPLIED',
    reason: discount_amount > 0 ? 'Discount applied' : 'No discount applied',
  },
  line_item_discounts: [],
};

Bonnes pratiques

• Dans la mesure du possible, utilisez des types définis par Stripe dans votre configuration (par exemple, MonetaryAmount)
• Effectuez une vérification des devises avant d’appliquer votre réduction.

Exemples de scripts

Si vous avez accès à la version bêta privée, vous pouvez envoyer votre logique de réduction personnalisée à l’équipe Stripe Billing par e-mail. Les exemples de scripts ci-dessous vous permettent de vous faire une idée de la logique personnalisée que vous pouvez créer et vous donnent un modèle avec lequel démarrer.

Réduction en pourcentage avec un montant maximum

import {MonetaryAmount, Percent} from '@stripe/scripts';
import {
  DiscountCalculatorFunction,
  DiscountableItem,
  DiscountResult,
} from '@stripe/scripts/discounts';

/**
 * Configuration for the discount calculator function
 */
export type DiscountCalculatorConfiguration = {
  max_discount_amount: MonetaryAmount;
  discount_percent: Percent;
};

/**
 * Gives a percentage off discount upto a maximum discount amount
 *
 * @param {DiscountCalculatorConfiguration} config - The configuration containing max discount amount and discount percent
 * @param {DiscountableItem} item - The items to apply discounts to
 * @returns {DiscountResult} - The discounts applied to the items
 */
const percentOffUptoMaxDiscount: DiscountCalculatorFunction<
  DiscountCalculatorConfiguration
> = (
  config: DiscountCalculatorConfiguration,
  item: DiscountableItem,
): DiscountResult => {
  const {max_discount_amount, discount_percent} = config;
  let discountAmount = 0;

  if (
    item.gross_amount.currency.toLowerCase().trim() ===
    max_discount_amount.currency.toLowerCase().trim()
  ) {
    const discountAmountValue =
      (item.gross_amount.amount * discount_percent) / 100;
    discountAmount = Math.min(discountAmountValue, max_discount_amount.amount);
  }

  return {
    discount: {
      amount: {
        amount: discountAmount,
        currency: item.gross_amount.currency,
      },
      status: discountAmount > 0 ? 'APPLIED' : 'NOT_APPLIED',
      reason: discountAmount > 0 ? 'Discount applied' : 'No discount applied',
    },
    line_item_discounts: [],
  };
};

export default percentOffUptoMaxDiscount;

Tester votre script

Nous vous recommandons de tester la logique créée par Stripe pour vous familiariser avec le workflow. Si vous avez accès à la version bêta privée, nous chargeons votre logique personnalisée dans un environnement de test sur votre compte, où vous pourrez effectuer les tests nécessaires pour vérifier qu’elle fonctionne comme prévu. Une fois que vous l’avez validée dans votre environnement de test, Stripe charge votre script sur votre compte de production.

Soumettez votre script à des fins de révision et de test

Une fois que vous aurez intégré la version bêta privée, vous aurez accès à un SDK contenant des outils de création, de test et de package de scripts. Vous pourrez soumettre vos packages de scripts à Stripe pour vérification.

Après approbation, nous importerons votre logique personnalisée dans l’environnement de test de votre choix pour la tester avant de l’appliquer à votre environnement de production.

Critères d’admissibilité à la version bêta privée

Cette fonctionnalité est en version bêta privée et est en cours de développement. Les fonctionnalités peuvent évoluer à mesure que nous poursuivons le développement des scripts. Points importants à prendre en compte :

• Vous devez utiliser la version 2025-03-31.preview ou une version ultérieure. Il s’agit de la version par défaut si vous êtes un nouvel utilisateur, mais vous pouvez effectuer une mise à niveau si vous êtes un utilisateur existant.
• Vous pouvez uniquement associer des bons de réduction avec script aux nouveaux abonnements ou factures.
• Checkout prend uniquement en charge l’utilisation de codes promotionnels activés pour les scripts en mode subscription.
• Pendant la version bêta, vous ne pouvez pas distribuer de scripts aux comptes connectés dans Connect.