Skip to main content
The Subscribd facade is your primary entry point for all billing operations. Calling Subscribd::for($billable) returns a BillableContext instance scoped to that billable model. Every method on BillableContext — subscribe, swap, cancel, resume, charge — delegates to the corresponding action class, so you get consistent event firing, gateway abstraction, and error handling without wiring anything manually.

​
BillableContext methods

​
subscribe()

Creates a new subscription for the billable on the configured gateway. 
use Pixelworxio\Subscribd\Facades\Subscribd;

// Basic subscription on the default gateway
Subscribd::for($user)->subscribe('starter');

// Named subscription slot with a quantity override
Subscribd::for($user)->subscribe('starter', ['name' => 'default']);
Subscribd::for($user)->subscribe('extra-storage', ['name' => 'storage']);

// Per-seat subscription with an explicit quantity
Subscribd::for($user)->subscribe('plan-key', ['name' => 'addons', 'quantity' => 3]);
name defaults to 'default' when omitted. A single billable can hold multiple independent subscriptions, each identified by its name.

​
swap()

Upgrades or downgrades the plan on an existing subscription. 
// Immediate proration (global default: 'now')
Subscribd::for($user)->swap('default', 'pro');

// Defer the price change to the next renewal
Subscribd::for($user)->swap('default', 'pro', ['prorate' => 'renewal']);

// Target a named subscription other than 'default'
Subscribd::for($user)->swapTo('new-plan-key', 'addons', ['prorate' => 'renewal']);

​
cancel()

Cancels a subscription. By default cancellation takes effect at the end of the current billing period, leaving a grace period during which onGracePeriod() returns true. 
// Cancel at period end (default)
Subscribd::for($user)->cancel();

// Cancel a named subscription immediately
Subscribd::for($user)->cancel('default', immediately: true);

// Cancel a named add-on slot immediately
Subscribd::for($user)->cancelSubscription('addons', immediately: true);

​
resume()

Resumes a subscription that is in the grace period or in a paused state. 
Subscribd::for($user)->resume();

// Resume using the explicit method name
Subscribd::for($user)->resumeSubscription();

​
charge()

Issues a one-off charge to the billable outside of a recurring subscription. 
use Pixelworxio\Subscribd\Support\Money;

Subscribd::for($user)->charge(new Money(4900, 'USD'));

// BillableContext alias
Subscribd::for($user)->chargeOnce(new Money(4900, 'USD'));

​
applyCoupon()

Applies a coupon code directly from the context without needing to resolve the Coupon model yourself. 
Subscribd::for($user)->applyCoupon('LAUNCH20');

​
Per-call gateway override with ->on()

You can override the configured gateway for a single operation by chaining ->on('gateway-name') before any action method. This is useful when a user has payment methods on multiple gateways or when migrating between providers. 
// Use PayPal for this subscription only
Subscribd::for($user)->on('paypal')->subscribe('starter');

// Use PayPal for this subscription with explicit naming
Subscribd::for($user)->on('paypal')->subscribeTo('plan-key');
The ->on() method returns the same BillableContext instance, so the full method chain remains available. The override applies only to the next action call — it does not change the global default.

​
Direct gateway access with Subscribd::gateway()

When you need to call a gateway method that has no facade shortcut — for example, creating a customer record manually or registering a custom driver — use Subscribd::gateway() to get the driver instance directly. 
// Call a gateway method directly
Subscribd::gateway('stripe')->createCustomer($user);

// Register a custom gateway driver
use Pixelworxio\Subscribd\Contracts\GatewayManager;

app(GatewayManager::class)->extend('my-provider', function ($app) {
    return new MyProviderGateway($app['config']->get('services.my_provider'));
});
Use Subscribd::gateway() when you need a gateway capability that has no facade shortcut, such as creating a customer record before the subscriber has chosen a plan.

​
Complete BillableContext reference

MethodDescription
subscribe(string $plan, array $options = [])Create a new subscription
subscribeTo(string $plan, array $options = [])Alias for subscribe()
swap(string $name, string $newPlan, array $options = [])Upgrade or downgrade a named subscription
swapTo(string $newPlan, string $name = 'default', array $options = [])Swap with argument order flipped
cancel(string $name = 'default', bool $immediately = false)Cancel at period end or immediately
cancelSubscription(string $name = 'default', bool $immediately = false)Alias for cancel()
resume(string $name = 'default')Resume a paused or grace-period subscription
resumeSubscription(string $name = 'default')Alias for resume()
charge(Money $amount)Issue a one-off charge
chargeOnce(Money $amount)Alias for charge()
applyCoupon(string $code)Apply a coupon by code
on(string $gateway)Override the gateway for the next operation