> ## Documentation Index
> Fetch the complete documentation index at: https://docs.subscribd.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Applying Coupons

> Apply discount codes at checkout or to active subscriptions

# Applying Coupons

Coupons can be applied at the point of subscription creation, or to an existing active subscription.

## Applying at checkout

Pass a `coupon` option to `CreateSubscription`:

```php theme={null}
use Pixelworxio\Subscribd\Actions\CreateSubscription;
use Pixelworxio\Subscribd\Models\Plan;

$plan = Plan::query()->where('key', 'pro')->firstOrFail();

app(CreateSubscription::class)->execute($user, $plan, ['coupon' => 'SAVE20']);
```

## Applying to an active subscription

Use the `ApplyCoupon` action to attach a coupon to a subscription that already exists:

```php theme={null}
use Pixelworxio\Subscribd\Actions\ApplyCoupon;
use Pixelworxio\Subscribd\Models\Coupon;

$coupon = Coupon::query()->where('code', 'SAVE20')->firstOrFail();

app(ApplyCoupon::class)->execute($subscription, $coupon);
```

The coupon is pushed to the gateway (e.g., attached to the Stripe customer) and stored locally. The discount takes effect on the next invoice.

## subscriber.coupon-redeem component

For custom checkout flows that don't use `subscriber.plan-picker`, the `subscriber.coupon-redeem` Livewire component handles validation and session storage:

```blade theme={null}
<livewire:subscribd::subscriber.coupon-redeem />
```

### How it works

1. The user enters a coupon code and submits the form.
2. The component validates the code using `Coupon::isValid()` — checking expiry and maximum redemptions.
3. On success, the code is written to `session('subscribd.pending_checkout')['coupon']`.
4. When `subscriber.checkout` processes the subscription, it reads the session key and passes the coupon to `CreateSubscription`.
5. The browser event `subscribd:coupon-validated` is dispatched with `{ code }`.

```js theme={null}
document.addEventListener('subscribd:coupon-validated', (e) => {
    console.log('Coupon applied:', e.detail.code);
});

document.addEventListener('subscribd:coupon-removed', () => {
    console.log('Coupon removed');
});
```

### Named subscription slot

Scope the component to a named slot when using multiple subscriptions:

```blade theme={null}
<livewire:subscribd::subscriber.coupon-redeem subscription-name="team" />
```

## Removing a coupon

Remove a coupon from an active subscription:

```php theme={null}
use Pixelworxio\Subscribd\Actions\RemoveCoupon;

app(RemoveCoupon::class)->execute($subscription);
```

## Checking whether a coupon is applied

```php theme={null}
$subscription->coupon;           // Coupon model or null
$subscription->coupon?->code;    // 'SAVE20'
$subscription->hasActiveCoupon(); // bool
```

## Next steps

* **[Creating Coupons](/coupons/creating)** — Define coupon codes and rules
* **[Feature Grants](/coupons/feature-grants)** — Grant feature access via coupon