SwapPlan is the action that handles plan changes for an existing subscription. When you upgrade or downgrade, it updates the subscription on the gateway, applies the proration strategy you have configured (or specified per-call), and updates the Subscription model in your database. The package fires SubscriptionUpdated after both operations complete.
Calling styles
Use swap() or swapTo() on a BillableContext. Both methods delegate to SwapPlan internally.use Pixelworxio\Subscribd\Facades\Subscribd;
// Upgrade the 'default' subscription to 'pro'
Subscribd::for($user)->swap('default', 'pro');
// Defer the price change to the next renewal (no immediate charge)
Subscribd::for($user)->swap('default', 'pro', ['prorate' => 'renewal']);
// Swap a named subscription other than 'default'
Subscribd::for($user)->swapTo('new-plan-key', 'addons', ['prorate' => 'renewal']);
Resolve SwapPlan from the container when you need to call it from a job, command, or test.use Pixelworxio\Subscribd\Actions\SwapPlan;
use Pixelworxio\Subscribd\Models\Plan;
$subscription = $user->subscription('default');
$newPlan = Plan::query()->where('key', 'pro')->firstOrFail();
app(SwapPlan::class)->execute($subscription, $newPlan, ['prorate' => 'now']);
Parameters
| Parameter | Type | Required | Description |
|---|
$subscription | Subscription | Yes | The existing subscription to change |
$newPlan | Plan | Yes | The plan to switch to |
$options | array | No | Per-call options (see below) |
Options array
| Key | Type | Default | Description |
|---|
prorate | string | From config | Proration strategy: 'now', 'renewal', or 'none' |
Proration strategies
The global default is set in config/subscribd.php under proration_strategy. You can override it per call using the prorate option.
| Strategy | Behavior |
|---|
now | Credit or charge the prorated difference immediately at the time of the swap |
renewal | Switch to the new plan price at the next renewal; no immediate charge |
none | No proration; the new price takes effect at the next cycle with no credit |
// Global default in config/subscribd.php
'proration_strategy' => 'now', // 'now' | 'renewal' | 'none'
// Per-call override
Subscribd::for($user)->swap('default', 'pro', ['prorate' => 'renewal']);
Use 'renewal' for downgrades when you want to avoid issuing immediate credits, and 'now' for upgrades when you want to collect the difference immediately.
What happens to the current period
now: The gateway computes a credit for unused time on the old plan and an immediate charge for the new plan. The subscription switches plans as of today.renewal: The subscription continues on the old plan until the current period ends, then switches automatically. No mid-cycle charge or credit is issued.none: Similar to renewal but without any credit. The subscriber is not compensated for unused time on the old plan.
Events fired
SubscriptionUpdated is dispatched after the plan change is saved. Use it to update entitlement caches, sync external systems, or notify the subscriber.
use Pixelworxio\Subscribd\Events\SubscriptionUpdated;
Event::listen(SubscriptionUpdated::class, function (SubscriptionUpdated $event) {
// $event->subscription — the updated Subscription model with the new plan_id
Cache::forget("entitlements.{$event->subscription->billable_id}");
});
Subscription name
When using the facade’s swap() method, the first argument is the subscription slot name ('default' if you have only one subscription). When using swapTo(), the slot name is the second argument and defaults to 'default'.
// swap(name, newPlanKey, options)
Subscribd::for($user)->swap('default', 'pro');
// swapTo(newPlanKey, name, options)
Subscribd::for($user)->swapTo('pro', 'default');
