List the plans a subscription can switch to
Returns the plans this subscription may move to, grouped as `same_tier` (another billing option of the same tier), `upgrades`, and `downgrades`. Only active or trialing subscriptions have options; a cancelling or paused subscription answers `409 conflict`.
Authorization
apiKey Community-scoped API key. Send it as Authorization: Bearer arclt_live_.... Keys carry scopes; endpoints that need a specific scope answer 403 missing_scope when the key lacks it.
In: header
Path Parameters
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
curl -X GET "https://example.com/v1/subscriptions/string/switch-options"{
"same_tier": [
{
"plan_id": "plan_01JMZX3B2K",
"plan_name": "Collective monthly",
"tier_id": "tier_01JMZX2A9F",
"amount_cents": 19900,
"currency": "usd",
"interval": "month",
"trial_days": 0
}
],
"upgrades": [
{
"plan_id": "plan_01JMZX3B2K",
"plan_name": "Collective monthly",
"tier_id": "tier_01JMZX2A9F",
"amount_cents": 19900,
"currency": "usd",
"interval": "month",
"trial_days": 0
}
],
"downgrades": [
{
"plan_id": "plan_01JMZX3B2K",
"plan_name": "Collective monthly",
"tier_id": "tier_01JMZX2A9F",
"amount_cents": 19900,
"currency": "usd",
"interval": "month",
"trial_days": 0
}
]
}{
"type": "https://docs.arcalotl.com/api/errors#unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "A valid API key is required. Provide it as 'Authorization: Bearer arclt_live_...'.",
"code": "unauthorized"
}{
"type": "https://docs.arcalotl.com/api/errors#missing_scope",
"title": "Forbidden",
"status": 403,
"detail": "This API key is missing the required scope: subscriptions:read.",
"code": "missing_scope"
}{
"type": "https://docs.arcalotl.com/api/errors#not_found",
"title": "Not Found",
"status": 404,
"detail": "The requested resource was not found.",
"code": "not_found"
}{
"type": "https://docs.arcalotl.com/api/errors#request_in_flight",
"title": "Conflict",
"status": 409,
"detail": "Another request with this Idempotency-Key is still in flight.",
"code": "request_in_flight"
}{
"type": "https://docs.arcalotl.com/api/errors#rate_limited",
"title": "Too Many Requests",
"status": 429,
"detail": "Rate limit exceeded. Retry after the interval in the Retry-After header.",
"code": "rate_limited"
}POSTCancel a subscription at period end
Schedules a period-end cancellation. The member keeps access until the current period ends, then the subscription transitions to cancelled. Idempotent: a subscription already cancelling returns 202 without another provider call. Supply an `Idempotency-Key` header to make retries safe.
POSTSwitch a subscription to another plan
Moves the subscription to a plan from its switch options. A same-tier change or an upgrade applies immediately with proration and the response shows the new `plan_id`. A downgrade is scheduled for the end of the current period and the response shows it as `scheduled_plan_id` and `scheduled_at`. Entitlement webhooks follow as usual. Supply an `Idempotency-Key` header to make retries safe.