Subscription Transition

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

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

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

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

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