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 workflow de facturation, vous pouvez explorer les scripts créés par Stripe et mis à disposition des utilisateurs de Billing dans notre SDK de script.

Vous pouvez utiliser ces scripts comme base pour développer votre propre logique à l’aide de notre langage de script. Nous vous recommandons de commencer dans un environnement de test ou en mode 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 commencer ce processus dans un environnement de test ou en mode 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 de bons de réduction script avec d’autres bons de réduction script.
• Vous ne pouvez pas utiliser de bons de réduction de type script sur les objets Quote.
• Vous ne pouvez pas utiliser de bons de réduction de type script sur les objets Customer.

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 DiscountCalculationFunction<C> = (
  run_context: RunContext,
  configuration: C,
  discountable_item: 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 réduction et mettons ces données à votre disposition pour utilisation dans votre script. Par exemple, le élément à réduction peut ressembler à ceci. Pour la dernière définition du paramètre, reportez-vous à notre SDK. Vous verrez des objets Stripe familiers comme Customer transmis dans le script. Cependant, ces objets ne contiendront qu’un sous-ensemble des données disponibles dans l’API.

export interface DiscountableLineItem {
  subtotal: MonetaryAmount;
  quantity?: number | null;
  period: TimeRange;
  price?: Price | null;
}

export interface DiscountableItem {
  line_items: Array<DiscountableLineItem>;
  gross_amount: MonetaryAmount;
  customer?: Customer | null;
  billing_reason?: BillingReason | null;
  subscription?: Subscription | null;
}

DiscountResult

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

export interface DiscountResult {
  discount: Discount;
}

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

return {
    discount: {
      amount: {
        amount: discountAmount,
        currency: item.gross_amount.currency,
      },
    },
  };

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 type {
  ComputeDiscountsFunction,
  DiscountCalculation,
  DiscountableItem,
  DiscountResult,
} from '@stripe/scripts/discount_calculation';

import type {PositiveMonetaryAmount, Percent, RunContext} from '@stripe/scripts';

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

/**
 * Gives a percentage off discount up to a maximum discount amount
 *
 * @param {DiscountCalculatorConfiguration} config-The configuration containing max discount amount and discount percent
 * @param {DiscountableItem} item-The item to apply discounts to
 * @returns {DiscountResult} The discounts applied to the item
 */
const percentOffUptoMaxDiscount: ComputeDiscountsFunction<
  DiscountCalculatorConfiguration
> = (
  run_context: RunContext,
  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,
      },
    },
  };
};

const computePercentOffUptoMaxDiscount: DiscountCalculation<
  DiscountCalculatorConfiguration
> = {
  computeDiscounts: percentOffUptoMaxDiscount,
};

export default computePercentOffUptoMaxDiscount;

Tester votre script

Nous vous recommandons de tester la logique développée par Stripe afin de vous familiariser avec le flux de travail. Si vous avez accès à la version privée, nous chargeons votre logique personnalisée dans un environnement de test ou dans votre compte en mode test, afin que vous puissiez effectuer les tests nécessaires pour vérifier son bon fonctionnement. Une fois la validation terminée dans votre environnement de test, Stripe charge votre script dans votre compte de production.

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

Vous pouvez accéder à notre SDK public avec des outils de autorisation, de test et de packaging de scripts. Vous pouvez soumettre vos scripts packagés à Stripe pour vérifier.

Après approbation, nous importerons votre logique personnalisée dans l’environnement de test de votre choix ou en mode test. Une fois que vous aurez vérifié son bon fonctionnement, nous l’appliquerons à 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 ne pouvez associer des bons de réduction de type script qu’aux abonnements ou aux factures.
• Pendant la version bêta, vous ne pouvez pas distribuer de scripts aux comptes connectés dans Connect.