Subscriptions

Managing subscriptions involves creating a subscription on Paystack and then tracking its status in your paystack_subscriptions table.

Creating a Subscription

To subscribe a user, you typically initialize a transaction with a plan parameter. When the user pays, Paystack creates the subscription.

Step 1: Initialize Transaction with Plan

use App\Models\User;

$user = User::find(1);

// Initialize transaction for a specific plan
$response = paystack()->transaction()->initialize([
    'email' => $user->email,
    'amount' => 5000, // Amount in kobo/pesewas (ignored if plan amount is set)
    'plan' => 'PLN_gx2wn530m0i3w3y', // The Plan Code
    'callback_url' => route('payment.callback')
]);

return redirect($response['data']['authorization_url']);

Step 2: Handle Webhook or Callback

After payment, Paystack will send a subscription.create webhook. This is where you should save the subscription to your database.

// In your Webhook Controller
public function handleWebhook(Request $request)
{
    $event = $request->input('event');
    $data = $request->input('data');

    if ($event === 'subscription.create') {
        // Find the user by email (or customer code)
        $user = User::where('email', $data['customer']['email'])->first();

        if ($user) {
            $user->subscriptions()->create([
                'name' => 'default', // or derive from plan
                'paystack_id' => $data['subscription_code'],
                'paystack_status' => $data['status'], // 'active'
                'paystack_plan' => $data['plan']['plan_code'],
                'ends_at' => $data['next_payment_date'] // Parse this date
            ]);
        }
    }
}

Checking Subscription Status

With the PaystackSubscription model methods we defined in the Setup guide, you can easily check the user's status.

$user = User::find(1);

// Get the subscription
$subscription = $user->subscriptions()->where('name', 'default')->first();

if (! $subscription) {
    // User has never subscribed
}

// 1. Check if Active (Paid & Valid)
if ($subscription->isActive()) {
    // Grant Access
}

// 2. Check if on Trial
if ($subscription->onTrial()) {
    // Grant Trial Access
}

// 3. Check if Cancelled but on Grace Period
if ($subscription->onGracePeriod()) {
    // Show banner: "Your subscription will end on " . $subscription->ends_at
}

// 4. Check if Fully Expired
if ($subscription->subscriptionEnded()) {
    // Redirect to renewal page
}

Cancelling a Subscription

To cancel a subscription, you call the Paystack API and then update your local database.

$subscription = $user->subscriptions()->where('name', 'default')->first();

// 1. Disable on Paystack
paystack()->subscription()->disable([
    'code' => $subscription->paystack_id,
    'token' => $subscription->email_token // You might need to store this if required
]);

// 2. Update local status
$subscription->update([
    'paystack_status' => 'cancelled',
    'ends_at' => now() // or keep the original end date for grace period
]);

Use Case: Multiple Subscriptions

If your app allows users to subscribe to different products (e.g., "Course A" and "Course B"), you can use the name field to distinguish them.

// Subscribe to Course A
$user->subscriptions()->create([
    'name' => 'course_a',
    'paystack_plan' => 'PLN_course_a_code',
    // ...
]);

// Check access
if ($user->subscriptions()->where('name', 'course_a')->first()?->active()) {
    // Show Course A content
}