> ## 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.

# One-Off Charges

> Charge a billable outside of their subscription

# One-Off Charges

Beyond recurring subscriptions, you can charge a billable once for additional services, overages, or add-ons using the `CreateInvoice` action.

## Creating a one-off charge

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

app(CreateInvoice::class)->execute($user, [
    [
        'description' => 'Custom report generation',
        'amount'      => 4900,   // $49.00 in cents
        'currency'    => 'USD',
        'quantity'    => 1,
    ],
]);
```

This creates and immediately collects an `Invoice` against the customer's default payment method. The action returns the `Invoice` model.

## Multiple line items

```php theme={null}
app(CreateInvoice::class)->execute($user, [
    [
        'description' => 'Data export — 10,000 rows',
        'amount'      => 2500,
        'currency'    => 'USD',
        'quantity'    => 1,
    ],
    [
        'description' => 'Priority processing',
        'amount'      => 1000,
        'currency'    => 'USD',
        'quantity'    => 1,
    ],
]);
```

## Passing options

Pass metadata or a specific gateway as the third argument:

```php theme={null}
app(CreateInvoice::class)->execute($user, $lineItems, [
    'gateway'  => 'stripe',
    'metadata' => ['order_id' => 42],
]);
```

## Accessing the invoice

The returned `Invoice` model gives you the full invoice record:

```php theme={null}
$invoice = app(CreateInvoice::class)->execute($user, $lineItems);

$invoice->status->value;     // 'paid' or 'failed'
$invoice->total();           // Money object
$invoice->pdf_url;           // Download link (if available)
```

## Handling payment failure

If the charge fails, `CreateInvoice` throws `Pixelworxio\Subscribd\Exceptions\PaymentFailedException`:

```php theme={null}
use Pixelworxio\Subscribd\Exceptions\PaymentFailedException;

try {
    $invoice = app(CreateInvoice::class)->execute($user, $lineItems);
} catch (PaymentFailedException $e) {
    // Log, notify, or surface an error to the user
    logger()->warning('One-off charge failed', ['user' => $user->id, 'reason' => $e->getMessage()]);
}
```

## Retrying a failed invoice

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

app(RetryInvoice::class)->execute($invoice);
```

## Next steps

* **[Invoice History](/invoices/history)** — Listing and displaying invoices
* **[Tax](/invoices/tax)** — Tax handling on invoices