After running php artisan subscribd:install, Subscribd publishes its configuration file to config/subscribd.php. Most values read from environment variables so you can keep credentials out of version control and vary settings between environments. This page documents every key you are likely to customize.
Gateway
| Key | Env var | Type | Default | Description |
|---|
default | SUBSCRIBD_GATEWAY | string | 'stripe' | The gateway driver to use when no per-call override is specified. Accepted values: 'stripe', 'paypal', 'braintree', 'fake'. |
currency | — | string | 'USD' | Default ISO-4217 currency code. Used when creating invoices and charges that do not specify a currency explicitly. |
'default' => env('SUBSCRIBD_GATEWAY', 'stripe'),
'currency' => 'USD',
Proration
| Key | Env var | Type | Default | Description |
|---|
proration_strategy | SUBSCRIBD_PRORATION | string | 'now' | How price changes are handled on plan swaps. 'now' = immediate credit/charge; 'renewal' = switch at next renewal; 'none' = no credit, new price at next cycle. |
'proration_strategy' => env('SUBSCRIBD_PRORATION', 'now'),
Subscribd::for($user)->swap('default', 'pro', ['prorate' => 'renewal']);
Cancellation policy
| Key | Env var | Type | Default | Description |
|---|
cancel_policy | — | string | 'at_period_end' | Default cancellation behavior when $immediately is not passed. 'at_period_end' = grace period; 'immediately' = instant cancellation. |
'cancel_policy' => 'at_period_end', // 'at_period_end' | 'immediately'
Dunning
Dunning controls automatic failed-payment retries. The ProcessDunning job is scheduled hourly by the service provider — no additional scheduler configuration is required.
| Key | Env var | Type | Default | Description |
|---|
dunning.enabled | SUBSCRIBD_DUNNING_ENABLED | bool | true | Enable or disable automatic payment retries. |
dunning.retries | — | array | [24, 72, 168] | Hours between retry attempts after the initial failure. |
dunning.cancel_after_final_retry | — | bool | true | Cancel the subscription automatically if all retries are exhausted. |
'dunning' => [
'enabled' => env('SUBSCRIBD_DUNNING_ENABLED', true),
'retries' => [24, 72, 168], // hours between retry attempts
'cancel_after_final_retry' => true,
],
Tables
All table names can be overridden. This is useful when integrating Subscribd into an existing database that already has conflicting table names.
| Config key | Default table name |
|---|
tables.plans | subscribd_plans |
tables.subscriptions | subscribd_subscriptions |
tables.invoices | subscribd_invoices |
tables.payment_methods | subscribd_payment_methods |
tables.coupons | subscribd_coupons |
tables.feature_usage | subscribd_feature_usage |
tables.usage_records | subscribd_usage_records |
tables.webhook_events | subscribd_webhook_events |
'tables' => [
'plans' => 'subscribd_plans',
'subscriptions' => 'subscribd_subscriptions',
'invoices' => 'subscribd_invoices',
'payment_methods' => 'subscribd_payment_methods',
'coupons' => 'subscribd_coupons',
'feature_usage' => 'subscribd_feature_usage',
'usage_records' => 'subscribd_usage_records',
'webhook_events' => 'subscribd_webhook_events',
],
If you override table names, do so before running migrations. Migrations read from these config keys, so changing them after running migrations will leave orphaned tables and break queries.
Plans
Plans are defined under the plans key and synced to the database with php artisan subscribd:plan sync. All prices are in minor currency units (cents for USD).
'plans' => [
'starter' => [
'name' => 'Starter',
'description' => 'Full product access for individuals.',
'rule' => 'flat', // 'flat' | 'per_unit' | 'tiered' | 'metered'
'price' => 1900, // $19.00/month
'currency' => 'USD',
'interval' => 'month', // 'day' | 'week' | 'month' | 'year'
'interval_count' => 1,
'trial_days' => 14,
'features' => [
'projects' => 5,
'api_access' => true,
'support' => 'email',
],
],
],
Gateways
Each gateway reads its credentials from environment variables.
'gateways' => [
'stripe' => [
'secret' => env('STRIPE_SECRET'),
'key' => env('STRIPE_KEY'),
'webhook_secret' => env('STRIPE_WEBHOOK_SECRET'),
],
],
SUBSCRIBD_GATEWAY=stripe
STRIPE_SECRET=sk_live_...
STRIPE_KEY=pk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
'gateways' => [
'paypal' => [
'client_id' => env('PAYPAL_CLIENT_ID'),
'client_secret' => env('PAYPAL_CLIENT_SECRET'),
'webhook_id' => env('PAYPAL_WEBHOOK_ID'),
'mode' => env('PAYPAL_MODE', 'live'),
],
],
SUBSCRIBD_GATEWAY=paypal
PAYPAL_CLIENT_ID=...
PAYPAL_CLIENT_SECRET=...
PAYPAL_WEBHOOK_ID=...
PAYPAL_MODE=live
'gateways' => [
'braintree' => [
'environment' => env('BRAINTREE_ENV', 'production'),
'merchant_id' => env('BRAINTREE_MERCHANT_ID'),
'public_key' => env('BRAINTREE_PUBLIC_KEY'),
'private_key' => env('BRAINTREE_PRIVATE_KEY'),
],
],
SUBSCRIBD_GATEWAY=braintree
BRAINTREE_ENV=production
BRAINTREE_MERCHANT_ID=...
BRAINTREE_PUBLIC_KEY=...
BRAINTREE_PRIVATE_KEY=...
Admin panel
The built-in Blade admin panel is available at /subscribd/admin by default.
| Key | Type | Default | Description |
|---|
admin.enabled | bool | true | Enable or disable the admin panel routes. Set to false when using Filament resources instead. |
admin.path | string | 'subscribd/admin' | URL path for the admin panel. |
admin.middleware | array | ['web', 'auth'] | Middleware applied to all admin routes. |
'admin' => [
'enabled' => true,
'path' => 'subscribd/admin',
'middleware' => ['web', 'auth', 'can:manage-billing'],
],
If you use Filament, set 'admin.enabled' => false to avoid duplicate management interfaces. The Filament PlanResource and SubscriptionResource are auto-registered when Filament is present.
Billables
Register every Eloquent model type that can hold subscriptions. The package uses these mappings for polymorphic queries.
'billables' => [
'user' => \App\Models\User::class,
'team' => \App\Models\Team::class,
],
billable_type value stored in the database. If you rename a model class, add a new entry rather than changing the existing key so that historical records remain intact.
Full environment variable reference
| Env var | Config key | Description |
|---|
SUBSCRIBD_GATEWAY | default | Default gateway driver |
SUBSCRIBD_PRORATION | proration_strategy | Global proration strategy |
SUBSCRIBD_DUNNING_ENABLED | dunning.enabled | Enable/disable dunning retries |
STRIPE_SECRET | gateways.stripe.secret | Stripe secret key |
STRIPE_KEY | gateways.stripe.key | Stripe publishable key |
STRIPE_WEBHOOK_SECRET | gateways.stripe.webhook_secret | Stripe webhook signing secret |
PAYPAL_CLIENT_ID | gateways.paypal.client_id | PayPal OAuth client ID |
PAYPAL_CLIENT_SECRET | gateways.paypal.client_secret | PayPal OAuth client secret |
PAYPAL_WEBHOOK_ID | gateways.paypal.webhook_id | PayPal webhook ID |
PAYPAL_MODE | gateways.paypal.mode | PayPal environment (live or sandbox) |
BRAINTREE_ENV | gateways.braintree.environment | Braintree environment |
BRAINTREE_MERCHANT_ID | gateways.braintree.merchant_id | Braintree merchant ID |
BRAINTREE_PUBLIC_KEY | gateways.braintree.public_key | Braintree public key |
BRAINTREE_PRIVATE_KEY | gateways.braintree.private_key | Braintree private key |
