> 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/splynx/migrate-a-subscriber.md).

# Migrate a subscriber to a Share plan

This page is for the case where a subscriber **already exists on your Splynx tenant** — typically on one of your own legacy tariffs — and you want to move them onto a Share-managed plan so that billing, provisioning, and revenue split flow through the Share platform.

If the subscriber does not yet exist anywhere, see [Onboard a subscriber](/guides/onboard-a-subscriber.md) instead.

## In three steps

1. **Pick the Share plan** the customer should end up on. If it doesn't exist yet, follow [Create a plan](/splynx/create-a-plan.md) first.
2. **Trigger the migration** — either through the Share API (update the customer's subscription with the new `planId`), through the Share admin platform, or by having your CSR change the Splynx internet-service tariff to the Share-managed one.
3. **Wait for the renewal boundary.** The change is queued, not immediate. At the end of the current billing cycle the customer is moved to the new plan, the Splynx tariff updates, and RADIUS is re-provisioned to the new speed profile.

That's the whole flow. The rest of this page explains what happens under the hood, what the customer and your CSR see, and how to roll back.

## What "migrating" actually changes

Only the billing and provisioning surface moves. The Splynx customer record stays where it was — same `customer_id`, same name, address, notes — and your CSR's history on that customer is preserved.

After migration:

* The customer is billed at the **Share plan price**, on the **Share cycle**, by the **Share platform**.
* Their **RADIUS speed profile** is the Share plan's profile, pushed to FreeRADIUS by Share.
* Each completed payment appears as a `Payment` entry on the customer's Splynx ledger — same as for any other Share subscriber.
* Their Splynx internet-service is reassigned to the Share-managed tariff that mirrors the plan.

## Three ways to trigger a migration

You can start the migration from any of three places. The end state is identical — pick whichever fits your workflow.

### 1. From your CSR's Splynx UI

Your CSR opens the customer in Splynx, edits the internet-service, and picks one of the Share-managed tariffs (see [Create a plan](/splynx/create-a-plan.md)). Save.

Splynx sends Share a `service.update` webhook. Share recognises the tariff as one of its plans and queues the change to the end of the current cycle.

### 2. From the Share admin platform

Open the subscriber on the Share platform, change the plan on the subscription, save. Same outcome as the CSR path.

### 3. From the partner API

Call the subscription update endpoint with the new `planId`. The exact request shape lives in the [API Reference](/api-reference/api-reference.md) under **Subscriptions → Update subscription**.

In short, you `PATCH` the subscription identified by `sbn_…` and pass `{ "planId": "pln_…" }`. The response confirms whether the change applied immediately or was queued (see below).

## Immediate vs queued — what determines the timing

The Share platform decides automatically based on cycle state:

* **Queued to next cycle** — if the subscriber currently has an active paid billing cycle. The customer keeps the old plan until cycle expiry; the swap lands on the renewal date.
* **Applied immediately** — if there is no active cycle (e.g. a brand-new subscriber whose first cycle has not started yet, or one whose cycle has already been refunded).

Queuing is the common case for established subscribers. The platform will never interrupt a paid cycle to change the plan mid-month.

## What the customer experiences

* **Before the renewal:** no change. Same speed, same price, same service. The platform sends a notification ("your plan changes on *date*") so the customer is not surprised when the new price hits.
* **At the renewal:** the new plan takes effect. If the new speed differs from the old one, the RADIUS profile updates within seconds of the cycle starting.
* **First payment under the new plan:** comes through the normal Share collection (STK push or paybill) at the new price.

## What your CSR sees in Splynx

* **Before the renewal:** the internet-service still shows the previous tariff. The Splynx audit log shows that Share received the change request, but no tariff change has been pushed yet.
* **At the renewal:** Share updates the internet-service to the new tariff. Status (`active` / `blocked` / `disabled`) is **not** touched — a previously blocked service stays blocked.
* **In the payment ledger:** the first payment at the new price appears as a `Payment` row, with the same partner attribution as before.

## Rolling back

* **Before the renewal lands** — cancel the queued change. The subscription update endpoint accepts a `cancelQueuedSwap: true` flag that clears the queue without changing the active plan. The subscriber stays on their original plan and no notification is sent.
* **After the renewal has landed** — issue another migration in the opposite direction. There is no rollback shortcut; it is just another plan change.

## Migrating many subscribers at once

There is **no bulk-migration endpoint** in the public API and no "migrate a whole legacy plan" admin action either. If you need to move a batch of subscribers (e.g. retiring an old tariff), talk to your account manager. Bulk migrations are sequenced on the Share side by ops so renewal cut-overs don't flood the payment rail or RADIUS provisioning queue all at once.

If any subscriber in the batch is on a **static IP**, the migration also needs one extra grant on your API key — **write** access to `Networking → IPv4 networks` — so Share can create the networks that back those addresses. It's the only permission a bulk migration needs beyond normal operation, and it's reversible once the migration is done; see [Additional permission for bulk migration](/splynx/connect-your-splynx.md#additional-permission-for-bulk-migration).

## Common gotchas

* **The tariff is not in your CSR's picker.** The plan sync to your instance hasn't completed or failed — check the plan exists on the Share side and see [Create a plan](/splynx/create-a-plan.md); the integration page in the Share portal shows whether outbound sync is healthy.
* **The service is `blocked` or `disabled` in Splynx.** The migration still queues normally. Status is not changed; when the service is next unblocked it resumes on the new plan if the renewal date has already passed.
* **You expected the change to apply *****now*****.** It doesn't, unless there's no active cycle. Mid-cycle plan changes are intentionally not exposed — they break the revenue-split accounting model.
* **You wanted to migrate by editing the Splynx tariff directly.** Don't — the Splynx tariff is a mirror of the Share plan. Edits made in Splynx will get overwritten by the next Share-side update.