Self-serve plan changes

How a customer changes what they are subscribed to from the customer portal, and what your platform has to have in place for that change to be allowed.

Why this matters

A plan change is the one billing action customers want to take themselves and the one that most often lands in your support queue. The customer portal lets a customer switch the pricings on their own subscription and pay for the difference in the same visit, without an agent touching the subscription.

The endpoints below sit under /v1/portal/ and are scoped to a single customer by the portal session, so a customer can only ever change their own subscription. They are what the hosted portal and the SDK call on the customer’s behalf; you use them directly when you build your own upgrade screen.

How it works

A plan change is not an edit of the running schedule. It is a new schedule on the same subscription, using the same pricing plan version, with a different set of enabled pricings. The previous schedule is closed at the moment the new one starts, so the subscription always has exactly one schedule in effect.

The change can land at one of two moments, and which one you get depends on the subscription’s billing time as much as on the request.

The only value start_at accepts is the current time: it is validated against the clock with a five-minute tolerance either way, so an arbitrary future date is rejected. A change scheduled for next month is a platform-side operation, not something a customer sets from the portal.

Change at the next billing period

On a CALENDAR subscription, leave start_at out. The new schedule starts on the subscription’s next invoice date, so the customer finishes the period they already paid for on the pricings they had.

$
curl -X POST https://test.api.solvimon.com/v1/portal/pricing-plan-schedules \
>
  -H "Authorization: Bearer <portalAccessToken>" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "pricing_plan_subscription_id": "ppsu_example",
>
    "enabled_pricings": [
>
      { "pricing_id": "pric_premium_seat" },
>
      { "pricing_id": "pric_priority_support" }
>
    ]
>
  }'

1
{
2
  "object_type": "PRICING_PLAN_SCHEDULE",
3
  "id": "ppsc_example",
4
  "pricing_plan_subscription_id": "ppsu_example",
5
  "pricing_plan_version_id": "ppve_example",
6
  "status": "ACTIVE",
7
  "start_at": "2026-09-01T00:00:00Z",
8
  "enabled_pricings": [
9
    { "pricing_id": "pric_premium_seat" },
10
    { "pricing_id": "pric_priority_support" }
11
  ]
12
}

enabled_pricings is the complete set for the new schedule, not a delta. A pricing the customer keeps has to be listed again; anything left out is dropped from the subscription at the new start.

You do not send pricing_plan_version_id or start_at. Solvimon takes the version from the subscription’s current schedule and the start from its next invoice date. A subscription with no next invoice (because it has ended, for example) is rejected: there is no date to attach the change to.

Change immediately

On an EXACT subscription the change is always applied immediately, whether or not you send start_at. The new schedule opens straight away and the billing period realigns to that moment, so the customer is billed for the new pricings from now rather than from the old period boundary. Sending start_at makes that explicit.

$
curl -X POST https://test.api.solvimon.com/v1/portal/pricing-plan-schedules \
>
  -H "Authorization: Bearer <portalAccessToken>" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "pricing_plan_subscription_id": "ppsu_example",
>
    "start_at": "2026-08-19T14:32:00Z",
>
    "enabled_pricings": [
>
      { "pricing_id": "pric_premium_seat" }
>
    ]
>
  }'

Pay for the upgrade in the same step

The call above changes the subscription and leaves the money to the normal invoicing cycle. When the upgrade has to be paid before it applies, drive it from the payment instead: authorize the payment with a CREATE_PRICING_PLAN_SCHEDULE context and Solvimon creates the schedule once the payment is authorized.

$
curl -X POST https://test.api.solvimon.com/v1/portal/payments/authorize \
>
  -H "Authorization: Bearer <portalAccessToken>" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "payment_acceptor_id": "paya_example",
>
    "payment_gateway_variant": "ADYEN",
>
    "customer_id": "cust_example",
>
    "payment_method_id": "pmet_example",
>
    "amount": { "quantity": "49.00", "currency": "EUR" },
>
    "context": {
>
      "type": "CREATE_PRICING_PLAN_SCHEDULE",
>
      "create_pricing_plan_schedule": {
>
        "pricing_plan_subscription_id": "ppsu_example",
>
        "pricing_plan_version_id": "ppve_example",
>
        "pricing_id": "pric_premium_seat"
>
      }
>
    }
>
  }'

The schedule is only created when the payment comes back AUTHORIZED; a declined payment leaves the subscription untouched. The step is idempotent on the start date: if a schedule for that subscription and start already exists, because a retried payment ran the action twice, it is linked to the payment rather than duplicated.

Note the difference in shape from POST /v1/portal/pricing-plan-schedules: the payment context enables exactly one pricing_id, so it fits a single-product upgrade. Use the schedule endpoint when the customer picks a combination.

What must be true

Both routes validate the same preconditions before anything changes, because a self-serve change is only safe when Solvimon can bill for it without you intervening.

PREPAID and unrecognized payment method types are rejected. Each failure returns a validation error naming the field that blocked it, so your upgrade screen can tell the customer to add a payment method rather than failing silently.

Via Desk and the hosted portal

In the hosted portal the customer reaches this from My subscription through Upgrade subscription, which prices the change with the correct tax and shows what is due today before they confirm. That flow is described on the customer portal page.

An agent making the same change in Desk edits the subscription’s schedules directly and is not bound by the constraints above; the payment method and billing time rules exist to make the change safe when nobody is supervising it.

Edge cases

• The next invoice is refreshed, not reissued. After the schedule is created, Solvimon runs a full refresh of the subscription’s next invoice so the change is reflected immediately. If the refresh fails the schedule change still stands; the invoice picks the change up on its next regular refresh.
• The pricing plan version is fixed. A portal change swaps pricings within the version the customer is already on. Moving them to a different version, or a different plan, is a platform-side operation.
• enabled_pricings replaces the set. Sending only the new pricing removes everything the customer had before. Read the current schedule first and send the full intended set.
• One schedule per start moment. Creating a second schedule with the same start closes the first one at that same instant, which leaves a zero-length schedule. Check for an existing pending change before creating one.