Up- & Downgrades

Mit Produktgruppen definierst du, welche Produkte zusammengehören und wie Kunden zwischen ihnen wechseln können. So ermöglichst du Self-Service Upgrades und Downgrades im Kundenbereich.

Produktgruppen unterscheiden sich von Produktfamilien: Während Produktfamilien nur zur Strukturierung des Katalogs dienen, steuern Produktgruppen die Wechselmöglichkeiten zwischen Produkten.

Anwendungsfälle

Szenario	Beschreibung
Tier-Wechsel	Kunde wechselt von Starter zu Pro Paket
Upgrade	Kunde bucht ein höherwertiges Paket
Downgrade	Kunde wechselt zu einem günstigeren Paket
Mengenwechsel	Kunde ändert die Anzahl der Lizenzen

Konzept

Eine Produktgruppe besteht aus mehreren Tiers (Memberships), die jeweils ein Produkt mit seinen Preisplänen repräsentieren. Die Reihenfolge der Tiers bestimmt die Upgrade-/Downgrade-Richtung.

Produktgruppe: "SaaS Pakete"
├── Position 1: Starter (günstigster)
├── Position 2: Pro
└── Position 3: Enterprise (teuerster)

Upgrade: Wechsel zu einer höheren Position (z.B. Starter → Pro)
Downgrade: Wechsel zu einer niedrigeren Position (z.B. Pro → Starter)

Produktgruppe erstellen

Web-App verwenden
API verwenden

Produktgruppe anlegen

Navigiere zu Produkte > Produktgruppen und klicke auf “Produktgruppe erstellen”.Vergib einen Namen wie “SaaS Pakete” oder “Hosting Plans”.

Tiers hinzufügen

Füge für jedes Paket ein Tier hinzu:

Wähle das Produkt (z.B. “Starter Plan”)
Wähle die Preispläne (z.B. “Starter Monatlich”, “Starter Jährlich”)
Konfiguriere Upgrade/Downgrade-Verhalten

Reihenfolge festlegen

Ordne die Tiers in der gewünschten Reihenfolge an. Die Position bestimmt, was als Upgrade oder Downgrade gilt.

curl -X POST "https://coreapi.io/catalogue/product-groups" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "SaaS Pakete",
    "enabled": true,
    "forceSameBillingInterval": false,
    "memberships": [
      {
        "product": "/products/starter-uuid",
        "pricePlans": ["/plans/starter-monthly-uuid"],
        "position": 1,
        "upgradeable": true,
        "downgradeable": false,
        "changeTiming": "end_of_period",
        "label": "Starter"
      },
      {
        "product": "/products/pro-uuid",
        "pricePlans": ["/plans/pro-monthly-uuid"],
        "position": 2,
        "upgradeable": true,
        "downgradeable": true,
        "changeTiming": "immediately",
        "creditType": "pro_rata",
        "label": "Pro"
      }
    ]
  }'

Tier-Einstellungen

Jedes Tier in einer Produktgruppe hat folgende Einstellungen:

Upgrade & Downgrade

Einstellung	Beschreibung
Upgradeable	Kann zu höheren Positionen gewechselt werden
Downgradeable	Kann zu niedrigeren Positionen gewechselt werden

Das günstigste Paket sollte upgradeable: true, downgradeable: false sein, da es kein niedrigeres Paket gibt.

Wechselzeitpunkt (Change Timing)

Option	Beschreibung
Sofort (`immediately`)	Wechsel wird sofort aktiv
Zum Periodenende (`end_of_period`)	Wechsel wird zum Ende der aktuellen Abrechnungsperiode aktiv

Gutschrift-Typ (Credit Type)

Nur relevant wenn changeTiming = immediately:

Option	Beschreibung
Anteilig (`pro_rata`)	Gutschrift basierend auf verbleibenden Tagen
Vollständig (`full`)	Vollständige Gutschrift der aktuellen Periode
Letzte Rechnung (`last_invoiced`)	Gutschrift der letzten Rechnung
Keine (`none`)	Keine Gutschrift

Produktgruppe zuweisen

Damit Kunden wechseln können, muss die Produktgruppe einem Abonnement-Artikel zugewiesen werden.

Automatische Zuweisung im Checkout: Wenn ein Preisplan einer Produktgruppe zugeordnet ist, wird die Produktgruppe bei Abonnements aus dem Checkout automatisch zugewiesen. Eine manuelle Zuweisung ist nur für Abonnements erforderlich, die in der Wallet erstellt wurden.

