# Bons de réduction personnalisés Écrivez des scripts pour implémenter une logique personnalisée afin de calculer les montants des réductions pour les abonnements et les factures. 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](https://github.com/stripe/scripts). Vous pouvez utiliser ces scripts comme base pour développer votre propre logique à l’aide de notre [langage de script](https://docs.stripe.com/billing/scripts/script-language.md). Nous vous recommandons de commencer dans un [environnement de test](https://docs.stripe.com/sandboxes.md). ## 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](https://docs.stripe.com/sandboxes.md). #### 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](https://dashboard.stripe.com/test/coupons/create) 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. | Nom | ID | Définition du script | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Pourcentage de réduction avec maximum | `bfsimpl_61S9T2y7zlKu9YlG116S8pZoN2SQpuwOX348dhXM0R9c` | [Voir la définition du script :external: link-to-percent-off-up-to-maximum-script](https://docs.stripe.com/billing/subscriptions/script-coupons.md#percentage-off-up-to-maximum-example) | | ```js { max_discount_amount: { amount: number; currency: string; }, discount_percent: number; } ``` - `max_discount_amount.amount` : valeur dans l’[unité mineure de la devise](https://docs.stripe.com/currencies.md#minor-units) - `max_discount_amount.currency` : le [code ISO](https://docs.stripe.com/currencies.md#presentment-currencies) à trois lettres de la devise - `discount_percent` : valeur en pourcentage | 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 curl https://api.stripe.com/v1/coupons \ -u "<>:" \ -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](https://docs.stripe.com/billing/subscriptions/coupons.md) 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](https://docs.stripe.com/api/quotes.md). - Vous ne pouvez pas utiliser de bons de réduction de type script sur les objets [Customer](https://docs.stripe.com/api/customer.md). ## 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](https://docs.stripe.com/billing/scripts/script-language.md). > #### Vérifiez votre script > > Il vous appartient de vérifier que votre script réalise bien la fonctionnalité souhaitée. Veillez à ne jamais inclure d’informations exclusives ou confidentielles (par exemple, *PII* (Personally identifiable information (PII) is information that, when used alone or with other relevant data, can identify an individual. Examples include passport numbers, driver's license, mailing address, or credit card information)) ou de code malveillant. ### 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. ```typescript export type DiscountCalculationFunction = ( 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. ```typescript 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, l’élément à réduction peut ressembler à ceci. Pour la dernière définition du paramètre, reportez-vous à notre [SDK](https://github.com/stripe/scripts/blob/main/src/discount_calculation/types.ts). Vous verrez des objets Stripe familiers comme [Customer](https://docs.stripe.com/api/customer/object.md) transmis dans le script. Cependant, ces objets ne contiendront qu’un sous-ensemble des données disponibles dans l’API. ```typescript export interface DiscountableLineItem { subtotal: MonetaryAmount; quantity?: number | null; period: TimeRange; price?: Price | null; } export interface DiscountableItem { line_items: Array; gross_amount: MonetaryAmount; customer?: Customer | null; billing_reason?: BillingReason | null; subscription?: Subscription | null; } ``` #### DiscountResult Votre script doit renvoyer un résultat de réduction. ```typescript export interface DiscountResult { discount: Discount; } ``` Exemple de renvoi d’un résultat de réduction : ```typescript return { discount: { amount: { amount: discountAmount, currency: item.gross_amount.currency, }, }, }; ``` ## 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 ```typescript 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, 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](https://github.com/stripe/scripts) 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. ## Exigences de validation des données Votre script doit répondre à ces exigences pour s’exécuter avec succès. Tout manquement entraînera une erreur de validation. - Renvoyez un `DiscountResult` avec `discount.amount` contenant à la fois `amount` (nombre) et `currency` (chaîne de caractères) lors de chaque appel. - `amount` doit être une valeur non négative. - `currency` doit correspondre à la devise de la facture. ## Bonnes pratiques - Vérifiez la devise avant de calculer la remise. Si les devises ne correspondent pas, attribuez une remise de zéro. - Utilisez les types de SDK fournis par Stripe, tels que `PositiveMonetaryAmount` et `Percent` dans votre configuration pour la validation intégrée. - Testez des factures comportant plusieurs articles pour confirmer que la remise s’applique correctement sur le montant brut.