Preview a plan change

Show what POST /v2/subscriptions/{id}/change-plan would do with the same body: the new renewal amount, this change's proration and what the next renewal invoice would add or credit. Nothing is changed and nothing is recorded.

It uses the same calculation and the same checks as the change, so it is refused for the same reasons (400, and 409 for a Direct Debit subscription). The figures are as of the request: a change made later prorates over fewer remaining days.

Requires the subscriptions:read scope and the subscription:read permission.

---

Related endpoints

• POST /subscriptions — Create a new subscription
• GET /subscriptions — List subscriptions
• GET /subscriptions/{id} — Get subscription by ID
• PATCH /subscriptions/{id} — Update subscription details
• DELETE /subscriptions/{id} — Delete subscription
• POST /subscriptions/{id}/change-plan — Change subscription plan
• POST /subscriptions/{id}/change-quantity — Change subscription quantity
• POST /subscriptions/{id}/preview-renewal — Preview subscription renewal

Common errors

• 400 invalid_request — malformed payload or failed validation.
• 401 authentication_error — missing, invalid, expired, or revoked credential. Codes: authentication_failed, invalid_api_key, expired_api_key, api_key_revoked, session_invalid, merchant_required. Carries a WWW-Authenticate: Bearer challenge.
• 403 authorization_error — the caller is identified but the action is denied. Codes include insufficient_permissions, ip_not_allowed, merchant_mismatch, and origin_not_allowed.
• 404 resource_missing — the referenced resource does not exist or is not visible to your key.
• 409 conflict — Idempotency-Key collision with a different body, or a concurrent state-transition conflict.
• 429 rate_limit_error — code rate_limit_exceeded. Back off using the Retry-After header (whole seconds); X-RateLimit-Reset is a UNIX timestamp in seconds.

Idempotency

Pass an Idempotency-Key header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see the idempotency guide.

Path Parameters

Response Body

curl -X POST "https://api.revkeen.com/v2/subscriptions/11111111-1111-4111-8111-111111111111/preview-change-plan" \
  -H "x-api-key: $REVKEEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "newPlanId": "11111111-1111-4111-8111-111111111111"
  }'

{  "data": {    "subscription_id": "d4e6f8a1-2b3c-4d5e-9f60-7a8b9c0d1e24",    "current_price_id": "00000000-0000-4000-8000-000000000001",    "current_plan_name": "string",    "new_price_id": "b5d8e2f1-3a6c-4d9b-8e7f-1c4a2b5d6e73",    "new_plan_name": "string",    "new_product_id": "string",    "billing_interval": "string",    "billing_interval_count": 0,    "quantity": 0,    "current_amount_minor": 1000,    "new_amount_minor": 3000,    "proration_behavior": "next_invoice",    "effective_date": "2026-09-01T12:00:00Z",    "proration": {      "credit_amount_minor": 1000,      "charge_amount_minor": 3000,      "net_amount_minor": 2000,      "is_upgrade": true,      "days_remaining": 0,      "days_in_period": 0,      "currency": "GBP"    },    "pending_proration_net_amount_minor": 2000  }}