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 verwenden, um Ihre eigene Logik mit unserer Skriptsprache zu erstellen. Wir empfehlen, in einer Sandbox oder im Test-Modus 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 oder im Test-Modus 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 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 Skriptgutscheine nicht mit anderen Skriptgutscheinen 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 DiscountCalculationFunction<C> = (
  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.

export type DiscountCalculatorConfiguration = {
  max_discount_amount: {
    amount: number;
    currency: string;
  },
  discount_percent: number;
};

DiscountableItem

Wir übergeben die 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. Sie werden bekannte Stripe-Objekte wie Kunde/Kundin im Skript sehen. Diese Objekte enthalten jedoch nur einen Teil der Daten, die in der API verfügbar sind.

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

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 {
  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 oder Ihr Konto im Test-Modus, 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 Skript in Ihr Produktionskonto hoch.

Skript zur Überprüfung und zum Testen einreichen

Sie haben Zugriff auf unser öffentliches SDK 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.

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.