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

# Subscription Transition

> Transition a subscription to new products and price plans.

Wechsle Produkte und Preispläne in einem bestehenden Abonnement mit automatischer Proration und Gutschriften.

<Warning>
  Gekündigte Abonnements können nicht mehr transitioniert werden.
</Warning>

## POST /api/subscriptions/\[subscriptionId]/transition

Führt einen Übergang zu neuen Produkten/Preisplänen durch.

### Request

```bash theme={null}
curl -X POST "https://coreapi.io/api/subscriptions/550e8400-e29b-41d4-a716-446655440000/transition" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "effectiveAt": "2026-02-15T00:00:00Z",
    "desiredItems": [
      {
        "productId": "prod-premium-plan",
        "pricePlanId": "price-100-monthly",
        "quantity": 1
      }
    ],
    "proration": "creditProrated",
    "invoiceTiming": "phaseStart"
  }'
```

### Request Body

<ParamField body="effectiveAt" type="string" required>
  Zeitpunkt des Übergangs im ISO 8601 Format. Muss in der Zukunft oder jetzt sein. Ab diesem Zeitpunkt gelten die neuen Items.
</ParamField>

<ParamField body="desiredItems" type="array" required>
  Liste der gewünschten Items nach dem Übergang. Mindestens 1 Item erforderlich.

  <Expandable title="Item-Objekt">
    <ParamField body="productId" type="string" required>
      UUID des Produkts
    </ParamField>

    <ParamField body="pricePlanId" type="string" required>
      UUID des Preisplans
    </ParamField>

    <ParamField body="quantity" type="number" required>
      Menge (muss positiv sein). Für nutzungsbasierte Produkte ist dieser Wert immer `1` - die tatsächliche Menge wird durch Nutzungsereignisse bestimmt.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="proration" type="string" default="none">
  Wie sollen Gutschriften für nicht genutzte Zeit berechnet werden?

  | Wert             | Beschreibung                                           |
  | ---------------- | ------------------------------------------------------ |
  | `creditProrated` | Anteilige Gutschrift basierend auf verbleibenden Tagen |
  | `none`           | Keine Gutschrift                                       |

  <Note>
    Die Gutschrift wird sofort finalisiert und an den Kunden gesendet. Der Guthabenbetrag wird automatisch mit der nächsten Rechnung verrechnet.
  </Note>
</ParamField>

<ParamField body="invoiceTiming" type="string" default="phaseStart">
  Wann sollen die neuen Items abgerechnet werden?

  | Wert          | Beschreibung                                                                                                                                              |
  | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `phaseStart`  | Rechnung wird zum Übergangszeitpunkt (`effectiveAt`) erstellt. Teilperioden von nutzungsbasierten Items werden ebenfalls zu diesem Zeitpunkt abgerechnet. |
  | `immediately` | Rechnung wird sofort erstellt mit Leistungsdatum ab `effectiveAt`. Teilperioden von nutzungsbasierten Items werden ebenfalls sofort abgerechnet.          |
</ParamField>

<ParamField body="cancelReason" type="string">
  Optionaler Grund für die Beendigung der alten Items (max. 255 Zeichen)
</ParamField>

<ParamField body="dryRun" type="boolean" default="false">
  Wenn `true`, wird eine Vorschau der Änderungen zurückgegeben ohne sie zu speichern
</ParamField>

### Response (200 OK)

```json theme={null}
{
  "previousPhase": {
    "phaseId": "phase-old-123",
    "status": "Completed",
    "startAt": "2026-01-01T00:00:00Z",
    "endAt": "2026-02-15T00:00:00Z",
    "items": [...]
  },
  "newPhase": {
    "phaseId": "phase-new-456",
    "status": "Active",
    "startAt": "2026-02-15T00:00:00Z",
    "endAt": null,
    "items": [...]
  },
  "changes": {
    "itemsRemoved": [
      {
        "subscriptionItemId": "item-old-789",
        "productId": "prod-basic-plan",
        "productName": "Basic Plan",
        "cancelReason": "Upgraded to Premium"
      }
    ],
    "itemsAdded": [
      {
        "subscriptionItemId": "item-new-101",
        "productId": "prod-premium-plan",
        "productName": "Premium Plan",
        "quantity": 1
      }
    ]
  },
  "creditNoteId": "cn-abc-123"
}
```

<ResponseField name="previousPhase" type="object">
  Die abgeschlossene Phase mit den alten Items
</ResponseField>

<ResponseField name="newPhase" type="object">
  Die neue aktive Phase mit den neuen Items
</ResponseField>

<ResponseField name="changes" type="object">
  Übersicht der entfernten und hinzugefügten Items
</ResponseField>

<ResponseField name="creditNoteId" type="string">
  ID der erstellten Gutschrift (falls vorhanden, nur bei Festpreis-Produkten)
</ResponseField>

***

## Beispiele

### Upgrade mit anteiliger Gutschrift

```json theme={null}
{
  "effectiveAt": "2026-02-01T00:00:00Z",
  "desiredItems": [
    {
      "productId": "prod-pro-plan",
      "pricePlanId": "price-pro-monthly",
      "quantity": 1
    }
  ],
  "proration": "creditProrated",
  "invoiceTiming": "phaseStart"
}
```

### Sofortige Abrechnung

```json theme={null}
{
  "effectiveAt": "2026-02-15T12:00:00Z",
  "desiredItems": [
    {
      "productId": "prod-enterprise",
      "pricePlanId": "price-enterprise-yearly",
      "quantity": 1
    }
  ],
  "proration": "creditProrated",
  "invoiceTiming": "immediately"
}
```

### Vorschau (Dry-Run)

```json theme={null}
{
  "effectiveAt": "2026-02-01T00:00:00Z",
  "desiredItems": [...],
  "proration": "creditProrated",
  "dryRun": true
}
```

***

## Fehler-Codes

| HTTP Status | Code                     | Beschreibung                     |
| ----------- | ------------------------ | -------------------------------- |
| 400         | `VALIDATION_ERROR`       | Ungültige Eingabedaten           |
| 404         | `SUBSCRIPTION_NOT_FOUND` | Abonnement nicht gefunden        |
| 422         | `SUBSCRIPTION_CANCELLED` | Abonnement ist bereits gekündigt |
| 422         | `CURRENCY_MISMATCH`      | Unterschiedliche Währungen       |
| 422         | `PRICE_PLAN_ARCHIVED`    | Preisplan ist archiviert         |

***

## Verwandte Dokumentation

* [Abonnement-Übergänge (Guide)](/guide/subscriptions/transitions) - Konzepte und Anwendungsfälle