fluentcart-developer 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. package/.gitattributes +2 -0
  2. package/CLAUDE.md +22 -0
  3. package/CONTRIBUTING.md +73 -0
  4. package/LICENSE +21 -0
  5. package/README.md +127 -0
  6. package/SKILL.md +127 -0
  7. package/bin/index.js +281 -0
  8. package/copy-skills.js +43 -0
  9. package/package.json +38 -0
  10. package/skills/fluentcart-developer/SKILL.md +172 -0
  11. package/skills/fluentcart-developer/examples/README.md +25 -0
  12. package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/fluent-cart/checkout.php +32 -0
  13. package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/functions.php +40 -0
  14. package/skills/fluentcart-developer/examples/sample-custom-addon/fluentcart-custom-addon.php +114 -0
  15. package/skills/fluentcart-developer/examples/sample-custom-payment-gateway/fluentcart-custom-gateway-example.php +149 -0
  16. package/skills/fluentcart-developer/examples/sample-fee-surcharge-plugin/fluentcart-fee-surcharge.php +38 -0
  17. package/skills/fluentcart-developer/examples/sample-shipping-carrier/fluentcart-custom-shipping-carrier.php +62 -0
  18. package/skills/fluentcart-developer/references/action-hooks-admin-templates.md +787 -0
  19. package/skills/fluentcart-developer/references/action-hooks-cart-checkout.md +1355 -0
  20. package/skills/fluentcart-developer/references/action-hooks-customers-users.md +266 -0
  21. package/skills/fluentcart-developer/references/action-hooks-licenses.md +855 -0
  22. package/skills/fluentcart-developer/references/action-hooks-orders.md +631 -0
  23. package/skills/fluentcart-developer/references/action-hooks-payments-integrations.md +963 -0
  24. package/skills/fluentcart-developer/references/action-hooks-products-coupons.md +585 -0
  25. package/skills/fluentcart-developer/references/action-hooks-subscriptions.md +661 -0
  26. package/skills/fluentcart-developer/references/database-models-query-builder.md +194 -0
  27. package/skills/fluentcart-developer/references/database-models-reference.md +604 -0
  28. package/skills/fluentcart-developer/references/database-schema-reference.md +940 -0
  29. package/skills/fluentcart-developer/references/engineering-notes.md +154 -0
  30. package/skills/fluentcart-developer/references/fee-system-guide.md +449 -0
  31. package/skills/fluentcart-developer/references/filter-hooks-cart-checkout.md +1202 -0
  32. package/skills/fluentcart-developer/references/filter-hooks-customers-subscriptions.md +902 -0
  33. package/skills/fluentcart-developer/references/filter-hooks-integrations-advanced.md +1598 -0
  34. package/skills/fluentcart-developer/references/filter-hooks-orders-payments.md +1319 -0
  35. package/skills/fluentcart-developer/references/filter-hooks-products-pricing.md +628 -0
  36. package/skills/fluentcart-developer/references/filter-hooks-settings-configuration.md +1177 -0
  37. package/skills/fluentcart-developer/references/fluentcart-developer-guide.md +154 -0
  38. package/skills/fluentcart-developer/references/ghost-product-selling.md +458 -0
  39. package/skills/fluentcart-developer/references/modules-and-extensions-reference.md +224 -0
  40. package/skills/fluentcart-developer/references/paddle-gateway-case-study.md +1925 -0
  41. package/skills/fluentcart-developer/references/payment-gateway-integration.md +761 -0
  42. package/skills/fluentcart-developer/references/rest-api-checkout.md +286 -0
  43. package/skills/fluentcart-developer/references/rest-api-coupons.md +794 -0
  44. package/skills/fluentcart-developer/references/rest-api-customer-profile.md +190 -0
  45. package/skills/fluentcart-developer/references/rest-api-customers.md +1121 -0
  46. package/skills/fluentcart-developer/references/rest-api-dashboard-utilities.md +219 -0
  47. package/skills/fluentcart-developer/references/rest-api-email-notifications.md +619 -0
  48. package/skills/fluentcart-developer/references/rest-api-files.md +290 -0
  49. package/skills/fluentcart-developer/references/rest-api-integrations.md +324 -0
  50. package/skills/fluentcart-developer/references/rest-api-labels-attributes.md +321 -0
  51. package/skills/fluentcart-developer/references/rest-api-licensing.md +171 -0
  52. package/skills/fluentcart-developer/references/rest-api-order-bumps.md +200 -0
  53. package/skills/fluentcart-developer/references/rest-api-orders.md +1241 -0
  54. package/skills/fluentcart-developer/references/rest-api-overview.md +131 -0
  55. package/skills/fluentcart-developer/references/rest-api-products.md +2563 -0
  56. package/skills/fluentcart-developer/references/rest-api-public-shop.md +172 -0
  57. package/skills/fluentcart-developer/references/rest-api-reference.md +552 -0
  58. package/skills/fluentcart-developer/references/rest-api-reports.md +377 -0
  59. package/skills/fluentcart-developer/references/rest-api-roles-permissions.md +147 -0
  60. package/skills/fluentcart-developer/references/rest-api-settings.md +528 -0
  61. package/skills/fluentcart-developer/references/rest-api-shipping.md +800 -0
  62. package/skills/fluentcart-developer/references/rest-api-subscriptions.md +606 -0
  63. package/skills/fluentcart-developer/references/rest-api-tax.md +356 -0
  64. package/skills/fluentcart-developer/references/subscription-customization.md +197 -0
  65. package/skills/fluentcart-developer/scripts/cli.js +1 -0
  66. package/skills.sh.json +13 -0
