> For the complete documentation index, see [llms.txt](https://developers.share.inc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.share.inc/guides/handle-a-plan-change.md).

# Handle a plan change

> **Placeholder page.** Full content tracked under the docs content effort.

Upgrades and downgrades are modeled as a `PATCH /v1/subscriptions/{id}` with the new `planId`. The change takes effect at the next cycle boundary unless `effectiveAt: "immediate"` is set, in which case the current cycle is pro-rated.

## Splynx-initiated plan changes

If your billing runs on Splynx, you change a customer's plan from Splynx — not the Share API. Edit the customer's internet service and set the **Migrate to Share Plan** additional field to the target Share plan (the dropdown lists your Share plans). Share reads that `service.edit` and decides what to do from two fields, on the customer's **single** Share subscription:

| You set                                                    | What Share does                                                                                                                             |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Free Immediate Upgrade = on** (any plan)                 | **Free, immediate.** The plan switches now at no charge; the customer's regular renewal billing resumes on the new plan next cycle.         |
| Free Immediate Upgrade = off, target is **more expensive** | **Pay to upgrade.** The customer keeps their current plan and gets an SMS + email to pay for the upgrade. The switch happens once they pay. |
| Free Immediate Upgrade = off, target is **same / cheaper** | **Scheduled.** The switch is queued and applied at the end of the current plan; the customer keeps today's plan until then.                 |

For the scheduled and pay-to-upgrade cases, Share applies the change at the end of the customer's current billing cycle — you don't set an effective date.

### The pay-to-upgrade journey (customer's view)

When you queue a more-expensive upgrade (Free Immediate Upgrade = off), the customer stays on their current plan and the upgrade waits for payment:

1. **Prompt.** The customer gets an SMS + email asking them to pay for the upgrade. Their current plan keeps running in the meantime — nothing on their connection changes yet.
2. **They pay.** The customer pays the usual way (SasaPay). Share waits until the payment covers the new plan's price — a partial payment does **not** trigger the switch; it's held until enough arrives.
3. **The upgrade applies.** Once payment is confirmed, Share switches the customer to the new plan: their speed changes to the new tariff and they get a confirmation SMS + email. The login/password stay the same throughout.
   * If the customer's current billing cycle ends in the future, Share holds the paid upgrade and applies it **at the end of that cycle** instead of immediately.
   * With the cycle already ended (or none in effect), the switch happens as soon as the payment is confirmed.

No connection change or speed change happens before the payment is confirmed.

> Share does **not** use Splynx's *Change tariff* action, and it ignores Splynx *planned* edits (`edit_planned`). Always drive the change through the **Migrate to Share Plan** field so Share's billing and the customer's RADIUS session stay in sync — the customer keeps the same login/password throughout.