Zum Hauptinhalt springen
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.
​
proration
string
Standard:"none"
Wie sollen Gutschriften für nicht genutzte Zeit berechnet werden?
WertBeschreibung
creditProratedAnteilige Gutschrift basierend auf verbleibenden Tagen
noneKeine 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?
WertBeschreibung
phaseStartRechnung wird zum Übergangszeitpunkt (effectiveAt) erstellt. Teilperioden von nutzungsbasierten Items werden ebenfalls zu diesem Zeitpunkt abgerechnet.
immediatelyRechnung 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 StatusCodeBeschreibung
400VALIDATION_ERRORUngültige Eingabedaten
404SUBSCRIPTION_NOT_FOUNDAbonnement nicht gefunden
422SUBSCRIPTION_CANCELLEDAbonnement ist bereits gekündigt
422CURRENCY_MISMATCHUnterschiedliche Währungen
422PRICE_PLAN_ARCHIVEDPreisplan ist archiviert

​
Verwandte Dokumentation