@@ -0,0 +1,902 @@
1
+ # Filter Hooks: Customers & Subscriptions
2
+
3
+ All filters related to Customer management, the customer portal, Subscription lifecycle, billing configuration, and automated reminders.
4
+
5
+ ---
6
+
7
+ ## Customer Data & Portal
8
+
9
+ ### `customer/view`
10
+ `fluent_cart/customer/view` — Filter admin single customer view data
11
+
12
+ * **When it runs:** Applied when preparing a single customer's data for display in the admin panel.
13
+ * **Source:** `app/Http/Controllers/CustomerController.php` (line 74)
14
+
15
+ #### Parameters:
16
+ * `$customer` *(\FluentCart\App\Models\Customer)* — Customer model instance with loaded relations (`id`, `email`, `total_spent`, etc.)
17
+ * `$requestData` *(array)* — Full request data from `$request->all()`
18
+ * **Returns:** *(\FluentCart\App\Models\Customer)* — The modified customer data
19
+
20
+ #### Usage Example:
21
+ ```php
22
+ // Filter single customer view data payload in admin panel
23
+ add_filter('fluent_cart/customer/view', function($customer, $requestData) {
24
+ // Inject loyalty points user meta into customer view data
25
+ $customer['loyalty_points'] = get_user_meta($customer['user_id'], 'loyalty_points', true);
26
+ return $customer;
27
+ }, 10, 2);
28
+ ```
29
+
30
+ ---
31
+
32
+ ### `widgets/single_customer`
33
+ `fluent_cart/widgets/single_customer` — Filter single customer admin widgets
34
+
35
+ * **When it runs:** Applied when loading widget data for a single customer's admin view, allowing custom widget section injection.
36
+ * **Source:** `app/Http/Controllers/CustomerController.php` (line 177)
37
+
38
+ #### Parameters:
39
+ * `$widgets` *(array)* — Array of widget definitions (default: `[]`)
40
+ * `$customer` *(\FluentCart\App\Models\Customer)* — Customer model instance
41
+ * **Returns:** *(array)* — The modified widgets array
42
+
43
+ #### Usage Example:
44
+ ```php
45
+ // Filter admin widgets loaded on single customer detail view page
46
+ add_filter('fluent_cart/widgets/single_customer', function($widgets, $customer) {
47
+ // Append custom CRM notes widget definition for customer
48
+ $widgets[] = [
49
+ 'title' => 'CRM Notes',
50
+ 'content' => get_user_meta($customer->user_id, 'crm_notes', true)
51
+ ];
52
+ return $widgets;
53
+ }, 10, 2);
54
+ ```
55
+
56
+ ---
57
+
58
+ ### `customer_dashboard_data`
59
+ `fluent_cart/customer_dashboard_data` — Filter customer dashboard data
60
+
61
+ * **When it runs:** Applied when preparing customer portal dashboard data, including recent orders list and section parts. Runs both when a customer exists and when no customer is found.
62
+ * **Source:** `app/Http/Controllers/FrontendControllers/CustomerProfileController.php` (lines 58, 114)
63
+
64
+ #### Parameters:
65
+ * `$data` *(array)* — Dashboard response data (`message`, `dashboard_data`, `sections_parts`)
66
+ * `$context` *(array)* — Context data containing customer (`['customer' => Customer|null]`)
67
+ * **Returns:** *(array)* — The modified dashboard data
68
+
69
+ #### Usage Example:
70
+ ```php
71
+ // Filter customer portal dashboard response data payload
72
+ add_filter('fluent_cart/customer_dashboard_data', function($data, $context) {
73
+ // Extract customer model instance from context
74
+ $customer = $context['customer'];
75
+ if ($customer) {
76
+ // Inject welcome banner HTML above customer orders table
77
+ $data['sections_parts']['before_orders_table'] = '<div class="welcome-banner">Welcome back!</div>';
78
+ }
79
+ return $data;
80
+ }, 10, 2);
81
+ ```
82
+
83
+ ---
84
+
85
+ ### `global_customer_menu_items`
86
+ `fluent_cart/global_customer_menu_items` — Filter customer portal menu items
87
+
88
+ * **When it runs:** Applied when building customer portal sidebar navigation menu, after built-in items have been conditionally removed.
89
+ * **Source:** `app/Hooks/Handlers/ShortCodes/CustomerProfileHandler.php` (line 266)
90
+
91
+ #### Parameters:
92
+ * `$menuItems` *(array)* — Associative array of menu items keyed by slug (`orders`, `subscriptions`, `licenses`, `downloads`, `profile`)
93
+ * `$context` *(array)* — Context data (`['base_url' => string]`)
94
+ * **Returns:** *(array)* — The modified menu items array
95
+
96
+ #### Usage Example:
97
+ ```php
98
+ // Filter customer portal sidebar navigation menu items
99
+ add_filter('fluent_cart/global_customer_menu_items', function($menuItems, $context) {
100
+ // Inject custom Support menu item into customer portal navigation
101
+ $baseUrl = $context['base_url'];
102
+ $menuItems['support'] = [
103
+ 'label' => 'Support',
104
+ 'css_class' => 'fct_route',
105
+ 'link' => $baseUrl . 'support',
106
+ 'icon_svg' => '<svg>...</svg>'
107
+ ];
108
+ return $menuItems;
109
+ }, 10, 2);
110
+ ```
111
+
112
+ ---
113
+
114
+ ### `customer_portal/active_tab`
115
+ `fluent_cart/customer_portal/active_tab` — Filter active tab in customer portal
116
+
117
+ * **When it runs:** Applied when rendering customer portal to determine which tab should be visually active by default.
118
+ * **Source:** `app/Hooks/Handlers/ShortCodes/CustomerProfileHandler.php` (line 117)
119
+
120
+ #### Parameters:
121
+ * `$activeTab` *(string)* — Active tab identifier (default: `''`)
122
+ * **Returns:** *(string)* — Modified active tab slug
123
+
124
+ #### Usage Example:
125
+ ```php
126
+ // Filter default active tab slug in customer portal view
127
+ add_filter('fluent_cart/customer_portal/active_tab', function($activeTab) {
128
+ // Set default active tab to subscriptions
129
+ return 'subscriptions';
130
+ }, 10, 1);
131
+ ```
132
+
133
+ ---
134
+
135
+ ### `customer_portal/custom_endpoints`
136
+ `fluent_cart/customer_portal/custom_endpoints` — Filter custom portal endpoints
137
+
138
+ * **When it runs:** Applied when routing customer portal requests to check for registered custom endpoint paths.
139
+ * **Source:** `app/Hooks/Handlers/ShortCodes/CustomerProfileHandler.php` (line 141)
140
+
141
+ #### Parameters:
142
+ * `$endpoints` *(array)* — Associative array of custom endpoints (default: `[]`)
143
+ * **Returns:** *(array)* — Modified endpoints array
144
+
145
+ #### Usage Example:
146
+ ```php
147
+ // Register custom endpoint page handlers in customer portal
148
+ add_filter('fluent_cart/customer_portal/custom_endpoints', function($endpoints) {
149
+ // Add custom warranty page rendering callback to portal endpoints
150
+ $endpoints['warranty'] = [
151
+ 'render_callback' => function() {
152
+ echo '<div class="warranty-page">Warranty info here</div>';
153
+ }
154
+ ];
155
+ return $endpoints;
156
+ }, 10, 1);
157
+ ```
158
+
159
+ > [!TIP]
160
+ > Consider using the `FluentCartGeneralApi::addCustomerPortalEndpoint()` helper method instead, which registers both the menu item and the endpoint in one call.
161
+
162
+ ---
163
+
164
+ ### `customer_portal/subscription_data`
165
+ `fluent_cart/customer_portal/subscription_data` — Filter customer portal subscription data
166
+
167
+ * **When it runs:** Applied when preparing a single subscription's data for display in customer portal, after transactions are loaded.
168
+ * **Source:** `app/Http/Controllers/FrontendControllers/CustomerSubscriptionController.php` (line 157)
169
+
170
+ #### Parameters:
171
+ * `$formattedData` *(array)* — Formatted subscription data including transactions
172
+ * `$context` *(array)* — Context data (`['subscription' => Subscription, 'customer' => Customer]`)
173
+ * **Returns:** *(array)* — Modified subscription data
174
+
175
+ #### Usage Example:
176
+ ```php
177
+ // Filter subscription data structure formatted for customer portal
178
+ add_filter('fluent_cart/customer_portal/subscription_data', function($formattedData, $context) {
179
+ // Extract subscription model instance from context
180
+ $subscription = $context['subscription'];
181
+ // Inject next invoice preview array into subscription details
182
+ $formattedData['next_invoice_preview'] = [
183
+ 'amount' => $subscription->recurring_amount,
184
+ 'date' => $subscription->expiration_at
185
+ ];
186
+ return $formattedData;
187
+ }, 10, 2);
188
+ ```
189
+
190
+ ---
191
+
192
+ ### `payment_methods/stripe_pub_key`
193
+ `fluent_cart/payment_methods/stripe_pub_key` — Filter Stripe public key for customer portal
194
+
195
+ * **When it runs:** Applied when localizing JavaScript data for customer portal, providing Stripe publishable key.
196
+ * **Source:** `app/Hooks/Handlers/ShortCodes/CustomerProfileHandler.php` (line 356)
197
+
198
+ #### Parameters:
199
+ * `$pubKey` *(string)* — Stripe publishable key (default: `''`)
200
+ * **Returns:** *(string)* — Modified Stripe public key
201
+
202
+ #### Usage Example:
203
+ ```php
204
+ // Filter Stripe publishable key passed to customer portal JS
205
+ add_filter('fluent_cart/payment_methods/stripe_pub_key', function($pubKey) {
206
+ // Override Stripe publishable key in test environment
207
+ if (defined('STRIPE_TEST_MODE') && STRIPE_TEST_MODE) {
208
+ return 'pk_test_xxxxxxxxxxxx';
209
+ }
210
+ return $pubKey;
211
+ }, 10, 1);
212
+ ```
213
+
214
+ ---
215
+
216
+ ### `payment_methods/paypal_client_id`
217
+ `fluent_cart/payment_methods/paypal_client_id` — Filter PayPal client ID for customer portal
218
+
219
+ * **When it runs:** Applied when localizing JavaScript data for customer portal, providing PayPal client ID.
220
+ * **Source:** `app/Hooks/Handlers/ShortCodes/CustomerProfileHandler.php` (line 357)
221
+
222
+ #### Parameters:
223
+ * `$clientId` *(string)* — PayPal client ID (default: `''`)
224
+ * `$context` *(array)* — Additional context data (default: `[]`)
225
+ * **Returns:** *(string)* — Modified PayPal client ID
226
+
227
+ #### Usage Example:
228
+ ```php
229
+ // Filter PayPal client ID passed to customer portal JS
230
+ add_filter('fluent_cart/payment_methods/paypal_client_id', function($clientId, $context) {
231
+ // Provide sandbox PayPal client ID for client-side JS SDK
232
+ return 'AYourPayPalClientId';
233
+ }, 10, 2);
234
+ ```
235
+
236
+ ---
237
+
238
+ ## Customer Statuses & Auth
239
+
240
+ ### `editable_customer_statuses` (legacy)
241
+ `fluent-cart/editable_customer_statuses` — Filter editable customer statuses
242
+
243
+ * **When it runs:** Applied when retrieving list of customer statuses that can be set in admin panel. Note hyphenated prefix (`fluent-cart/`).
244
+ * **Source:** `app/Helpers/Helper.php` (line 162), `app/Helpers/Status.php` (line 350)
245
+
246
+ #### Parameters:
247
+ * `$statuses` *(array)* — Associative array of status key => label (`'active' => 'Active'`, `'inactive' => 'Inactive'`)
248
+ * `$context` *(array)* — Additional context data (default: `[]`)
249
+ * **Returns:** *(array)* — Modified statuses array
250
+
251
+ #### Usage Example:
252
+ ```php
253
+ // Filter editable customer statuses in admin panel (legacy hyphenated hook)
254
+ add_filter('fluent-cart/editable_customer_statuses', function($statuses, $context) {
255
+ // Add custom "Suspended" status to editable customer statuses
256
+ $statuses['suspended'] = __('Suspended', 'my-plugin');
257
+ return $statuses;
258
+ }, 10, 2);
259
+ ```
260
+
261
+ ---
262
+
263
+ ### `user/after_register/skip_hooks`
264
+ `fluent_cart/user/after_register/skip_hooks` — Skip post-registration hooks
265
+
266
+ * **When it runs:** Applied after a new WP user is created during checkout registration. When true, standard WP hooks like `register_new_user` are skipped.
267
+ * **Source:** `app/Services/AuthService.php` (line 122)
268
+
269
+ #### Parameters:
270
+ * `$skip` *(bool)* — Whether to skip hooks (default: `false`)
271
+ * `$user_id` *(int)* — Newly created WP user ID
272
+ * **Returns:** *(bool)* — Whether to skip post-registration hooks
273
+
274
+ #### Usage Example:
275
+ ```php
276
+ // Control skipping post-registration hooks during checkout user creation
277
+ add_filter('fluent_cart/user/after_register/skip_hooks', function($skip, $userId) {
278
+ // Skip default WP registration hooks to prevent welcome email dispatch
279
+ return true;
280
+ }, 10, 2);
281
+ ```
282
+
283
+ ---
284
+
285
+ ## Subscription Statuses & Configuration
286
+
287
+ ### `subscription_statuses`
288
+ `fluent_cart/subscription_statuses` — Filter subscription statuses
289
+
290
+ * **When it runs:** Applied when retrieving list of all available subscription statuses throughout system.
291
+ * **Source:** `app/Helpers/Status.php` (line 253)
292
+
293
+ #### Parameters:
294
+ * `$statuses` *(array)* — Associative array of status key => label (`pending`, `active`, `failing`, `paused`, `expired`, `expiring`, `canceled`, `trialing`, `intended`, `past_due`, `completed`)
295
+ * `$context` *(array)* — Additional context data (default: `[]`)
296
+ * **Returns:** *(array)* — Modified subscription statuses array
297
+
298
+ #### Usage Example:
299
+ ```php
300
+ // Filter available subscription statuses array across system
301
+ add_filter('fluent_cart/subscription_statuses', function($statuses, $context) {
302
+ // Add custom "On Hold" subscription status
303
+ $statuses['on_hold'] = __('On Hold', 'my-plugin');
304
+ return $statuses;
305
+ }, 10, 2);
306
+ ```
307
+
308
+ ---
309
+
310
+ ### `validable_subscription_statuses`
311
+ `fluent_cart/validable_subscription_statuses` — Filter valid (active) subscription statuses
312
+
313
+ * **When it runs:** Applied when determining which subscription statuses are considered "valid" for granting access (licenses, downloads, etc.).
314
+ * **Source:** `app/Helpers/Status.php` (line 271)
315
+
316
+ #### Parameters:
317
+ * `$statuses` *(array)* — Array of status keys considered valid (default: `['active', 'trialing']`)
318
+ * `$context` *(array)* — Additional context data (default: `[]`)
319
+ * **Returns:** *(array)* — Modified list of valid statuses
320
+
321
+ #### Usage Example:
322
+ ```php
323
+ // Filter subscription statuses considered valid for access control
324
+ add_filter('fluent_cart/validable_subscription_statuses', function($statuses, $context) {
325
+ // Include "expiring" status in list of valid subscription statuses
326
+ $statuses[] = 'expiring';
327
+ return $statuses;
328
+ }, 10, 2);
329
+ ```
330
+
331
+ ---
332
+
333
+ ### `subscription/view`
334
+ `fluent_cart/subscription/view` — Filter admin subscription view data
335
+
336
+ * **When it runs:** Applied when preparing a single subscription's data for display in admin panel.
337
+ * **Source:** `app/Modules/Subscriptions/Http/Controllers/SubscriptionController.php` (line 63)
338
+
339
+ #### Parameters:
340
+ * `$subscription` *(\FluentCart\App\Models\Subscription)* — Subscription model with loaded relations
341
+ * `$context` *(array)* — Additional context data (default: `[]`)
342
+ * **Returns:** *(array)* — Modified subscription data
343
+
344
+ #### Usage Example:
345
+ ```php
346
+ // Filter single subscription view data structure in admin panel
347
+ add_filter('fluent_cart/subscription/view', function($subscription, $context) {
348
+ // Append external Stripe dashboard link to subscription data payload
349
+ $subscription['external_url'] = 'https://dashboard.stripe.com/subscriptions/' . $subscription['vendor_subscription_id'];
350
+ return $subscription;
351
+ }, 10, 2);
352
+ ```
353
+
354
+ ---
355
+
356
+ ### `subscription/url_{$payment_method}`
357
+ `fluent_cart/subscription/url_{$payment_method}` — Filter vendor dashboard URL for a subscription
358
+
359
+ * **When it runs:** Applied when generating external vendor dashboard URL for subscription. Dynamic hook name with `{$payment_method}` replaced by gateway slug (`stripe`, `paypal`).
360
+ * **Source:** `app/Models/Subscription.php` (line 158)
361
+
362
+ #### Parameters:
363
+ * `$url` *(string)* — Vendor dashboard URL (default: `''`)
364
+ * `$context` *(array)* — Context data (`['vendor_subscription_id' => string, 'payment_mode' => 'live'|'test', 'subscription' => Subscription]`)
365
+ * **Returns:** *(string)* — Modified vendor dashboard URL
366
+
367
+ #### Usage Example:
368
+ ```php
369
+ // Filter vendor dashboard URL attribute for Stripe subscriptions
370
+ add_filter('fluent_cart/subscription/url_stripe', function($url, $context) {
371
+ // Extract vendor subscription ID and payment mode
372
+ $subId = $context['vendor_subscription_id'];
373
+ $mode = $context['payment_mode'];
374
+ $base = ($mode === 'test')
375
+ ? 'https://dashboard.stripe.com/test'
376
+ : 'https://dashboard.stripe.com';
377
+ return $base . '/subscriptions/' . $subId;
378
+ }, 10, 2);
379
+ ```
380
+
381
+ ---
382
+
383
+ ### `subscription/can_reactivate`
384
+ `fluent_cart/subscription/can_reactivate` — Filter whether subscription can be reactivated
385
+
386
+ * **When it runs:** Applied when checking if a canceled, failing, expired, paused, expiring, or past-due subscription is eligible for reactivation.
387
+ * **Source:** `app/Models/Subscription.php` (line 427)
388
+
389
+ #### Parameters:
390
+ * `$canReactivate` *(bool)* — Whether subscription can be reactivated based on status
391
+ * `$context` *(array)* — Context data (`['subscription' => Subscription]`)
392
+ * **Returns:** *(bool)* — Modified reactivation eligibility
393
+
394
+ #### Usage Example:
395
+ ```php
396
+ // Filter whether subscription is eligible for reactivation
397
+ add_filter('fluent_cart/subscription/can_reactivate', function($canReactivate, $context) {
398
+ $subscription = $context['subscription'];
399
+
400
+ // Prevent reactivation for subscriptions canceled more than 90 days ago
401
+ if ($subscription->status === 'canceled') {
402
+ $canceledAt = strtotime($subscription->updated_at);
403
+ if ((time() - $canceledAt) > (90 * DAY_IN_SECONDS)) {
404
+ return false;
405
+ }
406
+ }
407
+ return $canReactivate;
408
+ }, 10, 2);
409
+ ```
410
+
411
+ ---
412
+
413
+ ### `available_subscription_interval_options`
414
+ `fluent_cart/available_subscription_interval_options` — Filter subscription interval options
415
+
416
+ * **When it runs:** Applied when retrieving list of available subscription billing interval options for product configuration.
417
+ * **Source:** `app/Helpers/Helper.php` (line 1531)
418
+
419
+ #### Parameters:
420
+ * `$intervals` *(array)* — Array of interval option objects (`yearly`, `half_yearly`, `quarterly`, `monthly`, `weekly`, `daily`)
421
+ * **Returns:** *(array)* — Modified intervals array
422
+
423
+ #### Usage Example:
424
+ ```php
425
+ // Filter available subscription billing interval options
426
+ add_filter('fluent_cart/available_subscription_interval_options', function($intervals) {
427
+ // Add custom "Every 10th Day" billing interval option
428
+ $intervals[] = [
429
+ 'label' => __('Every 10th Day', 'my-plugin'),
430
+ 'value' => 'every_tenth_day',
431
+ 'map_value' => '10th Day'
432
+ ];
433
+ return $intervals;
434
+ });
435
+ ```
436
+
437
+ > [!TIP]
438
+ > When adding custom intervals, you must also implement `fluent_cart/subscription_interval_in_days` and `fluent_cart/subscription_billing_period` filters.
439
+
440
+ ---
441
+
442
+ ### `subscription_interval_in_days`
443
+ `fluent_cart/subscription_interval_in_days` — Filter number of days for custom subscription interval
444
+
445
+ * **When it runs:** Applied when converting subscription interval to day count. Built-in intervals calculate automatically; fires for custom/unknown intervals.
446
+ * **Source:** `app/Helpers/Helper.php` (line 1592), `app/Services/Payments/PaymentHelper.php` (line 236)
447
+
448
+ #### Parameters:
449
+ * `$days` *(int)* — Number of days for interval (default: `0` for custom)
450
+ * `$context` *(array)* — Context data (`['interval' => string]`)
451
+ * **Returns:** *(int)* — Number of days in interval
452
+
453
+ #### Usage Example:
454
+ ```php
455
+ // Filter day count for custom subscription billing interval
456
+ add_filter('fluent_cart/subscription_interval_in_days', function($days, $args) {
457
+ $interval = $args['interval'];
458
+
459
+ // Return 10 days for custom every_tenth_day interval
460
+ if ($interval === 'every_tenth_day') {
461
+ return 10;
462
+ }
463
+
464
+ // Return 14 days for custom biweekly interval
465
+ if ($interval === 'biweekly') {
466
+ return 14;
467
+ }
468
+
469
+ return $days;
470
+ }, 10, 2);
471
+ ```
472
+
473
+ ---
474
+
475
+ ### `max_trial_days_allowed`
476
+ `fluent_cart/max_trial_days_allowed` — Filter maximum trial days allowed
477
+
478
+ * **When it runs:** Applied when calculating adjusted trial days for subscription interval. Ensures trial does not exceed maximum.
479
+ * **Source:** `app/Helpers/Helper.php` (line 1566)
480
+
481
+ #### Parameters:
482
+ * `$maxDays` *(int)* — Maximum trial days allowed (default: `365`)
483
+ * `$context` *(array)* — Context data (`['existing_trial_days' => int, 'repeat_interval' => string, 'interval_in_days' => int]`)
484
+ * **Returns:** *(int)* — Modified maximum trial days
485
+
486
+ #### Usage Example:
487
+ ```php
488
+ // Filter maximum trial days allowed for subscription intervals
489
+ add_filter('fluent_cart/max_trial_days_allowed', function($maxDays, $args) {
490
+ // Cap trial duration at 30 days for monthly subscriptions
491
+ if ($args['repeat_interval'] === 'monthly') {
492
+ return 30;
493
+ }
494
+ return $maxDays;
495
+ }, 10, 2);
496
+ ```
497
+
498
+ ---
499
+
500
+ ### `trial_info`
501
+ `fluent_cart/trial_info` — Filter trial info display text
502
+
503
+ * **When it runs:** Applied when generating human-readable trial information text shown to customers (e.g. "Free Trial: 14 days").
504
+ * **Source:** `app/Helpers/Helper.php` (line 1133)
505
+
506
+ #### Parameters:
507
+ * `$trialInfo` *(string)* — Generated trial info text
508
+ * `$otherInfo` *(array)* — Product/variant pricing metadata (`trial_days`, `signup_fee`, etc.)
509
+ * **Returns:** *(string)* — Modified trial info text
510
+
511
+ #### Usage Example:
512
+ ```php
513
+ // Filter human-readable trial information display text string
514
+ add_filter('fluent_cart/trial_info', function($trialInfo, $otherInfo) {
515
+ // Extract trial days from product pricing metadata
516
+ $days = $otherInfo['trial_days'] ?? 0;
517
+ if ($days > 0) {
518
+ return sprintf('Try free for %d days - no credit card required!', $days);
519
+ }
520
+ return $trialInfo;
521
+ }, 10, 2);
522
+ ```
523
+
524
+ ---
525
+
526
+ ## Subscription Billing
527
+
528
+ ### `subscription_billing_period`
529
+ `fluent_cart/subscription_billing_period` — Filter billing period for payment gateways
530
+
531
+ * **When it runs:** Applied when translating subscription interval into payment gateway billing period format (Stripe Plans, PayPal billing cycles).
532
+ * **Source:** `app/Modules/PaymentMethods/StripeGateway/Plan.php` (line 58), `app/Modules/PaymentMethods/PayPalGateway/PayPalHelper.php` (line 243)
533
+
534
+ #### Parameters:
535
+ * `$billingPeriod` *(array)* — Gateway billing period (`['interval_unit' => 'month', 'interval_frequency' => 1]`)
536
+ * `$context` *(array)* — Context data (`['subscription_interval' => string, 'payment_method' => 'stripe'|'paypal']`)
537
+ * **Returns:** *(array)* — Modified billing period array
538
+
539
+ #### Usage Example:
540
+ ```php
541
+ // Filter gateway billing period mapping for custom subscription intervals
542
+ add_filter('fluent_cart/subscription_billing_period', function($billingPeriod, $args) {
543
+ $interval = $args['subscription_interval'];
544
+ $method = $args['payment_method'];
545
+
546
+ // Map custom every_tenth_day interval for Stripe and PayPal gateways
547
+ if ($interval === 'every_tenth_day') {
548
+ if ($method === 'stripe') {
549
+ return [
550
+ 'interval_unit' => 'day',
551
+ 'interval_frequency' => 10
552
+ ];
553
+ }
554
+ if ($method === 'paypal') {
555
+ return [
556
+ 'interval_unit' => 'DAY',
557
+ 'interval_frequency' => 10
558
+ ];
559
+ }
560
+ }
561
+
562
+ return $billingPeriod;
563
+ }, 10, 2);
564
+ ```
565
+
566
+ ---
567
+
568
+ ### `subscription/grace_period_days`
569
+ `fluent_cart/subscription/grace_period_days` — Filter grace period days per billing interval
570
+
571
+ * **When it runs:** Applied when retrieving grace period (extra days after payment fails before subscription marks expired) for each interval.
572
+ * **Source:** `app/Services/Payments/SubscriptionHelper.php` (line 159)
573
+
574
+ #### Parameters:
575
+ * `$gracePeriods` *(array)* — Associative array of interval => days (`daily => 1`, `weekly => 3`, `monthly => 7`, `yearly => 15`)
576
+ * **Returns:** *(array)* — Modified grace period days array
577
+
578
+ #### Usage Example:
579
+ ```php
580
+ // Filter grace period days mapping per subscription billing interval
581
+ add_filter('fluent_cart/subscription/grace_period_days', function($gracePeriods) {
582
+ // Extend yearly subscription grace period to 30 days
583
+ $gracePeriods['yearly'] = 30;
584
+
585
+ // Define 5-day grace period for custom interval
586
+ $gracePeriods['every_tenth_day'] = 5;
587
+
588
+ return $gracePeriods;
589
+ });
590
+ ```
591
+
592
+ ---
593
+
594
+ ## Reminders
595
+
596
+ ### `reminders/scan_batch_size`
597
+ `fluent_cart/reminders/scan_batch_size` — Filter reminder scan batch size
598
+
599
+ * **When it runs:** Applied when automated reminder system scans for subscriptions/invoices needing reminders (default: `100`).
600
+ * **Source:** `app/Services/Reminders/ReminderService.php` (line 75)
601
+
602
+ #### Parameters:
603
+ * `$batchSize` *(int)* — Number of records per scan batch (min: `10`, max: `500`)
604
+ * **Returns:** *(int)* — Modified batch size
605
+
606
+ #### Usage Example:
607
+ ```php
608
+ // Filter scan batch size for automated reminder processing
609
+ add_filter('fluent_cart/reminders/scan_batch_size', function($batchSize) {
610
+ // Increase scan batch size to 250 records for high-volume processing
611
+ return 250;
612
+ });
613
+ ```
614
+
615
+ ---
616
+
617
+ ### `reminders/invoice_due_days`
618
+ `fluent_cart/reminders/invoice_due_days` — Filter invoice due reminder days
619
+
620
+ * **When it runs:** Applied when determining how many days before an invoice is due to send a reminder notification.
621
+ * **Source:** `app/Services/Reminders/InvoiceReminderService.php` (line 288)
622
+
623
+ #### Parameters:
624
+ * `$days` *(int)* — Number of days before due date to send reminder
625
+ * **Returns:** *(int)* — Modified number of days
626
+
627
+ #### Usage Example:
628
+ ```php
629
+ // Filter advance days count for invoice due reminder notifications
630
+ add_filter('fluent_cart/reminders/invoice_due_days', function($days) {
631
+ // Dispatch invoice due reminder 3 days prior to due date
632
+ return 3;
633
+ });
634
+ ```
635
+
636
+ ---
637
+
638
+ ### `reminders/invoice_overdue_days`
639
+ `fluent_cart/reminders/invoice_overdue_days` — Filter overdue invoice reminder intervals
640
+
641
+ * **When it runs:** Applied when determining day intervals after invoice becomes overdue to send follow-up reminders (default: `[1, 3, 7]`).
642
+ * **Source:** `app/Services/Reminders/InvoiceReminderService.php` (line 299)
643
+
644
+ #### Parameters:
645
+ * `$days` *(array)* — Array of day intervals for overdue reminders
646
+ * **Returns:** *(array)* — Modified array of day intervals
647
+
648
+ #### Usage Example:
649
+ ```php
650
+ // Filter day interval schedule for overdue invoice reminders
651
+ add_filter('fluent_cart/reminders/invoice_overdue_days', function($days) {
652
+ // Send overdue follow-up reminders at 1, 3, 7, and 14 days overdue
653
+ return [1, 3, 7, 14];
654
+ });
655
+ ```
656
+
657
+ ---
658
+
659
+ ### `reminders/billing_cycle`
660
+ `fluent_cart/reminders/billing_cycle` — Filter billing cycle name for reminder processing
661
+
662
+ * **When it runs:** Applied when mapping subscription billing interval to cycle identifier used by reminder system.
663
+ * **Source:** `app/Services/Reminders/SubscriptionReminderService.php` (line 502)
664
+
665
+ #### Parameters:
666
+ * `$cycle` *(string)* — Billing cycle name (`monthly`, `yearly`, `unsupported`)
667
+ * `$subscription` *(\FluentCart\App\Models\Subscription)* — Subscription model instance
668
+ * **Returns:** *(string)* — Modified billing cycle name
669
+
670
+ #### Usage Example:
671
+ ```php
672
+ // Filter billing cycle name mapping for subscription reminder logic
673
+ add_filter('fluent_cart/reminders/billing_cycle', function($cycle, $subscription) {
674
+ // Map custom every_tenth_day interval to daily reminder logic
675
+ if ($subscription->billing_interval === 'every_tenth_day') {
676
+ return 'daily';
677
+ }
678
+ return $cycle;
679
+ }, 10, 2);
680
+ ```
681
+
682
+ ---
683
+
684
+ ### `reminders/yearly_before_days`
685
+ `fluent_cart/reminders/yearly_before_days` — Filter days before yearly renewal reminder
686
+
687
+ * **When it runs:** Applied when determining day intervals before yearly subscription renewal to send reminders (default: `[30]`).
688
+ * **Source:** `app/Services/Reminders/SubscriptionReminderService.php` (line 534)
689
+
690
+ #### Parameters:
691
+ * `$days` *(array)* — Array of day intervals before renewal
692
+ * **Returns:** *(array)* — Modified array of day intervals
693
+
694
+ #### Usage Example:
695
+ ```php
696
+ // Filter reminder day intervals prior to yearly subscription renewal
697
+ add_filter('fluent_cart/reminders/yearly_before_days', function($days) {
698
+ // Dispatch yearly renewal reminders at 60, 30, and 7 days prior
699
+ return [60, 30, 7];
700
+ });
701
+ ```
702
+
703
+ ---
704
+
705
+ ### `reminders/monthly_before_days`
706
+ `fluent_cart/reminders/monthly_before_days` — Filter days before monthly renewal reminder
707
+
708
+ * **When it runs:** Applied when determining day intervals before monthly subscription renewal to send reminders (default: `[7]`).
709
+ * **Source:** `app/Services/Reminders/SubscriptionReminderService.php` (line 546)
710
+
711
+ #### Parameters:
712
+ * `$days` *(array)* — Array of day intervals before renewal
713
+ * **Returns:** *(array)* — Modified array of day intervals
714
+
715
+ #### Usage Example:
716
+ ```php
717
+ // Filter reminder day intervals prior to monthly subscription renewal
718
+ add_filter('fluent_cart/reminders/monthly_before_days', function($days) {
719
+ // Dispatch monthly renewal reminders at 7 and 3 days prior
720
+ return [7, 3];
721
+ });
722
+ ```
723
+
724
+ ---
725
+
726
+ ### `reminders/quarterly_before_days`
727
+ `fluent_cart/reminders/quarterly_before_days` — Filter days before quarterly renewal reminder
728
+
729
+ * **When it runs:** Applied when determining day intervals before quarterly subscription renewal to send reminders (default: `[14]`).
730
+ * **Source:** `app/Services/Reminders/SubscriptionReminderService.php` (line 558)
731
+
732
+ #### Parameters:
733
+ * `$days` *(array)* — Array of day intervals before renewal
734
+ * **Returns:** *(array)* — Modified array of day intervals
735
+
736
+ #### Usage Example:
737
+ ```php
738
+ // Filter reminder day intervals prior to quarterly subscription renewal
739
+ add_filter('fluent_cart/reminders/quarterly_before_days', function($days) {
740
+ // Dispatch quarterly renewal reminders at 21 and 7 days prior
741
+ return [21, 7];
742
+ });
743
+ ```
744
+
745
+ ---
746
+
747
+ ### `reminders/half_yearly_before_days`
748
+ `fluent_cart/reminders/half_yearly_before_days` — Filter days before half-yearly renewal reminder
749
+
750
+ * **When it runs:** Applied when determining day intervals before half-yearly subscription renewal to send reminders (default: `[21]`).
751
+ * **Source:** `app/Services/Reminders/SubscriptionReminderService.php` (line 570)
752
+
753
+ #### Parameters:
754
+ * `$days` *(array)* — Array of day intervals before renewal
755
+ * **Returns:** *(array)* — Modified array of day intervals
756
+
757
+ #### Usage Example:
758
+ ```php
759
+ // Filter reminder day intervals prior to half-yearly subscription renewal
760
+ add_filter('fluent_cart/reminders/half_yearly_before_days', function($days) {
761
+ // Dispatch half-yearly renewal reminders at 30 and 7 days prior
762
+ return [30, 7];
763
+ });
764
+ ```
765
+
766
+ ---
767
+
768
+ ### `reminders/trial_end_days`
769
+ `fluent_cart/reminders/trial_end_days` — Filter days before trial end reminder
770
+
771
+ * **When it runs:** Applied when determining day intervals before trial period ends to send reminders (default: `[3]`).
772
+ * **Source:** `app/Services/Reminders/SubscriptionReminderService.php` (line 582)
773
+
774
+ #### Parameters:
775
+ * `$days` *(array)* — Array of day intervals before trial ends
776
+ * **Returns:** *(array)* — Modified array of day intervals
777
+
778
+ #### Usage Example:
779
+ ```php
780
+ // Filter reminder day intervals prior to trial expiration
781
+ add_filter('fluent_cart/reminders/trial_end_days', function($days) {
782
+ // Dispatch trial end reminders at 7, 3, and 1 day before expiration
783
+ return [7, 3, 1];
784
+ });
785
+ ```
786
+
787
+ ---
788
+
789
+ ## Pro: Early Payments & Reactivation
790
+
791
+ ### `subscription/early_payment_enabled` (Pro)
792
+ `fluent_cart/subscription/early_payment_enabled` — Filter whether early installment payments are enabled
793
+
794
+ * **When it runs:** Applied when checking if early payment feature for installment subscriptions is globally enabled. Requires Pro plugin.
795
+ * **Source:** `app/Modules/Subscriptions/Services/EarlyPaymentFeature.php` (line 14)
796
+
797
+ #### Parameters:
798
+ * `$isEnabled` *(bool)* — Whether early payments are enabled from store settings
799
+ * **Returns:** *(bool)* — Modified enabled state
800
+
801
+ #### Usage Example:
802
+ ```php
803
+ // Filter global enabled state for early installment payments (Pro)
804
+ add_filter('fluent_cart/subscription/early_payment_enabled', function($isEnabled) {
805
+ // Disable early payments during December promotion window
806
+ if (current_time('Y-m') === '2026-12') {
807
+ return false;
808
+ }
809
+ return $isEnabled;
810
+ });
811
+ ```
812
+
813
+ ---
814
+
815
+ ### `subscription/can_early_pay` (Pro)
816
+ `fluent_cart/subscription/can_early_pay` — Filter whether a specific subscription can make an early payment
817
+
818
+ * **When it runs:** Applied when checking if a specific installment subscription is eligible for early payment. Requires Pro plugin.
819
+ * **Source:** `app/Modules/Subscriptions/Services/EarlyPaymentFeature.php` (line 26)
820
+
821
+ #### Parameters:
822
+ * `$canPay` *(bool)* — Whether subscription can make early payment
823
+ * `$context` *(array)* — Context data (`['subscription' => Subscription]`)
824
+ * **Returns:** *(bool)* — Modified eligibility
825
+
826
+ #### Usage Example:
827
+ ```php
828
+ // Filter early installment payment eligibility for a subscription (Pro)
829
+ add_filter('fluent_cart/subscription/can_early_pay', function($canPay, $context) {
830
+ $subscription = $context['subscription'];
831
+
832
+ // Require more than 2 remaining installments for early payment
833
+ $remaining = $subscription->bill_times - $subscription->bill_count;
834
+ if ($remaining <= 2) {
835
+ return false;
836
+ }
837
+
838
+ return $canPay;
839
+ }, 10, 2);
840
+ ```
841
+
842
+ ---
843
+
844
+ ### `subscription/reactivation_same_price_days_limit` (Pro)
845
+ `fluent_cart/subscription/reactivation_same_price_days_limit` — Filter days limit for same-price reactivation
846
+
847
+ * **When it runs:** Applied when customer reactivates canceled/expired subscription at original price without new checkout (default: `60` days). Requires Pro.
848
+ * **Source:** `fluent-cart-pro/.../SubscriptionRenewalHandler.php` (line 234)
849
+
850
+ #### Parameters:
851
+ * `$daysLimit` *(int)* — Number of days within which same-price reactivation is allowed (default: `60`)
852
+ * `$context` *(array)* — Context data (`['subscription' => Subscription]`)
853
+ * **Returns:** *(int)* — Modified days limit
854
+
855
+ #### Usage Example:
856
+ ```php
857
+ // Filter maximum days limit allowed for same-price subscription reactivation (Pro)
858
+ add_filter('fluent_cart/subscription/reactivation_same_price_days_limit', function($daysLimit, $context) {
859
+ $subscription = $context['subscription'];
860
+
861
+ // Allow 180 days (6 months) same-price reactivation for yearly subscriptions
862
+ if ($subscription->billing_interval === 'yearly') {
863
+ return 180;
864
+ }
865
+
866
+ return $daysLimit;
867
+ }, 10, 2);
868
+ ```
869
+
870
+ ---
871
+
872
+ ## Pro: License Customer Portal
873
+
874
+ ### `customer/license_details_section_parts` (Pro)
875
+ `fluent_cart/customer/license_details_section_parts` — Filter license details section parts in customer portal
876
+
877
+ * **When it runs:** Applied when rendering license details page in customer portal, allowing HTML section injection. Requires Pro plugin.
878
+ * **Source:** `fluent-cart-pro/.../CustomerProfileController.php` (line 97)
879
+
880
+ #### Parameters:
881
+ * `$sectionParts` *(array)* — Associative array of injectable HTML sections (`before_summary`, `after_summary`, `end_of_details`, `additional_actions`)
882
+ * `$context` *(array)* — Context data (`['license' => License, 'formattedData' => array]`)
883
+ * **Returns:** *(array)* — Modified section parts array
884
+
885
+ #### Usage Example:
886
+ ```php
887
+ // Filter injectable HTML section parts on customer license details page (Pro)
888
+ add_filter('fluent_cart/customer/license_details_section_parts', function($parts, $context) {
889
+ $license = $context['license'];
890
+
891
+ // Inject activation guide HTML section after license summary
892
+ $parts['after_summary'] = '<div class="activation-guide">'
893
+ . '<h4>How to Activate</h4>'
894
+ . '<p>Copy your license key and paste it in your plugin settings.</p>'
895
+ . '</div>';
896
+
897
+ // Inject custom regenerate key action button HTML
898
+ $parts['additional_actions'] = '<button class="btn-regenerate" onclick="regenerateLicense(\'' . $license->id . '\')">Regenerate Key</button>';
899
+
900
+ return $parts;
901
+ }, 10, 2);
902
+ ```