> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fynn.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# Up- & Downgrades

> Definiere Upgrade- und Downgrade-Pfade für Self-Service Paketwechsel

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.

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

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

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Produktgruppe anlegen">
        Navigiere zu **Produkte > Produktgruppen** und klicke auf "Produktgruppe erstellen".

        Vergib einen Namen wie "SaaS Pakete" oder "Hosting Plans".
      </Step>

      <Step title="Tiers hinzufügen">
        Füge für jedes Paket ein Tier hinzu:

        1. Wähle das **Produkt** (z.B. "Starter Plan")
        2. Wähle die **Preispläne** (z.B. "Starter Monatlich", "Starter Jährlich")
        3. Konfiguriere **Upgrade/Downgrade-Verhalten**
      </Step>

      <Step title="Reihenfolge festlegen">
        Ordne die Tiers in der gewünschten Reihenfolge an. Die Position bestimmt, was als Upgrade oder Downgrade gilt.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    ```bash theme={null}
    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"
          }
        ]
      }'
    ```
  </Tab>
</Tabs>

***

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

<Tip>
  Das günstigste Paket sollte `upgradeable: true, downgradeable: false` sein, da es kein niedrigeres Paket gibt.
</Tip>

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

<Tip>
  **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.
</Tip>

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Abonnement öffnen">
        Navigiere zum Abonnement und öffne den Artikel, für den Up-/Downgrades aktiviert werden sollen.
      </Step>

      <Step title="Produktgruppe zuweisen">
        Unter "Produktgruppe" wähle die entsprechende Gruppe aus.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    ```bash theme={null}
    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"
      }'
    ```
  </Tab>
</Tabs>

***

## Wechsel durchführen

### Im Kundenbereich

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

1. Kunde öffnet sein Abonnement
2. Klickt auf "Ändern"
3. Wählt das neue Paket und bestätigt
4. Wechsel wird je nach Konfiguration sofort oder zum Periodenende angewendet

### Per API

```bash theme={null}
# 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`](/api-reference/productgroup/get-product-groups)                | GET     | Alle Produktgruppen abrufen        |
| [`/catalogue/product-groups`](/api-reference/productgroup/create-product-group)              | POST    | Neue Produktgruppe erstellen       |
| [`/catalogue/product-groups/{id}`](/api-reference/productgroup/get-product-group)            | GET     | Einzelne Produktgruppe abrufen     |
| [`/catalogue/product-groups/{id}`](/api-reference/productgroup/update-product-group)         | PUT     | Produktgruppe aktualisieren        |
| [`/catalogue/product-groups/{id}`](/api-reference/productgroup/delete-product-group)         | DELETE  | Produktgruppe löschen              |
| [`/subscription-items/{id}/product-group`](/api-reference/productgroup/assign-product-group) | PUT     | Up- & Downgrades aktivieren        |
| [`/subscription-items/{id}/change-options`](/api-reference/productgroup/get-change-options)  | GET     | Verfügbare Wechseloptionen abrufen |
| [`/product-group-memberships/{id}/apply`](/api-reference/productgroup/apply-membership)      | POST    | Tier wechseln                      |

***

## Verwandte Dokumentation

<CardGroup cols={2}>
  <Card title="Abonnement-Übergänge" icon="arrow-right-arrow-left" href="/guide/subscriptions/transitions">
    Manuelle Übergänge mit Proration
  </Card>

  <Card title="Produkte" icon="box" href="/guide/catalogue/products">
    Produkte erstellen und verwalten
  </Card>

  <Card title="Kundenbereich" icon="user" href="/guide/customers/customer-portal">
    Self-Service für Kunden
  </Card>

  <Card title="API Guide: Upgrades" icon="code" href="/api-reference/guides/implement-upgrades">
    Upgrades in eigene Apps integrieren
  </Card>
</CardGroup>