Web-App verwenden
API verwenden

Abonnement öffnen

Navigiere zum Abonnement und öffne den Artikel, für den Up-/Downgrades aktiviert werden sollen.

Produktgruppe zuweisen

Unter “Produktgruppe” wähle die entsprechende Gruppe aus.

curl -X PUT "https://coreapi.io/subscription-items/{itemId}/product-group" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "productGroupMembership": "membership-uuid"
  }'

Wechsel durchführen

Im Kundenbereich

Sobald eine Produktgruppe zugewiesen ist, sehen Kunden im Kundenbereich die verfügbaren Wechseloptionen:

Kunde öffnet sein Abonnement
Klickt auf “Ändern”
Wählt das neue Paket und bestätigt
Wechsel wird je nach Konfiguration sofort oder zum Periodenende angewendet

Per API

# 1. Verfügbare Optionen abrufen
curl -X GET "https://coreapi.io/subscription-items/{itemId}/change-options" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 2. Wechsel anwenden
curl -X POST "https://coreapi.io/product-group-memberships/{membershipId}/apply" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "subscriptionItem": "item-uuid",
    "selectedPricePlan": "price-plan-uuid",
    "quantity": 1
  }'

Einstellungen

Gleiches Abrechnungsintervall erzwingen

Mit forceSameBillingInterval: true können Kunden nur zwischen Preisplänen mit gleichem Abrechnungsintervall wechseln. Ein Kunde mit monatlichem Plan sieht dann nur monatliche Optionen.

API Übersicht

Endpoint	Methode	Beschreibung
`/catalogue/product-groups`	GET	Alle Produktgruppen abrufen
`/catalogue/product-groups`	POST	Neue Produktgruppe erstellen
`/catalogue/product-groups/{id}`	GET	Einzelne Produktgruppe abrufen
`/catalogue/product-groups/{id}`	PUT	Produktgruppe aktualisieren
`/catalogue/product-groups/{id}`	DELETE	Produktgruppe löschen
`/subscription-items/{id}/product-group`	PUT	Up- & Downgrades aktivieren
`/subscription-items/{id}/change-options`	GET	Verfügbare Wechseloptionen abrufen
`/product-group-memberships/{id}/apply`	POST	Tier wechseln

Abonnement-Übergänge

Manuelle Übergänge mit Proration

Produkte

Produkte erstellen und verwalten

Kundenbereich

Self-Service für Kunden

API Guide: Upgrades

Upgrades in eigene Apps integrieren

Loslegen

Kunden

Produkte

Nutzungsbasierte Abrechnung

Abonnements

Rechnungen

Zahlungen

Analysen

KI-Assistent

Listen & Filter

Einstellungen

Benachrichtigungen

Buchhaltung

Entwickler

Anwendungsfälle

Konzept

Produktgruppe erstellen

Tier-Einstellungen

Upgrade & Downgrade

Wechselzeitpunkt (Change Timing)

Gutschrift-Typ (Credit Type)

Produktgruppe zuweisen

Wechsel durchführen

Im Kundenbereich

Per API

Einstellungen

Gleiches Abrechnungsintervall erzwingen

API Übersicht

Verwandte Dokumentation

Abonnement-Übergänge

Produkte

Kundenbereich

API Guide: Upgrades

Loslegen

Kunden

Produkte

Nutzungsbasierte Abrechnung

Abonnements

Rechnungen

Zahlungen

Analysen

KI-Assistent

Listen & Filter

Einstellungen

Benachrichtigungen

Buchhaltung

Entwickler

​Anwendungsfälle

​Konzept

​Produktgruppe erstellen

​Tier-Einstellungen

​Upgrade & Downgrade

​Wechselzeitpunkt (Change Timing)

​Gutschrift-Typ (Credit Type)

​Produktgruppe zuweisen

​Wechsel durchführen

​Im Kundenbereich

​Per API

​Einstellungen

​Gleiches Abrechnungsintervall erzwingen

​API Übersicht

​Verwandte Dokumentation

Abonnement-Übergänge

Produkte

Kundenbereich

API Guide: Upgrades

Anwendungsfälle

Konzept

Produktgruppe erstellen

Tier-Einstellungen

Upgrade & Downgrade

Wechselzeitpunkt (Change Timing)

Gutschrift-Typ (Credit Type)

Produktgruppe zuweisen

Wechsel durchführen

Im Kundenbereich

Per API

Einstellungen

Gleiches Abrechnungsintervall erzwingen

API Übersicht

Verwandte Dokumentation