Skip to main content
CreateSubscription is the single action responsible for provisioning a new billing relationship between a billable and a plan. When you call it — whether through the facade or directly — it contacts the configured gateway to create the subscription record there, then persists a Subscription model in your database. The package fires a SubscriptionCreated event after both operations complete successfully.

​
Calling styles

The fluent facade is the recommended approach for most application code. Subscribd::for($billable) returns a BillableContext, and subscribe() delegates to CreateSubscription internally.
use Pixelworxio\Subscribd\Facades\Subscribd;

// Minimal — creates a subscription named 'default'
Subscribd::for($user)->subscribe('starter');

// With options
Subscribd::for($user)->subscribe('starter', ['name' => 'default']);
Subscribd::for($user)->subscribe('extra-storage', ['name' => 'storage']);

// Per-seat with an explicit quantity
Subscribd::for($user)->subscribe('plan-key', ['name' => 'addons', 'quantity' => 3]);

​
Parameters

ParameterTypeRequiredDescription
$billableBillableYesThe model being subscribed (e.g., User, Team)
$planPlanYesThe resolved Plan model to subscribe to
$optionsarrayNoAdditional options (see below)

​
Options array

KeyTypeDefaultDescription
namestring'default'Subscription slot name — allows a billable to hold multiple subscriptions
quantityint1Number of seats or units (used for per_unit plans)

​
Return value

CreateSubscription::execute() returns the newly created Subscription model, already persisted and loaded with its plan relationship. 
$subscription = app(CreateSubscription::class)->execute($user, $plan);

$subscription->status;   // SubscriptionStatus::active (or SubscriptionStatus::trialing if the plan has trial_days)
$subscription->name;     // 'default'
$subscription->gateway;  // 'stripe' (or whichever gateway is configured)

​
Multiple named subscriptions

A single billable can hold multiple independent subscriptions by using different name values. This is the recommended pattern when you sell add-on plans separately from a base plan. 
// Subscribe to the base plan
Subscribd::for($user)->subscribe('starter', ['name' => 'default']);

// Subscribe to a storage add-on as a separate slot
Subscribd::for($user)->subscribe('extra-storage', ['name' => 'storage']);
Each subscription is tracked independently — canceling or swapping one does not affect the others.
The subscription name is how Subscribd identifies which slot you are operating on in subsequent calls like swap(), cancel(), and resume().

​
Events fired

SubscriptionCreated is dispatched after the subscription is persisted. Listen to it in EventServiceProvider to trigger onboarding workflows, send welcome emails, or provision resources. 
use Pixelworxio\Subscribd\Events\SubscriptionCreated;

Event::listen(SubscriptionCreated::class, function (SubscriptionCreated $event) {
    // $event->subscription — the newly created Subscription model
    $event->subscription->billable->notify(new WelcomeNotification());
});

​
Gateway override

To create the subscription on a specific gateway instead of the configured default, chain ->on() before subscribe() when using the facade. 
Subscribd::for($user)->on('paypal')->subscribe('starter');
When using the direct action, set the gateway in config or pass a context-aware billable.