ArcalotlArcalotl
Subscriptions

Switch 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.

Serverhttps://api.arcalotl.com
POST
/v1/subscriptions/{id}/switch

Authorization

apiKey
AuthorizationBearer <token>

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

id*string

Header Parameters

Idempotency-Key?string

Opaque client-generated key (1-255 chars) that makes a write safe to retry for 24h. A replay of the same key and body returns the original response with Idempotent-Replayed: true. Reusing the key with a different body returns 422 idempotency_key_reuse; an in-flight duplicate returns 409 request_in_flight.

Length1 <= length <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

plan_id*string

A plan_id from the subscription's switch options.

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X POST "https://example.com/v1/subscriptions/string/switch" \  -H "Idempotency-Key: 6f8a2c1e-4b3d-4e9a-9c21-2f0a1b7d5e44" \  -H "Content-Type: application/json" \  -d '{    "plan_id": "plan_01JMZX3B2K"  }'
{
  "id": "sub_01JMZX47H8Q2C9R4T1",
  "status": "active",
  "plan_id": "plan_01JMZX3B2K",
  "plan_name": "Monthly",
  "tier_id": "tier_01JMZX2A9F",
  "tier_name": "VIP",
  "member_id": "mem_01JMZX1Z7D",
  "amount_cents": 1500,
  "currency": "usd",
  "interval": "month",
  "current_period_end": "2026-08-01T00:00:00Z",
  "cancel_at": "2026-08-01T00:00:00Z",
  "paused_until": "2019-08-24T14:15:22Z",
  "scheduled_plan_id": "plan_01JMZX3B2K",
  "scheduled_at": "2026-08-01T00:00:00Z",
  "created_at": "2026-05-01T12:00:00Z",
  "updated_at": "2026-07-01T12:00:00Z"
}
{
  "type": "https://docs.arcalotl.com/api/errors#invalid_request",
  "title": "Bad Request",
  "status": 400,
  "detail": "The 'cursor' parameter is not a valid cursor from a previous response.",
  "code": "invalid_request"
}
{
  "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#not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "The requested resource was not found.",
  "code": "not_found"
}
{
  "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#rate_limited",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded. Retry after the interval in the Retry-After header.",
  "code": "rate_limited"
}

GETList 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`.

POSTDrop a scheduled plan change

Cancels a pending period-end plan change so the subscription keeps its current plan. Answers `409 conflict` when nothing is scheduled. Supply an `Idempotency-Key` header to make retries safe.