# Nutzerdefinierte Gutscheine Implementieren Sie benutzerdefinierte Logik, um Rabattbeträge für Abonnements und Rechnungen zu berechnen. Mit Stripe Billing können Sie einen Gutschein mit nutzerdefinierter Logik konfigurieren, um den Rabattbetrag für Abonnements und Rechnungen zu berechnen, der über feste Prozentsätze oder Rabattbeträge hinausgeht. Hier sind einige Beispiele dafür, was Sie mit einem einzigen Gutschein tun können: - Bieten Sie 10 % Rabatt für Jahresabonnenten, aber keinen Rabatt für Monatsabonnenten. - Bieten Sie 20 % Rabatt, jedoch bis zu einem Höchstbetrag von 1000 USD. Stellen Sie dies nur Ihren Kundinnen und Kunden mit hochwertigem Profil zur Verfügung (gekennzeichnet durch Metadaten). - Bieten Sie gestaffelte Rabatte an (zum Beispiel 100 USD Rabatt beim Kauf von mehr als 10 Plätzen, andernfalls 30 USD Rabatt. ## Loslegen Um zu verstehen, wie sich nutzerdefinierte Logik in den Abrechnungs-Workflow integrieren lässt, können Sie sich die von Stripe verfassten Skripts ansehen, die Billing-Nutzer/innen in unserem [Skript-SDK](https://github.com/stripe/scripts) zur Verfügung stehen. Sie können diese Scripts als Grundlage verwenden, um Ihre eigene Logik mit unserer [Scriptsprache](https://docs.stripe.com/billing/scripts/script-language.md) zu erstellen. Wir empfehlen, in einer [Sandbox](https://docs.stripe.com/sandboxes.md) zu starten. ## Von Stripe erstellte nutzerdefinierte Logik verwenden Sie können einen Gutschein mit der benutzerdefinierten Logik **von Stripe verfasst** erstellen, indem Sie zur Seite **Gutschein erstellen** navigieren und den Typ **Prozentualer Rabatt bis zum Höchstbetrag** auswählen. So erhalten Sie eine Vorstellung davon, wie Skripts mit nutzerdefinierter Logik auf einen Gutschein angewendet werden, bevor Sie Ihr eigenes Skript erstellen. ### Gutschein erstellen Wir empfehlen, diesen Prozess in einer [Sandbox](https://docs.stripe.com/sandboxes.md) zu starten. #### Gutschein ohne Code erstellen Sie können einen Gutschein mit einer von Stripe selbst erstellten nutzerdefinierten Logik erstellen, indem Sie zur Seite [Gutschein erstellen](https://dashboard.stripe.com/test/coupons/create) navigieren und den neuen Gutscheintyp `Percentage off up to maximum` verwenden, der von einem von Stripe erstellten Skript unterstützt wird. #### Gutschein mit der API erstellen Informationen zum Erstellen von Skriptgutscheinen mit der API finden Sie in der folgenden Tabelle für die Skriptspezifikationen. | Name | ID | Skriptdefinition | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Prozentualer Rabatt bis zum Höchstbetrag | `bfsimpl_61S9T2y7zlKu9YlG116S8pZoN2SQpuwOX348dhXM0R9c` | [Siehe Skriptdefinition :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`: Wert in der [Nebeneinheit der Währung](https://docs.stripe.com/currencies.md#minor-units) - `max_discount_amount.currency`: Der dreistellige [ISO-Code für die Währung](https://docs.stripe.com/currencies.md#presentment-currencies) - `discount_percent`: Wert als Prozentsatz | Wenn Sie beispielsweise einen Gutschein über 20 % Rabatt bis zu 100 USD mit `Percentage off up to maximum` konfigurieren, sieht dies folgendermaßen aus: ```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" ``` ### Gutschein anwenden Nachdem Sie den Gutschein erstellt haben, können Sie ihn wie jeden anderen Standard-Gutschein auf Abonnements oder Rechnungen anwenden. Detaillierte Anweisungen finden Sie in der Dokumentation zu [Gutscheinen](https://docs.stripe.com/billing/subscriptions/coupons.md). ### Einschränkungen für Skript-Gutscheine Für Skript-Gutscheine gelten folgende Einschränkungen: - Sie können Script-Gutscheine nicht für Artikelgutscheine verwenden. - Sie können Skriptgutscheine nicht mit anderen Skriptgutscheinen stapeln. - Sie können keine Skript-Gutscheine für [Quote](https://docs.stripe.com/api/quotes.md)-Objekte verwenden. - Sie können keine Skript-Gutscheine für [Customer](https://docs.stripe.com/api/customer.md)-Objekte verwenden. ## Ein Skript verfassen Um spezifische Geschäftsanforderungen zu erfüllen, können Sie mit unserer [Skriptsprache](https://docs.stripe.com/billing/scripts/script-language.md) Ihre eigene benutzerdefinierte Logik erstellen. > #### Script verifizieren > > Sie sind dafür verantwortlich, zu überprüfen, ob Ihr Script Ihre gewünschte Funktionalität widerspiegelt. Geben Sie keine proprietären, vertraulichen Informationen (zum Beispiel *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)) oder schadhaften Code ein. ### Rabattrechner-Schnittstelle Alle Gutscheinskripts müssen der von Stripe definierten Schnittstelle für den Rabattrechner entsprechen. ```typescript export type DiscountCalculationFunction = ( run_context: RunContext, configuration: C, discountable_item: DiscountableItem, ) => DiscountResult; ``` #### Konfiguration Sie können Konfigurationswerte definieren, die Nutzer/innen beim Erstellen eines Gutscheins vom Typ „Skript“ angeben müssen. Die für den Gutschein festgelegten Konfigurationswerte werden bei jedem Aufruf der Rabattfunktion übergeben. ```typescript export type DiscountCalculatorConfiguration = { max_discount_amount: { amount: number; currency: string; }, discount_percent: number; }; ``` #### DiscountableItem Wir übergeben den `DiscountableItem` an den Rabattrechner und stellen Ihnen diese Daten für die Verwendung in Ihrem Skript zur Verfügung. Als Beispiel könnte das rabattfähige Produkt wie folgt aussehen. Die aktuelle Definition des Parameters finden Sie in unserem [SDK](https://github.com/stripe/scripts/blob/main/src/discount_calculation/types.ts). Sie werden bekannte Stripe-Objekte wie [Kunde/Kundin](https://docs.stripe.com/api/customer/object.md) im Skript sehen. Diese Objekte enthalten jedoch nur einen Teil der Daten, die in der API verfügbar sind. ```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 Ihr Skript muss ein Rabattergebnis zurückgeben. ```typescript export interface DiscountResult { discount: Discount; } ``` Beispiel für die Rückgabe eines Rabattergebnisses: ```typescript return { discount: { amount: { amount: discountAmount, currency: item.gross_amount.currency, }, }, }; ``` ## Beispielskripte Wenn Sie Zugriff auf die private Vorschau haben, können Sie Ihre nutzerdefinierte Rabattlogik per E-Mail an das Stripe Billing-Team übermitteln. Die folgenden Beispielskripts ermöglichen es Ihnen, ein Gefühl für die nutzerdefinierte Logik zu bekommen, die Sie erstellen können, und geben Ihnen eine Vorlage, mit der Sie arbeiten können. ### Prozentualer Rabatt mit einem Höchstbetrag ```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; ``` ## Skript testen Wir empfehlen Ihnen, die von Stripe autorisierte Logik zu testen, um sich mit dem Arbeitsablauf vertraut zu machen. Wenn Sie Zugriff auf die private Vorschau haben, laden wir Ihre benutzerdefinierte Logik in eine Sandbox, wo Sie die erforderlichen Tests durchlaufen können, um zu überprüfen, ob sie wie erwartet funktioniert. Nachdem Sie sie in Ihrer Testumgebung validiert haben, lädt Stripe Ihr Script in Ihr Produktionskonto hoch. ### Skript zur Überprüfung und zum Testen einreichen Sie haben Zugriff auf unser öffentliches [SDK](https://github.com/stripe/scripts) mit Tools zum Erstellen, Testen und Verpacken von Skripten. Sie können Ihre verpackten Skripte zur Überprüfung an Stripe senden. Nach der Genehmigung importieren wir Ihre benutzerdefinierte Logik in eine Sandbox Ihrer Wahl oder Ihren Test-Modus. Sobald Sie überprüft haben, ob sie wie erwartet funktioniert, wenden wir sie auf Ihre Produktionsumgebung an. ## Anforderungen an die Datenvalidierung Ihr Script muss diese Anforderungen erfüllen, um erfolgreich ausgeführt zu werden. Verstöße führen zu einem Validierungsfehler. - Geben Sie ein `DiscountResult` mit `discount.amount` zurück, das bei jedem Aufruf sowohl `amount` (Zahl) als auch `currency` (Zeichenfolge) enthält. - `amount` darf nicht negativ sein. - `currency` muss mit der Rechnungswährung übereinstimmen. ## Best Practices - Führen Sie eine Währungsprüfung durch, bevor Sie den Rabatt berechnen. Wenn die Währungen nicht übereinstimmen, geben Sie einen Rabatt von Null zurück. - Verwenden Sie für die integrierte Validierung von Stripe bereitgestellte SDK-Typen wie `PositiveMonetaryAmount` und `Percent` in Ihrer Konfiguration. - Erstellen Sie Testrechnungen mit mehreren Posten, um zu bestätigen, dass der Rabatt korrekt auf den Bruttobetrag angewendet wird.