Stripe Billing um nutzerdefinierte Rabattlogik erweiternPrivate Vorschau

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 benutzerdefinierte Logik in den Abrechnungs-Workflow integriert wird, können Sie die von Stripe verfasste Skripte untersuchen, die Billing-Nutzerinnen und -Nutzern in unserem Skript-SDK zur Verfügung stehen.

Sie können diese Skripte als Grundlage für die Erstellung Ihrer eigenen Logik mit unserer Skriptsprache verwenden. Wir empfehlen, in einer Sandbox zu beginnen.

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 Vorgang in einer Sandbox zu starten. Im Test-Modus werden keine Skripts unterstützt. Für alle Tests müssen Sie eine Sandbox-Umgebung verwenden.

Gutschein ohne Code erstellen

Sie können einen Gutschein mit einer von Stripe selbst erstellten nutzerdefinierten Logik erstellen, indem Sie zur Seite Gutschein erstellen 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
Configuration fields `{ max_discount_amount: { amount: number; currency: string; }, discount_percent: number; }` `max_discount_amount.amount`: Wert in der Nebeneinheit der Währung `max_discount_amount.currency`: Der dreistellige ISO-Code für die Währung `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:

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.

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 Script-Gutscheine nicht mit anderen Gutscheinen stapeln.
You can’t use script coupons on Quote objects.
Skript-Gutscheine werden im payment-Modus für Checkout-Sitzungen nicht unterstützt.
Skript-Gutscheine werden nur in späteren API-Versionen als 2025-03-31.preview unterstützt.

Ein Skript verfassen

Um spezifische Geschäftsanforderungen zu erfüllen, können Sie mit unserer Skriptsprache Ihre eigene benutzerdefinierte Logik erstellen.

Notiz

Sie sind dafür verantwortlich, zu überprüfen, ob Ihr Skript die gewünschte Funktionalität aufweist. Geben Sie keine geschützten, vertraulichen Informationen (z. B. PII) oder bösartigen Code ein.

Rabattrechner-Schnittstelle

Alle Gutscheinskripts müssen der von Stripe definierten Schnittstelle für den Rabattrechner entsprechen.

Discount calculator interface
export type DiscountFunction<T> = (
  configuration: T,
  discountableItem: 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.

Sample script configuration
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 zur Verwendung in Ihrem Skript zur Verfügung. Ihr Skript wird mit den folgenden Informationen versehen:

DiscountableItem definition
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

Ihr Skript muss ein Rabattergebnis zurückgeben.

Discountable result
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>;
};

Notiz

line_item_discounts sind Rabatte, die auf die Rechnungsposten angewendet werden und nicht auf den übergeordneten discount übertragen werden. Der oberste discount ist der Rabatt, der unabhängig von den line_item_discount auf die Rechnung angewendet wird.

Beispiel für die Rückgabe eines Rabattergebnisses:

Sample Discountable result (truncated)
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: [],
};

Best Practices

Verwenden Sie nach Möglichkeit von Stripe definierte Typen in Ihrer Konfiguration (z. B. MonetaryAmount)
Führen Sie eine Währungsprüfung durch, bevor Sie Ihren Rabatt anwenden.

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

Percent-up-to-max script  (truncated)
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;

Skript testen

Wir empfehlen Ihnen, die von Stripe erstellte Logik zu testen, um sich mit dem Ablauf vertraut zu machen. Wenn Sie Zugriff auf die private Vorschau haben, laden wir Ihre nutzerdefinierte Logik in eine Sandbox auf Ihrem Konto, wo Sie die erforderlichen Tests durchführen können, um zu überprüfen, ob sie wie erwartet funktioniert. Nachdem Sie es in Ihrer Sandbox-Umgebung validiert haben, lädt Stripe Ihr Skript in Ihr Produktionskonto hoch.

Skript zur Überprüfung und zum Testen einreichen

Nach der Annahme in der privaten Vorschau erhalten Sie Zugriff auf ein SDK mit Tools zum Erstellen, Testen und Verpacken von Skripts. Sie können Ihre verpackten Skripts zur Überprüfung an senden.

Nach der Genehmigung importieren wir Ihre benutzerdefinierte Logik zum Testen in eine Sandbox Ihrer Wahl, bevor Sie sie auf Ihre Produktionsumgebung anwenden.

Eignungskriterien für die private Vorschau

Dieses Feature befindet sich in der privaten Vorschau und ist noch in der Entwicklung. Die Funktionalität kann sich ändern, wenn wir die Entwicklung von Skripten fortsetzen. Beachten Sie Folgendes:

Sie müssen Version 2025-03-31.preview oder neuer verwenden. Dies ist die Standardversion, wenn Sie ein/e neue/r Nutzer/in sind. Wenn Sie bereits ein/e bestehende/r Nutzer/in sind, können Sie ein Upgrade durchführen.
Sie können Skript-Gutscheine nur an neue Abonnements oder Rechnungen anhängen.
Checkout unterstützt die Verwendung von Promo-Codes, für die ein Skript aktiviert wurde, nur im Modus subscription.
Während der Vorschauphase können Sie in Connect keine Skripte an verbundene Konten verteilen.