Stripe Billing um nutzerdefinierte Rabattlogik erweiternPrivate Vorschau

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 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.

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

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

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.
• Sie können keine Skript-Gutscheine für Quote-Objekte verwenden.
• Sie können keine Skript-Gutscheine für Customer-Objekte verwenden.

Ein Skript verfassen

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

Rabattrechner-Schnittstelle

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

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.

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. Ein rabattfähiger Artikel könnte beispielsweise folgendermaßen aussehen. Die aktuelle Definition des Parameters finden Sie in unserem SDK.

export interface DiscountableLineItem {
  subtotal: MonetaryAmount;
  price_id?: string | null;
  quantity?: number | null;
  unit_amount?: MonetaryAmount | 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

Ihr Skript muss ein Rabattergebnis zurückgeben.

export interface DiscountResult {
  discount: Discount;
}

Beispiel für die Rückgabe eines Rabattergebnisses:

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

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

import type {
  DiscountCalculationFunction,
  DiscountableItem,
  DiscountResult,
} from '@stripe/scripts/discount_calculation';

import type {PositiveMonetaryAmount, Percent} 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: DiscountCalculationFunction<
  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,
      },
    },
  };
};

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 können Skript-Gutscheine nur an Abonnements oder Rechnungen anhängen.
• Während der Vorschauphase können Sie in Connect keine Skripte an verbundene Konten verteilen.