Change Subscription Plan

Switch a subscription to a different variant of the same product.

The change is transactional and prorated. The proration is invoiced immediately, and the new plan takes effect as soon as it is paid. If the proration payment is declined, the plan change does not take effect and the call returns 422 with the decline reason.

For a subscription paid with BLIK, the bank confirms the proration payment asynchronously, usually within a minute. Until it does, the call returns 202 and the subscription stays on its current variant — see Pending Response (202).

Validation rules

The endpoint rejects the request with 422 when the target variant fails any of these checks:

Reason	Error message
Target variant does not exist or does not belong to your store	Target variant not found.
Target variant is attached to a different product	Target variant does not belong to the subscription's product.
Target variant is one-time (not recurring)	Target variant must be recurring.
Target variant is the variant the subscription is already on	Subscription is already on the requested variant.

Request

POST /subscriptions/{id}/change-plan

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Subscription UUID

Request Body

Parameter	Type	Required	Description
variant_id	string	Yes	Target variant (price) UUID

Example Request

curl -X POST "https://cart.easy.tools/api/v1/subscriptions/2945128f-5490-4ded-80fe-9c6519b00eec/change-plan" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "variant_id": "d91c65aa-b221-4aa4-b626-cf0d8a198749"
  }'

Response

Success Response (200)

Returns the updated subscription (base fields only; no include sections) — the variant_name, recurring_amount, interval, etc. reflect the new plan.

{
  "id": "2945128f-5490-4ded-80fe-9c6519b00eec",
  "remote_id": "sub_1QabcDEFghiJKLmn",
  "provider": "stripe",
  "status": "active",
  "variant_name": "Annual Plan",
  "product_name": "Premium Course",
  "recurring_amount": 49000,
  "currency": "usd",
  "interval": "year",
  "interval_count": 1,
  "quantity": 1,
  "customer_email": "buyer@example.com",
  "current_period_start": "2026-05-28T12:00:00+00:00",
  "current_period_end": "2027-05-28T12:00:00+00:00",
  "trial_end": null,
  "cancel_at": null,
  "canceled_at": null,
  "active_until": null,
  "active_cycles": null,
  "cancel_early": false,
  "keep_access_after_expiring": false,
  "is_delegated": false,
  "is_cancelable": true,
  "created_at": "2026-01-15T10:00:00+00:00",
  "customer": null,
  "variant": null,
  "product": null,
  "order": null,
  "renewals": null,
  "upcoming_invoice": null
}

See the Get Subscription reference for a full description of each base field.

Pending Response (202)

Returned for a subscription paid with BLIK while the bank is still confirming the proration payment. The body has the same shape as the 200 response, but the subscription is still on its previous variant — variant_name, recurring_amount, interval, etc. show the plan it had before the call.

The new variant applies once the bank confirms the payment. If the bank declines it, the subscription stays on the previous variant. To see the outcome, read the subscription again with Get Subscription after a short wait.

Don't retry a pending change

Don't repeat the change-plan call while the change is pending — a repeated call can charge the customer a second time.

Error Responses

Bad Request (400)

Returned when the path parameter or variant_id is not a valid UUID.

{
  "message": "Invalid subscription ID"
}

{
  "message": "Invalid variant ID"
}

Not Found Error (404)

{
  "message": "Subscription with ID 2945128f-5490-4ded-80fe-9c6519b00eec not found"
}

Validation Error (422 — request body)

Returned when variant_id is missing or malformed.

{
  "message": "The given data was invalid.",
  "errors": {
    "variant_id": [
      "This field is required."
    ]
  }
}

Variant Rejected (422)

Returned when the target variant fails one of the validation rules.

{
  "message": "Target variant does not belong to the subscription's product."
}

{
  "message": "Target variant must be recurring."
}

{
  "message": "Subscription is already on the requested variant."
}

Provider Error (422)

Returned when the payment provider rejects the plan change.

{
  "message": "Payment provider rejected the plan change: the customer has no valid payment method on file"
}

Payment Failed (422)

Returned when the proration payment is declined. The plan change has not taken effect. The message carries the decline reason; when the provider gives no specific reason, it reads The proration payment could not be completed.

{
  "message": "Your card was declined."
}

Unauthorized Error (401)

{
  "message": "Unauthenticated."
}