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.

Gekündigte Abonnements können nicht mehr transitioniert werden.

​

POST /api/subscriptions/[subscriptionId]/transition

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

​

Request

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

effectiveAt · string · erforderlich

Zeitpunkt des Übergangs im ISO 8601 Format. Muss in der Zukunft oder jetzt sein. Ab diesem Zeitpunkt gelten die neuen Items.

desiredItems · array · erforderlich

Liste der gewünschten Items nach dem Übergang. Mindestens 1 Item erforderlich.

Anzeigen Item-Objekt

productId · string · erforderlich

UUID des Produkts

pricePlanId · string · erforderlich

UUID des Preisplans

quantity · number · erforderlich

Menge (muss positiv sein). Für nutzungsbasierte Produkte ist dieser Wert immer 1 - die tatsächliche Menge wird durch Nutzungsereignisse bestimmt.

proration · string · Standard: "none"

Wie sollen Gutschriften für nicht genutzte Zeit berechnet werden?

Wert	Beschreibung
creditProrated	Anteilige Gutschrift basierend auf verbleibenden Tagen
none	Keine Gutschrift

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

invoiceTiming · string · Standard: "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.

cancelReason · string

Optionaler Grund für die Beendigung der alten Items (max. 255 Zeichen)

dryRun · boolean · Standard: "false"

Wenn true, wird eine Vorschau der Änderungen zurückgegeben ohne sie zu speichern

​

Response (200 OK)

{
  "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"
}

previousPhase · object

Die abgeschlossene Phase mit den alten Items

newPhase · object

Die neue aktive Phase mit den neuen Items

changes · object

Übersicht der entfernten und hinzugefügten Items

creditNoteId · string

ID der erstellten Gutschrift (falls vorhanden, nur bei Festpreis-Produkten)

---

​

Beispiele

​

Upgrade mit anteiliger Gutschrift

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

​

Sofortige Abrechnung

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

​

Vorschau (Dry-Run)

{
  "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) - Konzepte und Anwendungsfälle