# Switch a subscription to another plan

`POST https://rcur.app/api/v2/subscriptions/{subscriptionId}/plan`

Switching right away prorates what is left of the running period, starts a new period today and charges the difference through the mandate. Switching at the next payment keeps the current plan until then. A switch planned earlier is replaced.

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `subscriptionId` | string | yes |  |

## Request body

The plan to switch to and when. Check the amount first with GET on the same path.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `plan` | string | no | Id of the template to switch to, from the options |
| `timing` | string | no | immediate prorates the running period and charges the difference now; next_payment keeps the current plan until the next payment One of: `immediate`, `next_payment`. |
| `settlement` | number | no | Optional. The amount you expect to be charged for a switch right away; the switch is refused when it is different now |

## Example request

```bash
curl -X POST https://rcur.app/api/v2/subscriptions/YJRQAMRQ6y/plan \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "plan": "aB3dE5fG7h",
  "timing": "next_payment",
  "settlement": 13.33
}'
```

## Responses

### 201 The subscription is switched, or the switch is planned

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | yes | One of: `scheduled`, `applied`, `cancelled`. |
| `timing` | string | yes | One of: `immediate`, `next_payment`. |
| `direction` | string | yes | One of: `upgrade`, `downgrade`, `interval`. |
| `from` | string | yes |  |
| `to` | string | yes |  |
| `effective_on` | string | yes | Today for a switch right away, otherwise the date of the next payment |
| `currency` | string | no |  |
| `old_amount` | string | no |  |
| `new_amount` | string | no |  |
| `credit` | string | no | Credit for the unused part of the running period (switch right away) |
| `settlement` | string | no | Amount charged for the switch (switch right away) |
| `credit_left` | string | no | Credit that stays on the subscription for the next payments |

```json
{
    "status": "applied",
    "timing": "immediate",
    "direction": "upgrade",
    "from": "Klein",
    "to": "Groot",
    "effective_on": "2026-11-20",
    "currency": "EUR",
    "old_amount": "10.00",
    "new_amount": "20.00",
    "credit": "6.67",
    "settlement": "13.33",
    "credit_left": "0.00"
}
```

### 404 Resource not found

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | integer | yes |  |
| `error` | string | yes |  |

```json
{
    "status": 404,
    "error": "Resource not found"
}
```

### 422 Validation error

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | integer | yes |  |
| `error` | string | yes |  |
| `fields` | object | no |  |

```json
{
    "status": 422,
    "error": "Could not process request. Some fields contain invalid data",
    "fields": {
        "email": [
            "The email field is required."
        ]
    }
}
```