fluentcart-developer 1.1.0 → 1.1.1

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 (65) hide show
  1. package/CLAUDE.md +22 -22
  2. package/LICENSE +21 -21
  3. package/README.md +169 -127
  4. package/SKILL.md +127 -127
  5. package/bin/index.js +281 -281
  6. package/package.json +48 -37
  7. package/skills/fluentcart-developer/SKILL.md +172 -172
  8. package/skills/fluentcart-developer/examples/README.md +25 -25
  9. package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/fluent-cart/checkout.php +32 -32
  10. package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/functions.php +40 -40
  11. package/skills/fluentcart-developer/examples/sample-custom-addon/fluentcart-custom-addon.php +114 -114
  12. package/skills/fluentcart-developer/examples/sample-custom-payment-gateway/fluentcart-custom-gateway-example.php +149 -149
  13. package/skills/fluentcart-developer/examples/sample-fee-surcharge-plugin/fluentcart-fee-surcharge.php +38 -38
  14. package/skills/fluentcart-developer/examples/sample-shipping-carrier/fluentcart-custom-shipping-carrier.php +62 -62
  15. package/skills/fluentcart-developer/references/action-hooks-admin-templates.md +787 -787
  16. package/skills/fluentcart-developer/references/action-hooks-cart-checkout.md +1355 -1355
  17. package/skills/fluentcart-developer/references/action-hooks-customers-users.md +266 -266
  18. package/skills/fluentcart-developer/references/action-hooks-licenses.md +855 -855
  19. package/skills/fluentcart-developer/references/action-hooks-orders.md +631 -631
  20. package/skills/fluentcart-developer/references/action-hooks-payments-integrations.md +963 -963
  21. package/skills/fluentcart-developer/references/action-hooks-products-coupons.md +585 -585
  22. package/skills/fluentcart-developer/references/action-hooks-subscriptions.md +661 -661
  23. package/skills/fluentcart-developer/references/database-models-query-builder.md +194 -194
  24. package/skills/fluentcart-developer/references/database-models-reference.md +604 -604
  25. package/skills/fluentcart-developer/references/database-schema-reference.md +940 -940
  26. package/skills/fluentcart-developer/references/engineering-notes.md +154 -154
  27. package/skills/fluentcart-developer/references/fee-system-guide.md +449 -449
  28. package/skills/fluentcart-developer/references/filter-hooks-cart-checkout.md +1202 -1202
  29. package/skills/fluentcart-developer/references/filter-hooks-customers-subscriptions.md +902 -902
  30. package/skills/fluentcart-developer/references/filter-hooks-integrations-advanced.md +1598 -1598
  31. package/skills/fluentcart-developer/references/filter-hooks-orders-payments.md +1319 -1319
  32. package/skills/fluentcart-developer/references/filter-hooks-products-pricing.md +628 -628
  33. package/skills/fluentcart-developer/references/filter-hooks-settings-configuration.md +1177 -1177
  34. package/skills/fluentcart-developer/references/fluentcart-developer-guide.md +154 -154
  35. package/skills/fluentcart-developer/references/ghost-product-selling.md +458 -458
  36. package/skills/fluentcart-developer/references/modules-and-extensions-reference.md +224 -224
  37. package/skills/fluentcart-developer/references/payment-gateway-integration.md +761 -761
  38. package/skills/fluentcart-developer/references/rest-api-checkout.md +286 -286
  39. package/skills/fluentcart-developer/references/rest-api-coupons.md +794 -794
  40. package/skills/fluentcart-developer/references/rest-api-customer-profile.md +190 -190
  41. package/skills/fluentcart-developer/references/rest-api-customers.md +1121 -1121
  42. package/skills/fluentcart-developer/references/rest-api-dashboard-utilities.md +219 -219
  43. package/skills/fluentcart-developer/references/rest-api-email-notifications.md +619 -619
  44. package/skills/fluentcart-developer/references/rest-api-files.md +290 -290
  45. package/skills/fluentcart-developer/references/rest-api-integrations.md +324 -324
  46. package/skills/fluentcart-developer/references/rest-api-labels-attributes.md +321 -321
  47. package/skills/fluentcart-developer/references/rest-api-licensing.md +171 -171
  48. package/skills/fluentcart-developer/references/rest-api-order-bumps.md +200 -200
  49. package/skills/fluentcart-developer/references/rest-api-orders.md +1241 -1241
  50. package/skills/fluentcart-developer/references/rest-api-overview.md +131 -131
  51. package/skills/fluentcart-developer/references/rest-api-products.md +2563 -2563
  52. package/skills/fluentcart-developer/references/rest-api-public-shop.md +172 -172
  53. package/skills/fluentcart-developer/references/rest-api-reference.md +552 -552
  54. package/skills/fluentcart-developer/references/rest-api-reports.md +377 -377
  55. package/skills/fluentcart-developer/references/rest-api-roles-permissions.md +147 -147
  56. package/skills/fluentcart-developer/references/rest-api-settings.md +528 -528
  57. package/skills/fluentcart-developer/references/rest-api-shipping.md +799 -799
  58. package/skills/fluentcart-developer/references/rest-api-subscriptions.md +606 -606
  59. package/skills/fluentcart-developer/references/rest-api-tax.md +356 -356
  60. package/skills/fluentcart-developer/references/subscription-customization.md +197 -197
  61. package/skills/fluentcart-developer/scripts/cli.js +1 -1
  62. package/.gitattributes +0 -2
  63. package/CONTRIBUTING.md +0 -73
  64. package/copy-skills.js +0 -43
  65. package/skills.sh.json +0 -13
@@ -1,661 +1,661 @@
1
- # Action Hooks: Subscriptions
2
-
3
- Action hooks for Subscription lifecycle management, status transitions, and scheduled reminder notifications. These hooks let you react to subscription state changes, send custom notifications, and integrate with external systems. Most hooks pass the related Order and Customer models as well.
4
-
5
- ---
6
-
7
- ## Subscription Status Changes
8
-
9
- ### `subscription_status_changed`
10
- `fluent_cart/payments/subscription_status_changed` — Fires on any subscription status transition
11
-
12
- * **When it runs:** This action fires whenever a Subscription's status changes from one value to another (e.g., `pending` to `active`, `active` to `cancelled`, etc.). It does not fire when other subscription data changes without a status transition. This is the generic handler -- for status-specific hooks, see status-specific hooks below.
13
- * **Source:** `app/Modules/Subscriptions/Services/SubscriptionService.php`
14
-
15
- #### Parameters:
16
- `$data` *(array)*: Subscription status change data
17
- ```php
18
- $data = [
19
- 'subscription' => $subscriptionModel, // \FluentCart\App\Models\Subscription
20
- 'order' => $subscriptionModel->order, // \FluentCart\App\Models\Order
21
- 'customer' => $subscriptionModel->customer,// \FluentCart\App\Models\Customer
22
- 'old_status' => 'pending', // string — previous status
23
- 'new_status' => 'active', // string — current status after update
24
- ];
25
- ```
26
-
27
- #### Usage Example:
28
- ```php
29
- // Hook into any subscription status change
30
- add_action('fluent_cart/payments/subscription_status_changed', function ($data) {
31
- // Extract subscription model and status values
32
- $subscription = $data['subscription'];
33
- $oldStatus = $data['old_status'];
34
- $newStatus = $data['new_status'];
35
-
36
- // Log every status transition into FluentCart logs
37
- fluent_cart_add_log(
38
- 'Subscription Status Changed',
39
- sprintf('Subscription #%d changed from %s to %s', $subscription->id, $oldStatus, $newStatus),
40
- 'info'
41
- );
42
- }, 10, 1);
43
- ```
44
-
45
- ---
46
-
47
- ### `subscription_active`
48
- `fluent_cart/payments/subscription_active` — Fires when a subscription becomes active
49
-
50
- * **When it runs:** This action fires when a subscription's status transitions to `active`. This may occur after initial payment, after reactivation, or when moving from trialing to active.
51
- * **Source:** `app/Modules/Subscriptions/Services/SubscriptionService.php`
52
-
53
- #### Parameters:
54
- `$data` *(array)*: Subscription data
55
- ```php
56
- $data = [
57
- 'subscription' => $subscriptionModel, // \FluentCart\App\Models\Subscription
58
- 'order' => $subscriptionModel->order, // \FluentCart\App\Models\Order
59
- 'customer' => $subscriptionModel->customer,// \FluentCart\App\Models\Customer
60
- 'old_status' => 'pending', // string — previous status
61
- 'new_status' => 'active', // string — always 'active'
62
- ];
63
- ```
64
-
65
- #### Usage Example:
66
- ```php
67
- // Hook when a subscription becomes active
68
- add_action('fluent_cart/payments/subscription_active', function ($data) {
69
- // Extract customer model from event data
70
- $customer = $data['customer'];
71
-
72
- // Grant premium access when subscription activates
73
- update_user_meta($customer->user_id, 'premium_member', true);
74
- }, 10, 1);
75
- ```
76
-
77
- ---
78
-
79
- ### `subscription_canceled`
80
- `fluent_cart/payments/subscription_canceled` — Fires when a subscription is cancelled
81
-
82
- * **When it runs:** This action fires when a subscription's status transitions to `canceled`. The `canceled_at` timestamp is automatically set if not already provided.
83
- * **Source:** `app/Modules/Subscriptions/Services/SubscriptionService.php`
84
-
85
- #### Parameters:
86
- `$data` *(array)*: Subscription data
87
- ```php
88
- $data = [
89
- 'subscription' => $subscriptionModel, // \FluentCart\App\Models\Subscription
90
- 'order' => $subscriptionModel->order, // \FluentCart\App\Models\Order
91
- 'customer' => $subscriptionModel->customer,// \FluentCart\App\Models\Customer
92
- 'old_status' => 'active', // string — previous status
93
- 'new_status' => 'canceled', // string — always 'canceled'
94
- ];
95
- ```
96
-
97
- #### Usage Example:
98
- ```php
99
- // Hook when a subscription is cancelled
100
- add_action('fluent_cart/payments/subscription_canceled', function ($data) {
101
- // Extract subscription and customer models from event data
102
- $subscription = $data['subscription'];
103
- $customer = $data['customer'];
104
-
105
- // Revoke premium access on cancellation
106
- update_user_meta($customer->user_id, 'premium_member', false);
107
-
108
- // Notify store administrator via email
109
- wp_mail(
110
- get_option('admin_email'),
111
- 'Subscription Cancelled',
112
- sprintf('Subscription #%d for %s has been cancelled.', $subscription->id, $customer->email)
113
- );
114
- }, 10, 1);
115
- ```
116
-
117
- ---
118
-
119
- ### `subscription_paused`
120
- `fluent_cart/payments/subscription_paused` — Fires when a subscription is paused
121
-
122
- * **When it runs:** This action fires when a subscription's status transitions to `paused`. The subscription remains in the system but billing is temporarily halted.
123
- * **Source:** `app/Modules/Subscriptions/Services/SubscriptionService.php`
124
-
125
- #### Parameters:
126
- `$data` *(array)*: Subscription data
127
- ```php
128
- $data = [
129
- 'subscription' => $subscriptionModel, // \FluentCart\App\Models\Subscription
130
- 'order' => $subscriptionModel->order, // \FluentCart\App\Models\Order
131
- 'customer' => $subscriptionModel->customer,// \FluentCart\App\Models\Customer
132
- 'old_status' => 'active', // string — previous status
133
- 'new_status' => 'paused', // string — always 'paused'
134
- ];
135
- ```
136
-
137
- #### Usage Example:
138
- ```php
139
- // Hook when a subscription is paused
140
- add_action('fluent_cart/payments/subscription_paused', function ($data) {
141
- // Extract subscription model from event data
142
- $subscription = $data['subscription'];
143
-
144
- // Temporarily suspend feature access for paused customer
145
- update_user_meta($data['customer']->user_id, 'subscription_paused', true);
146
- }, 10, 1);
147
- ```
148
-
149
- ---
150
-
151
- ### `subscription_expired`
152
- `fluent_cart/payments/subscription_expired` — Fires when a subscription expires
153
-
154
- * **When it runs:** This action fires when a subscription's status transitions to `expired`. After this hook fires, the system also stores a `validity_expired_at` meta value and dispatches the `SubscriptionValidityExpired` event.
155
- * **Source:** `app/Modules/Subscriptions/Services/SubscriptionService.php`
156
-
157
- #### Parameters:
158
- `$data` *(array)*: Subscription data
159
- ```php
160
- $data = [
161
- 'subscription' => $subscriptionModel, // \FluentCart\App\Models\Subscription
162
- 'order' => $subscriptionModel->order, // \FluentCart\App\Models\Order
163
- 'customer' => $subscriptionModel->customer,// \FluentCart\App\Models\Customer
164
- 'old_status' => 'active', // string — previous status
165
- 'new_status' => 'expired', // string — always 'expired'
166
- ];
167
- ```
168
-
169
- #### Usage Example:
170
- ```php
171
- // Hook when a subscription expires
172
- add_action('fluent_cart/payments/subscription_expired', function ($data) {
173
- // Extract customer model from event data
174
- $customer = $data['customer'];
175
-
176
- // Remove premium access from customer user account
177
- update_user_meta($customer->user_id, 'premium_member', false);
178
-
179
- // Send expiration notification email to the customer
180
- wp_mail(
181
- $customer->email,
182
- 'Your Subscription Has Expired',
183
- 'Your subscription has expired. Please renew to continue using premium features.'
184
- );
185
- }, 10, 1);
186
- ```
187
-
188
- ---
189
-
190
- ### `subscription_failing`
191
- `fluent_cart/payments/subscription_failing` — Fires when a subscription payment is failing
192
-
193
- * **When it runs:** This action fires when a subscription's status transitions to `failing`, indicating that a renewal payment attempt has failed. The subscription is still technically active but requires payment attention.
194
- * **Source:** `app/Modules/Subscriptions/Services/SubscriptionService.php`
195
-
196
- #### Parameters:
197
- `$data` *(array)*: Subscription data
198
- ```php
199
- $data = [
200
- 'subscription' => $subscriptionModel, // \FluentCart\App\Models\Subscription
201
- 'order' => $subscriptionModel->order, // \FluentCart\App\Models\Order
202
- 'customer' => $subscriptionModel->customer,// \FluentCart\App\Models\Customer
203
- 'old_status' => 'active', // string — previous status
204
- 'new_status' => 'failing', // string — always 'failing'
205
- ];
206
- ```
207
-
208
- #### Usage Example:
209
- ```php
210
- // Hook when a subscription renewal payment is failing
211
- add_action('fluent_cart/payments/subscription_failing', function ($data) {
212
- // Extract subscription and customer models from event data
213
- $subscription = $data['subscription'];
214
- $customer = $data['customer'];
215
-
216
- // Alert the customer about the payment failure via email
217
- wp_mail(
218
- $customer->email,
219
- 'Payment Failed for Your Subscription',
220
- sprintf('We were unable to process payment for subscription #%d. Please update your payment method.', $subscription->id)
221
- );
222
- }, 10, 1);
223
- ```
224
-
225
- ---
226
-
227
- ### `subscription_expiring`
228
- `fluent_cart/payments/subscription_expiring` — Fires when a subscription is marked as expiring soon
229
-
230
- * **When it runs:** This action fires when a subscription's status transitions to `expiring`, indicating that the subscription is approaching its end-of-term and will not be renewed.
231
- * **Source:** `app/Modules/Subscriptions/Services/SubscriptionService.php`
232
-
233
- #### Parameters:
234
- `$data` *(array)*: Subscription data
235
- ```php
236
- $data = [
237
- 'subscription' => $subscriptionModel, // \FluentCart\App\Models\Subscription
238
- 'order' => $subscriptionModel->order, // \FluentCart\App\Models\Order
239
- 'customer' => $subscriptionModel->customer,// \FluentCart\App\Models\Customer
240
- 'old_status' => 'active', // string — previous status
241
- 'new_status' => 'expiring', // string — always 'expiring'
242
- ];
243
- ```
244
-
245
- #### Usage Example:
246
- ```php
247
- // Hook when a subscription is marked as expiring soon
248
- add_action('fluent_cart/payments/subscription_expiring', function ($data) {
249
- // Extract subscription and customer models from event data
250
- $subscription = $data['subscription'];
251
- $customer = $data['customer'];
252
-
253
- // Send a win-back offer email before subscription fully expires
254
- wp_mail(
255
- $customer->email,
256
- 'Your Subscription is About to Expire',
257
- 'Renew now and get 10% off your next billing cycle!'
258
- );
259
- }, 10, 1);
260
- ```
261
-
262
- ---
263
-
264
- ### `subscription_completed`
265
- `fluent_cart/payments/subscription_completed` — Fires when a subscription completes all billing cycles
266
-
267
- * **When it runs:** This action fires when a subscription's status transitions to `completed`. This occurs when the subscription has reached its end-of-term (EOT) -- i.e., the `bill_count` has met or exceeded `bill_times`. The `next_billing_date` is set to `NULL` and `canceled_at` is cleared.
268
- * **Source:** `app/Modules/Subscriptions/Services/SubscriptionService.php`
269
-
270
- #### Parameters:
271
- `$data` *(array)*: Subscription data
272
- ```php
273
- $data = [
274
- 'subscription' => $subscriptionModel, // \FluentCart\App\Models\Subscription
275
- 'order' => $subscriptionModel->order, // \FluentCart\App\Models\Order
276
- 'customer' => $subscriptionModel->customer,// \FluentCart\App\Models\Customer
277
- 'old_status' => 'active', // string — previous status
278
- 'new_status' => 'completed', // string — always 'completed'
279
- ];
280
- ```
281
-
282
- #### Usage Example:
283
- ```php
284
- // Hook when a subscription completes all required billing cycles
285
- add_action('fluent_cart/payments/subscription_completed', function ($data) {
286
- // Extract subscription and customer models from event data
287
- $subscription = $data['subscription'];
288
- $customer = $data['customer'];
289
-
290
- // Thank the customer for completing their full subscription term
291
- wp_mail(
292
- $customer->email,
293
- 'Subscription Complete',
294
- sprintf('Your subscription #%d has completed all %d billing cycles. Thank you!', $subscription->id, $subscription->bill_times)
295
- );
296
- }, 10, 1);
297
- ```
298
-
299
- ---
300
-
301
- ### `subscription_trialing`
302
- `fluent_cart/payments/subscription_trialing` — Fires when a subscription enters trial status
303
-
304
- * **When it runs:** This action fires when a subscription's status transitions to `trialing`. The subscription is in a free trial period and will transition to `active` (with billing) when the trial ends.
305
- * **Source:** `app/Modules/Subscriptions/Services/SubscriptionService.php`
306
-
307
- #### Parameters:
308
- `$data` *(array)*: Subscription data
309
- ```php
310
- $data = [
311
- 'subscription' => $subscriptionModel, // \FluentCart\App\Models\Subscription
312
- 'order' => $subscriptionModel->order, // \FluentCart\App\Models\Order
313
- 'customer' => $subscriptionModel->customer,// \FluentCart\App\Models\Customer
314
- 'old_status' => 'pending', // string — previous status
315
- 'new_status' => 'trialing', // string — always 'trialing'
316
- ];
317
- ```
318
-
319
- #### Usage Example:
320
- ```php
321
- // Hook when a subscription enters trial status
322
- add_action('fluent_cart/payments/subscription_trialing', function ($data) {
323
- // Extract subscription and customer models from event data
324
- $subscription = $data['subscription'];
325
- $customer = $data['customer'];
326
-
327
- // Grant trial access to customer account
328
- update_user_meta($customer->user_id, 'trial_active', true);
329
-
330
- // Send trial welcome email to customer
331
- wp_mail(
332
- $customer->email,
333
- 'Your Free Trial Has Started',
334
- sprintf('Enjoy your trial! Your first payment will be on %s.', $subscription->next_billing_date)
335
- );
336
- }, 10, 1);
337
- ```
338
-
339
- ---
340
-
341
- ## Subscription Data Updates
342
-
343
- ### `subscription_data_updated`
344
- `fluent_cart/subscription/data_updated` — Fires when subscription data changes without a status transition
345
-
346
- * **When it runs:** This action fires when Subscription attributes are modified but the status remains the same. Examples include billing amount changes, next payment date adjustments, or metadata updates. It only fires when there are actual dirty (changed) fields on the model.
347
- * **Source:** `app/Modules/Subscriptions/Services/SubscriptionService.php`
348
-
349
- #### Parameters:
350
- `$data` *(array)*: Subscription update data
351
- ```php
352
- $data = [
353
- 'subscription' => $subscriptionModel, // \FluentCart\App\Models\Subscription (already saved)
354
- 'updated_data' => [
355
- // Only the fields that actually changed (dirty attributes), e.g.:
356
- 'recurring_total' => 2999, // int — new amount in cents
357
- 'next_billing_date' => '2025-03-15 00:00:00', // string — updated billing date
358
- ],
359
- ];
360
- ```
361
-
362
- #### Usage Example:
363
- ```php
364
- // Hook when subscription data changes without a status transition
365
- add_action('fluent_cart/subscription/data_updated', function ($data) {
366
- // Extract subscription model and modified attributes map
367
- $subscription = $data['subscription'];
368
- $updatedData = $data['updated_data'];
369
-
370
- // Log billing amount changes if total was modified
371
- if (isset($updatedData['recurring_total'])) {
372
- fluent_cart_add_log(
373
- 'Subscription Amount Changed',
374
- sprintf(
375
- 'Subscription #%d recurring total changed to %s',
376
- $subscription->id,
377
- number_format($updatedData['recurring_total'] / 100, 2)
378
- ),
379
- 'info'
380
- );
381
- }
382
-
383
- // Sync next billing date with external calendar if modified
384
- if (isset($updatedData['next_billing_date'])) {
385
- do_action('my_plugin/sync_billing_date', $subscription->id, $updatedData['next_billing_date']);
386
- }
387
- }, 10, 1);
388
- ```
389
-
390
- ---
391
-
392
- ## Reminders & Notifications
393
-
394
- ### `subscription_renewal_reminder`
395
- `fluent_cart/subscription_renewal_reminder` — Fires when a subscription renewal reminder is due
396
-
397
- * **When it runs:** This action fires on a scheduled basis (via Action Scheduler) when a subscription's next billing date is approaching. The reminder system supports multiple billing cycles (`yearly`, `monthly`, `quarterly`, `half_yearly`) and configurable "days before" thresholds. Only fires for subscriptions with `active` or `trialing` status. The stage name indicates how many days before renewal (e.g., `before_30`, `before_7`).
398
- * **Source:** `app/Services/Reminders/SubscriptionReminderService.php`
399
-
400
- #### Parameters:
401
- `$data` *(array)*: Renewal reminder data
402
- ```php
403
- $data = [
404
- 'subscription' => $subscription, // \FluentCart\App\Models\Subscription
405
- 'order' => $subscription->order, // \FluentCart\App\Models\Order
406
- 'customer' => $subscription->customer, // \FluentCart\App\Models\Customer
407
- 'reminder' => [
408
- 'stage' => 'before_30', // string — e.g., 'before_30', 'before_7'
409
- 'billing_cycle' => 'yearly', // string — 'yearly', 'monthly', 'quarterly', 'half_yearly'
410
- 'billing_date' => '2025-03-15 00:00:00', // string — GMT formatted next billing date
411
- ],
412
- ];
413
- ```
414
-
415
- #### Usage Example:
416
- ```php
417
- // Hook when a scheduled subscription renewal reminder is due
418
- add_action('fluent_cart/subscription_renewal_reminder', function ($data) {
419
- // Extract subscription, customer, and reminder metadata
420
- $subscription = $data['subscription'];
421
- $customer = $data['customer'];
422
- $reminder = $data['reminder'];
423
-
424
- // Send a custom renewal reminder email to the subscriber
425
- wp_mail(
426
- $customer->email,
427
- 'Subscription Renewal Coming Up',
428
- sprintf(
429
- 'Your %s subscription #%d will renew on %s.',
430
- $reminder['billing_cycle'],
431
- $subscription->id,
432
- date('F j, Y', strtotime($reminder['billing_date']))
433
- )
434
- );
435
- }, 10, 1);
436
- ```
437
-
438
- ---
439
-
440
- ### `subscription_trial_end_reminder`
441
- `fluent_cart/subscription_trial_end_reminder` — Fires when a trial ending reminder is due
442
-
443
- * **When it runs:** This action fires on a scheduled basis when a trialing subscription's trial period is about to end. Only fires for subscriptions with `trialing` status (excluding simulated trials). The stage name indicates how many days before the trial ends (e.g., `trial_end_3`, `trial_end_1`). Configurable via the `trial_end_reminder_days` store setting.
444
- * **Source:** `app/Services/Reminders/SubscriptionReminderService.php`
445
-
446
- #### Parameters:
447
- `$data` *(array)*: Trial end reminder data
448
- ```php
449
- $data = [
450
- 'subscription' => $subscription, // \FluentCart\App\Models\Subscription
451
- 'order' => $subscription->order, // \FluentCart\App\Models\Order
452
- 'customer' => $subscription->customer, // \FluentCart\App\Models\Customer
453
- 'reminder' => [
454
- 'stage' => 'trial_end_3', // string — e.g., 'trial_end_3', 'trial_end_1'
455
- 'trial_end_date' => '2025-02-01 00:00:00',// string — GMT formatted trial end date
456
- ],
457
- ];
458
- ```
459
-
460
- #### Usage Example:
461
- ```php
462
- // Hook when a trial ending reminder is due
463
- add_action('fluent_cart/subscription_trial_end_reminder', function ($data) {
464
- // Extract subscription, customer, and reminder metadata
465
- $subscription = $data['subscription'];
466
- $customer = $data['customer'];
467
- $reminder = $data['reminder'];
468
-
469
- // Notify customer that their trial is ending soon via email
470
- wp_mail(
471
- $customer->email,
472
- 'Your Free Trial is Ending Soon',
473
- sprintf(
474
- 'Your trial for subscription #%d ends on %s. After that, you will be billed %s.',
475
- $subscription->id,
476
- date('F j, Y', strtotime($reminder['trial_end_date'])),
477
- number_format($subscription->recurring_total / 100, 2)
478
- )
479
- );
480
- }, 10, 1);
481
- ```
482
-
483
- ---
484
-
485
- ### `invoice_reminder_overdue`
486
- `fluent_cart/invoice_reminder_overdue` — Fires when an overdue invoice reminder is triggered
487
-
488
- * **When it runs:** This action fires on a scheduled basis when an Order with an outstanding balance has passed its due date by a configured number of days. The stage name indicates how many days overdue (e.g., `overdue_1`, `overdue_3`, `overdue_7`). Only fires for orders with `pending`, `partially_paid`, `failed`, or `authorized` payment statuses. The overdue days are configurable via the `invoice_reminder_overdue_days` store setting (defaults to `1,3,7`).
489
- * **Source:** `app/Services/Reminders/InvoiceReminderService.php`
490
-
491
- #### Parameters:
492
- `$data` *(array)*: Invoice overdue reminder data
493
- ```php
494
- $data = [
495
- 'order' => $order, // \FluentCart\App\Models\Order
496
- 'customer' => $order->customer, // \FluentCart\App\Models\Customer
497
- 'reminder' => [
498
- 'stage' => 'overdue_3', // string — e.g., 'overdue_1', 'overdue_3', 'overdue_7'
499
- 'order_id' => 123, // int — order ID
500
- 'order_ref' => 'INV-00123', // string — invoice number or '#123' fallback
501
- 'due_at' => '2025-01-15 00:00:00', // string — GMT formatted due date
502
- 'due_amount' => 5000, // int — outstanding amount in cents
503
- 'payment_link' => 'https://example.com/checkout/pay/uuid', // string — customer payment URL
504
- ],
505
- ];
506
- ```
507
-
508
- #### Usage Example:
509
- ```php
510
- // Hook when an overdue invoice reminder is triggered
511
- add_action('fluent_cart/invoice_reminder_overdue', function ($data) {
512
- // Extract order, customer, and overdue reminder details
513
- $order = $data['order'];
514
- $customer = $data['customer'];
515
- $reminder = $data['reminder'];
516
-
517
- // Send a payment reminder with a direct payment link
518
- wp_mail(
519
- $customer->email,
520
- sprintf('Payment Overdue for %s', $reminder['order_ref']),
521
- sprintf(
522
- "Your payment of %s for order %s is overdue.\n\nPay now: %s",
523
- number_format($reminder['due_amount'] / 100, 2),
524
- $reminder['order_ref'],
525
- $reminder['payment_link']
526
- )
527
- );
528
- }, 10, 1);
529
- ```
530
-
531
- ---
532
-
533
- ### `invoice_reminder_due`
534
- `fluent_cart/invoice_reminder_due` — Fires when an invoice due-date reminder is triggered
535
-
536
- * **When it runs:** This action fires on a scheduled basis when an order with an outstanding balance has reached its due date (stage `before_0`). This is the on-due-date notification, as opposed to the overdue reminders that fire after the due date has passed. Shares the same parameter structure as the overdue reminder.
537
- * **Note:** This hook is currently defined in the codebase but the queueing logic for the `before_0` stage is commented out pending the full invoice feature deployment. It is documented here for forward compatibility.
538
- * **Source:** `app/Services/Reminders/InvoiceReminderService.php`
539
-
540
- #### Parameters:
541
- `$data` *(array)*: Invoice due reminder data
542
- ```php
543
- $data = [
544
- 'order' => $order, // \FluentCart\App\Models\Order
545
- 'customer' => $order->customer, // \FluentCart\App\Models\Customer
546
- 'reminder' => [
547
- 'stage' => 'before_0', // string — always 'before_0' for due-date reminders
548
- 'order_id' => 123, // int — order ID
549
- 'order_ref' => 'INV-00123', // string — invoice number or '#123' fallback
550
- 'due_at' => '2025-01-15 00:00:00', // string — GMT formatted due date
551
- 'due_amount' => 5000, // int — outstanding amount in cents
552
- 'payment_link' => 'https://example.com/checkout/pay/uuid', // string — customer payment URL
553
- ],
554
- ];
555
- ```
556
-
557
- #### Usage Example:
558
- ```php
559
- // Hook when an invoice due-date reminder is triggered
560
- add_action('fluent_cart/invoice_reminder_due', function ($data) {
561
- // Extract order, customer, and due reminder details
562
- $order = $data['order'];
563
- $customer = $data['customer'];
564
- $reminder = $data['reminder'];
565
-
566
- // Notify customer that their invoice is due today via email
567
- wp_mail(
568
- $customer->email,
569
- sprintf('Payment Due Today for %s', $reminder['order_ref']),
570
- sprintf(
571
- "Your payment of %s for order %s is due today.\n\nPay now: %s",
572
- number_format($reminder['due_amount'] / 100, 2),
573
- $reminder['order_ref'],
574
- $reminder['payment_link']
575
- )
576
- );
577
- }, 10, 1);
578
- ```
579
-
580
- ---
581
-
582
- ## Subscription Upgrades & Early Payments (Pro)
583
-
584
- ### `early_payment_completed` (Pro)
585
- `fluent_cart/subscription/early_payment_completed` — Fires when an early installment payment is completed
586
-
587
- * **When it runs:** This action fires when a customer makes an early installment payment on their subscription, paying for one or more future billing cycles ahead of schedule.
588
- * **Source:** `fluent-cart-pro/app/Hooks/Handlers/EarlyInstallmentPaymentHandler.php` (line 279)
589
-
590
- #### Parameters:
591
- `$data` *(array)*: Early payment completion data
592
- ```php
593
- $data = [
594
- 'subscription' => $subscription, // \FluentCart\App\Models\Subscription
595
- 'order' => $order, // \FluentCart\App\Models\Order
596
- 'installment_count' => $installmentCount, // int — number of installments paid early
597
- ];
598
- ```
599
-
600
- #### Usage Example:
601
- ```php
602
- // Hook when an early installment payment is completed (Pro extension)
603
- add_action('fluent_cart/subscription/early_payment_completed', function ($data) {
604
- // Extract subscription, order, and installment count details
605
- $subscription = $data['subscription'];
606
- $order = $data['order'];
607
- $installmentCount = $data['installment_count'];
608
-
609
- // Log early installment payment event
610
- fluent_cart_add_log(
611
- 'Early Payment Completed',
612
- sprintf('Subscription #%d received %d early installment(s) via order #%d', $subscription->id, $installmentCount, $order->id),
613
- 'info'
614
- );
615
- }, 10, 1);
616
- ```
617
-
618
- ---
619
-
620
- ### `order_upgraded` (Pro)
621
- `fluent_cart/order/upgraded` — Fires when a plan upgrade is completed
622
-
623
- * **When it runs:** This action fires when a customer completes a plan upgrade, transitioning from one product variant to another. The upgrade creates a new order and transaction record.
624
- * **Source:** `fluent-cart-pro/app/Hooks/Handlers/UpgradeHandler.php` (line 242)
625
-
626
- #### Parameters:
627
- `$data` *(array)*: Upgrade completion data
628
- ```php
629
- $data = [
630
- 'order' => $newOrder, // \FluentCart\App\Models\Order — the new upgrade order
631
- 'from_order' => $upgradeFromOrder, // \FluentCart\App\Models\Order — the original order
632
- 'cart' => $cartModel, // \FluentCart\App\Models\Cart — the cart used for the upgrade
633
- 'from_variant_id' => $fromVariantId, // int — ID of the original product variant
634
- 'transaction' => $transaction, // \FluentCart\App\Models\OrderTransaction — the upgrade payment transaction
635
- ];
636
- ```
637
-
638
- #### Usage Example:
639
- ```php
640
- // Hook when a plan upgrade is completed (Pro extension)
641
- add_action('fluent_cart/order/upgraded', function ($data) {
642
- // Extract upgraded order models and payment transaction
643
- $order = $data['order'];
644
- $fromOrder = $data['from_order'];
645
- $fromVariantId = $data['from_variant_id'];
646
- $transaction = $data['transaction'];
647
-
648
- // Log plan upgrade event
649
- fluent_cart_add_log(
650
- 'Plan Upgraded',
651
- sprintf(
652
- 'Order #%d upgraded from order #%d (variant %d). Transaction: %s',
653
- $order->id,
654
- $fromOrder->id,
655
- $fromVariantId,
656
- $transaction->charge_id
657
- ),
658
- 'info'
659
- );
660
- }, 10, 1);
661
- ```
1
+ # Action Hooks: Subscriptions
2
+
3
+ Action hooks for Subscription lifecycle management, status transitions, and scheduled reminder notifications. These hooks let you react to subscription state changes, send custom notifications, and integrate with external systems. Most hooks pass the related Order and Customer models as well.
4
+
5
+ ---
6
+
7
+ ## Subscription Status Changes
8
+
9
+ ### `subscription_status_changed`
10
+ `fluent_cart/payments/subscription_status_changed` — Fires on any subscription status transition
11
+
12
+ * **When it runs:** This action fires whenever a Subscription's status changes from one value to another (e.g., `pending` to `active`, `active` to `cancelled`, etc.). It does not fire when other subscription data changes without a status transition. This is the generic handler -- for status-specific hooks, see status-specific hooks below.
13
+ * **Source:** `app/Modules/Subscriptions/Services/SubscriptionService.php`
14
+
15
+ #### Parameters:
16
+ `$data` *(array)*: Subscription status change data
17
+ ```php
18
+ $data = [
19
+ 'subscription' => $subscriptionModel, // \FluentCart\App\Models\Subscription
20
+ 'order' => $subscriptionModel->order, // \FluentCart\App\Models\Order
21
+ 'customer' => $subscriptionModel->customer,// \FluentCart\App\Models\Customer
22
+ 'old_status' => 'pending', // string — previous status
23
+ 'new_status' => 'active', // string — current status after update
24
+ ];
25
+ ```
26
+
27
+ #### Usage Example:
28
+ ```php
29
+ // Hook into any subscription status change
30
+ add_action('fluent_cart/payments/subscription_status_changed', function ($data) {
31
+ // Extract subscription model and status values
32
+ $subscription = $data['subscription'];
33
+ $oldStatus = $data['old_status'];
34
+ $newStatus = $data['new_status'];
35
+
36
+ // Log every status transition into FluentCart logs
37
+ fluent_cart_add_log(
38
+ 'Subscription Status Changed',
39
+ sprintf('Subscription #%d changed from %s to %s', $subscription->id, $oldStatus, $newStatus),
40
+ 'info'
41
+ );
42
+ }, 10, 1);
43
+ ```
44
+
45
+ ---
46
+
47
+ ### `subscription_active`
48
+ `fluent_cart/payments/subscription_active` — Fires when a subscription becomes active
49
+
50
+ * **When it runs:** This action fires when a subscription's status transitions to `active`. This may occur after initial payment, after reactivation, or when moving from trialing to active.
51
+ * **Source:** `app/Modules/Subscriptions/Services/SubscriptionService.php`
52
+
53
+ #### Parameters:
54
+ `$data` *(array)*: Subscription data
55
+ ```php
56
+ $data = [
57
+ 'subscription' => $subscriptionModel, // \FluentCart\App\Models\Subscription
58
+ 'order' => $subscriptionModel->order, // \FluentCart\App\Models\Order
59
+ 'customer' => $subscriptionModel->customer,// \FluentCart\App\Models\Customer
60
+ 'old_status' => 'pending', // string — previous status
61
+ 'new_status' => 'active', // string — always 'active'
62
+ ];
63
+ ```
64
+
65
+ #### Usage Example:
66
+ ```php
67
+ // Hook when a subscription becomes active
68
+ add_action('fluent_cart/payments/subscription_active', function ($data) {
69
+ // Extract customer model from event data
70
+ $customer = $data['customer'];
71
+
72
+ // Grant premium access when subscription activates
73
+ update_user_meta($customer->user_id, 'premium_member', true);
74
+ }, 10, 1);
75
+ ```
76
+
77
+ ---
78
+
79
+ ### `subscription_canceled`
80
+ `fluent_cart/payments/subscription_canceled` — Fires when a subscription is cancelled
81
+
82
+ * **When it runs:** This action fires when a subscription's status transitions to `canceled`. The `canceled_at` timestamp is automatically set if not already provided.
83
+ * **Source:** `app/Modules/Subscriptions/Services/SubscriptionService.php`
84
+
85
+ #### Parameters:
86
+ `$data` *(array)*: Subscription data
87
+ ```php
88
+ $data = [
89
+ 'subscription' => $subscriptionModel, // \FluentCart\App\Models\Subscription
90
+ 'order' => $subscriptionModel->order, // \FluentCart\App\Models\Order
91
+ 'customer' => $subscriptionModel->customer,// \FluentCart\App\Models\Customer
92
+ 'old_status' => 'active', // string — previous status
93
+ 'new_status' => 'canceled', // string — always 'canceled'
94
+ ];
95
+ ```
96
+
97
+ #### Usage Example:
98
+ ```php
99
+ // Hook when a subscription is cancelled
100
+ add_action('fluent_cart/payments/subscription_canceled', function ($data) {
101
+ // Extract subscription and customer models from event data
102
+ $subscription = $data['subscription'];
103
+ $customer = $data['customer'];
104
+
105
+ // Revoke premium access on cancellation
106
+ update_user_meta($customer->user_id, 'premium_member', false);
107
+
108
+ // Notify store administrator via email
109
+ wp_mail(
110
+ get_option('admin_email'),
111
+ 'Subscription Cancelled',
112
+ sprintf('Subscription #%d for %s has been cancelled.', $subscription->id, $customer->email)
113
+ );
114
+ }, 10, 1);
115
+ ```
116
+
117
+ ---
118
+
119
+ ### `subscription_paused`
120
+ `fluent_cart/payments/subscription_paused` — Fires when a subscription is paused
121
+
122
+ * **When it runs:** This action fires when a subscription's status transitions to `paused`. The subscription remains in the system but billing is temporarily halted.
123
+ * **Source:** `app/Modules/Subscriptions/Services/SubscriptionService.php`
124
+
125
+ #### Parameters:
126
+ `$data` *(array)*: Subscription data
127
+ ```php
128
+ $data = [
129
+ 'subscription' => $subscriptionModel, // \FluentCart\App\Models\Subscription
130
+ 'order' => $subscriptionModel->order, // \FluentCart\App\Models\Order
131
+ 'customer' => $subscriptionModel->customer,// \FluentCart\App\Models\Customer
132
+ 'old_status' => 'active', // string — previous status
133
+ 'new_status' => 'paused', // string — always 'paused'
134
+ ];
135
+ ```
136
+
137
+ #### Usage Example:
138
+ ```php
139
+ // Hook when a subscription is paused
140
+ add_action('fluent_cart/payments/subscription_paused', function ($data) {
141
+ // Extract subscription model from event data
142
+ $subscription = $data['subscription'];
143
+
144
+ // Temporarily suspend feature access for paused customer
145
+ update_user_meta($data['customer']->user_id, 'subscription_paused', true);
146
+ }, 10, 1);
147
+ ```
148
+
149
+ ---
150
+
151
+ ### `subscription_expired`
152
+ `fluent_cart/payments/subscription_expired` — Fires when a subscription expires
153
+
154
+ * **When it runs:** This action fires when a subscription's status transitions to `expired`. After this hook fires, the system also stores a `validity_expired_at` meta value and dispatches the `SubscriptionValidityExpired` event.
155
+ * **Source:** `app/Modules/Subscriptions/Services/SubscriptionService.php`
156
+
157
+ #### Parameters:
158
+ `$data` *(array)*: Subscription data
159
+ ```php
160
+ $data = [
161
+ 'subscription' => $subscriptionModel, // \FluentCart\App\Models\Subscription
162
+ 'order' => $subscriptionModel->order, // \FluentCart\App\Models\Order
163
+ 'customer' => $subscriptionModel->customer,// \FluentCart\App\Models\Customer
164
+ 'old_status' => 'active', // string — previous status
165
+ 'new_status' => 'expired', // string — always 'expired'
166
+ ];
167
+ ```
168
+
169
+ #### Usage Example:
170
+ ```php
171
+ // Hook when a subscription expires
172
+ add_action('fluent_cart/payments/subscription_expired', function ($data) {
173
+ // Extract customer model from event data
174
+ $customer = $data['customer'];
175
+
176
+ // Remove premium access from customer user account
177
+ update_user_meta($customer->user_id, 'premium_member', false);
178
+
179
+ // Send expiration notification email to the customer
180
+ wp_mail(
181
+ $customer->email,
182
+ 'Your Subscription Has Expired',
183
+ 'Your subscription has expired. Please renew to continue using premium features.'
184
+ );
185
+ }, 10, 1);
186
+ ```
187
+
188
+ ---
189
+
190
+ ### `subscription_failing`
191
+ `fluent_cart/payments/subscription_failing` — Fires when a subscription payment is failing
192
+
193
+ * **When it runs:** This action fires when a subscription's status transitions to `failing`, indicating that a renewal payment attempt has failed. The subscription is still technically active but requires payment attention.
194
+ * **Source:** `app/Modules/Subscriptions/Services/SubscriptionService.php`
195
+
196
+ #### Parameters:
197
+ `$data` *(array)*: Subscription data
198
+ ```php
199
+ $data = [
200
+ 'subscription' => $subscriptionModel, // \FluentCart\App\Models\Subscription
201
+ 'order' => $subscriptionModel->order, // \FluentCart\App\Models\Order
202
+ 'customer' => $subscriptionModel->customer,// \FluentCart\App\Models\Customer
203
+ 'old_status' => 'active', // string — previous status
204
+ 'new_status' => 'failing', // string — always 'failing'
205
+ ];
206
+ ```
207
+
208
+ #### Usage Example:
209
+ ```php
210
+ // Hook when a subscription renewal payment is failing
211
+ add_action('fluent_cart/payments/subscription_failing', function ($data) {
212
+ // Extract subscription and customer models from event data
213
+ $subscription = $data['subscription'];
214
+ $customer = $data['customer'];
215
+
216
+ // Alert the customer about the payment failure via email
217
+ wp_mail(
218
+ $customer->email,
219
+ 'Payment Failed for Your Subscription',
220
+ sprintf('We were unable to process payment for subscription #%d. Please update your payment method.', $subscription->id)
221
+ );
222
+ }, 10, 1);
223
+ ```
224
+
225
+ ---
226
+
227
+ ### `subscription_expiring`
228
+ `fluent_cart/payments/subscription_expiring` — Fires when a subscription is marked as expiring soon
229
+
230
+ * **When it runs:** This action fires when a subscription's status transitions to `expiring`, indicating that the subscription is approaching its end-of-term and will not be renewed.
231
+ * **Source:** `app/Modules/Subscriptions/Services/SubscriptionService.php`
232
+
233
+ #### Parameters:
234
+ `$data` *(array)*: Subscription data
235
+ ```php
236
+ $data = [
237
+ 'subscription' => $subscriptionModel, // \FluentCart\App\Models\Subscription
238
+ 'order' => $subscriptionModel->order, // \FluentCart\App\Models\Order
239
+ 'customer' => $subscriptionModel->customer,// \FluentCart\App\Models\Customer
240
+ 'old_status' => 'active', // string — previous status
241
+ 'new_status' => 'expiring', // string — always 'expiring'
242
+ ];
243
+ ```
244
+
245
+ #### Usage Example:
246
+ ```php
247
+ // Hook when a subscription is marked as expiring soon
248
+ add_action('fluent_cart/payments/subscription_expiring', function ($data) {
249
+ // Extract subscription and customer models from event data
250
+ $subscription = $data['subscription'];
251
+ $customer = $data['customer'];
252
+
253
+ // Send a win-back offer email before subscription fully expires
254
+ wp_mail(
255
+ $customer->email,
256
+ 'Your Subscription is About to Expire',
257
+ 'Renew now and get 10% off your next billing cycle!'
258
+ );
259
+ }, 10, 1);
260
+ ```
261
+
262
+ ---
263
+
264
+ ### `subscription_completed`
265
+ `fluent_cart/payments/subscription_completed` — Fires when a subscription completes all billing cycles
266
+
267
+ * **When it runs:** This action fires when a subscription's status transitions to `completed`. This occurs when the subscription has reached its end-of-term (EOT) -- i.e., the `bill_count` has met or exceeded `bill_times`. The `next_billing_date` is set to `NULL` and `canceled_at` is cleared.
268
+ * **Source:** `app/Modules/Subscriptions/Services/SubscriptionService.php`
269
+
270
+ #### Parameters:
271
+ `$data` *(array)*: Subscription data
272
+ ```php
273
+ $data = [
274
+ 'subscription' => $subscriptionModel, // \FluentCart\App\Models\Subscription
275
+ 'order' => $subscriptionModel->order, // \FluentCart\App\Models\Order
276
+ 'customer' => $subscriptionModel->customer,// \FluentCart\App\Models\Customer
277
+ 'old_status' => 'active', // string — previous status
278
+ 'new_status' => 'completed', // string — always 'completed'
279
+ ];
280
+ ```
281
+
282
+ #### Usage Example:
283
+ ```php
284
+ // Hook when a subscription completes all required billing cycles
285
+ add_action('fluent_cart/payments/subscription_completed', function ($data) {
286
+ // Extract subscription and customer models from event data
287
+ $subscription = $data['subscription'];
288
+ $customer = $data['customer'];
289
+
290
+ // Thank the customer for completing their full subscription term
291
+ wp_mail(
292
+ $customer->email,
293
+ 'Subscription Complete',
294
+ sprintf('Your subscription #%d has completed all %d billing cycles. Thank you!', $subscription->id, $subscription->bill_times)
295
+ );
296
+ }, 10, 1);
297
+ ```
298
+
299
+ ---
300
+
301
+ ### `subscription_trialing`
302
+ `fluent_cart/payments/subscription_trialing` — Fires when a subscription enters trial status
303
+
304
+ * **When it runs:** This action fires when a subscription's status transitions to `trialing`. The subscription is in a free trial period and will transition to `active` (with billing) when the trial ends.
305
+ * **Source:** `app/Modules/Subscriptions/Services/SubscriptionService.php`
306
+
307
+ #### Parameters:
308
+ `$data` *(array)*: Subscription data
309
+ ```php
310
+ $data = [
311
+ 'subscription' => $subscriptionModel, // \FluentCart\App\Models\Subscription
312
+ 'order' => $subscriptionModel->order, // \FluentCart\App\Models\Order
313
+ 'customer' => $subscriptionModel->customer,// \FluentCart\App\Models\Customer
314
+ 'old_status' => 'pending', // string — previous status
315
+ 'new_status' => 'trialing', // string — always 'trialing'
316
+ ];
317
+ ```
318
+
319
+ #### Usage Example:
320
+ ```php
321
+ // Hook when a subscription enters trial status
322
+ add_action('fluent_cart/payments/subscription_trialing', function ($data) {
323
+ // Extract subscription and customer models from event data
324
+ $subscription = $data['subscription'];
325
+ $customer = $data['customer'];
326
+
327
+ // Grant trial access to customer account
328
+ update_user_meta($customer->user_id, 'trial_active', true);
329
+
330
+ // Send trial welcome email to customer
331
+ wp_mail(
332
+ $customer->email,
333
+ 'Your Free Trial Has Started',
334
+ sprintf('Enjoy your trial! Your first payment will be on %s.', $subscription->next_billing_date)
335
+ );
336
+ }, 10, 1);
337
+ ```
338
+
339
+ ---
340
+
341
+ ## Subscription Data Updates
342
+
343
+ ### `subscription_data_updated`
344
+ `fluent_cart/subscription/data_updated` — Fires when subscription data changes without a status transition
345
+
346
+ * **When it runs:** This action fires when Subscription attributes are modified but the status remains the same. Examples include billing amount changes, next payment date adjustments, or metadata updates. It only fires when there are actual dirty (changed) fields on the model.
347
+ * **Source:** `app/Modules/Subscriptions/Services/SubscriptionService.php`
348
+
349
+ #### Parameters:
350
+ `$data` *(array)*: Subscription update data
351
+ ```php
352
+ $data = [
353
+ 'subscription' => $subscriptionModel, // \FluentCart\App\Models\Subscription (already saved)
354
+ 'updated_data' => [
355
+ // Only the fields that actually changed (dirty attributes), e.g.:
356
+ 'recurring_total' => 2999, // int — new amount in cents
357
+ 'next_billing_date' => '2025-03-15 00:00:00', // string — updated billing date
358
+ ],
359
+ ];
360
+ ```
361
+
362
+ #### Usage Example:
363
+ ```php
364
+ // Hook when subscription data changes without a status transition
365
+ add_action('fluent_cart/subscription/data_updated', function ($data) {
366
+ // Extract subscription model and modified attributes map
367
+ $subscription = $data['subscription'];
368
+ $updatedData = $data['updated_data'];
369
+
370
+ // Log billing amount changes if total was modified
371
+ if (isset($updatedData['recurring_total'])) {
372
+ fluent_cart_add_log(
373
+ 'Subscription Amount Changed',
374
+ sprintf(
375
+ 'Subscription #%d recurring total changed to %s',
376
+ $subscription->id,
377
+ number_format($updatedData['recurring_total'] / 100, 2)
378
+ ),
379
+ 'info'
380
+ );
381
+ }
382
+
383
+ // Sync next billing date with external calendar if modified
384
+ if (isset($updatedData['next_billing_date'])) {
385
+ do_action('my_plugin/sync_billing_date', $subscription->id, $updatedData['next_billing_date']);
386
+ }
387
+ }, 10, 1);
388
+ ```
389
+
390
+ ---
391
+
392
+ ## Reminders & Notifications
393
+
394
+ ### `subscription_renewal_reminder`
395
+ `fluent_cart/subscription_renewal_reminder` — Fires when a subscription renewal reminder is due
396
+
397
+ * **When it runs:** This action fires on a scheduled basis (via Action Scheduler) when a subscription's next billing date is approaching. The reminder system supports multiple billing cycles (`yearly`, `monthly`, `quarterly`, `half_yearly`) and configurable "days before" thresholds. Only fires for subscriptions with `active` or `trialing` status. The stage name indicates how many days before renewal (e.g., `before_30`, `before_7`).
398
+ * **Source:** `app/Services/Reminders/SubscriptionReminderService.php`
399
+
400
+ #### Parameters:
401
+ `$data` *(array)*: Renewal reminder data
402
+ ```php
403
+ $data = [
404
+ 'subscription' => $subscription, // \FluentCart\App\Models\Subscription
405
+ 'order' => $subscription->order, // \FluentCart\App\Models\Order
406
+ 'customer' => $subscription->customer, // \FluentCart\App\Models\Customer
407
+ 'reminder' => [
408
+ 'stage' => 'before_30', // string — e.g., 'before_30', 'before_7'
409
+ 'billing_cycle' => 'yearly', // string — 'yearly', 'monthly', 'quarterly', 'half_yearly'
410
+ 'billing_date' => '2025-03-15 00:00:00', // string — GMT formatted next billing date
411
+ ],
412
+ ];
413
+ ```
414
+
415
+ #### Usage Example:
416
+ ```php
417
+ // Hook when a scheduled subscription renewal reminder is due
418
+ add_action('fluent_cart/subscription_renewal_reminder', function ($data) {
419
+ // Extract subscription, customer, and reminder metadata
420
+ $subscription = $data['subscription'];
421
+ $customer = $data['customer'];
422
+ $reminder = $data['reminder'];
423
+
424
+ // Send a custom renewal reminder email to the subscriber
425
+ wp_mail(
426
+ $customer->email,
427
+ 'Subscription Renewal Coming Up',
428
+ sprintf(
429
+ 'Your %s subscription #%d will renew on %s.',
430
+ $reminder['billing_cycle'],
431
+ $subscription->id,
432
+ date('F j, Y', strtotime($reminder['billing_date']))
433
+ )
434
+ );
435
+ }, 10, 1);
436
+ ```
437
+
438
+ ---
439
+
440
+ ### `subscription_trial_end_reminder`
441
+ `fluent_cart/subscription_trial_end_reminder` — Fires when a trial ending reminder is due
442
+
443
+ * **When it runs:** This action fires on a scheduled basis when a trialing subscription's trial period is about to end. Only fires for subscriptions with `trialing` status (excluding simulated trials). The stage name indicates how many days before the trial ends (e.g., `trial_end_3`, `trial_end_1`). Configurable via the `trial_end_reminder_days` store setting.
444
+ * **Source:** `app/Services/Reminders/SubscriptionReminderService.php`
445
+
446
+ #### Parameters:
447
+ `$data` *(array)*: Trial end reminder data
448
+ ```php
449
+ $data = [
450
+ 'subscription' => $subscription, // \FluentCart\App\Models\Subscription
451
+ 'order' => $subscription->order, // \FluentCart\App\Models\Order
452
+ 'customer' => $subscription->customer, // \FluentCart\App\Models\Customer
453
+ 'reminder' => [
454
+ 'stage' => 'trial_end_3', // string — e.g., 'trial_end_3', 'trial_end_1'
455
+ 'trial_end_date' => '2025-02-01 00:00:00',// string — GMT formatted trial end date
456
+ ],
457
+ ];
458
+ ```
459
+
460
+ #### Usage Example:
461
+ ```php
462
+ // Hook when a trial ending reminder is due
463
+ add_action('fluent_cart/subscription_trial_end_reminder', function ($data) {
464
+ // Extract subscription, customer, and reminder metadata
465
+ $subscription = $data['subscription'];
466
+ $customer = $data['customer'];
467
+ $reminder = $data['reminder'];
468
+
469
+ // Notify customer that their trial is ending soon via email
470
+ wp_mail(
471
+ $customer->email,
472
+ 'Your Free Trial is Ending Soon',
473
+ sprintf(
474
+ 'Your trial for subscription #%d ends on %s. After that, you will be billed %s.',
475
+ $subscription->id,
476
+ date('F j, Y', strtotime($reminder['trial_end_date'])),
477
+ number_format($subscription->recurring_total / 100, 2)
478
+ )
479
+ );
480
+ }, 10, 1);
481
+ ```
482
+
483
+ ---
484
+
485
+ ### `invoice_reminder_overdue`
486
+ `fluent_cart/invoice_reminder_overdue` — Fires when an overdue invoice reminder is triggered
487
+
488
+ * **When it runs:** This action fires on a scheduled basis when an Order with an outstanding balance has passed its due date by a configured number of days. The stage name indicates how many days overdue (e.g., `overdue_1`, `overdue_3`, `overdue_7`). Only fires for orders with `pending`, `partially_paid`, `failed`, or `authorized` payment statuses. The overdue days are configurable via the `invoice_reminder_overdue_days` store setting (defaults to `1,3,7`).
489
+ * **Source:** `app/Services/Reminders/InvoiceReminderService.php`
490
+
491
+ #### Parameters:
492
+ `$data` *(array)*: Invoice overdue reminder data
493
+ ```php
494
+ $data = [
495
+ 'order' => $order, // \FluentCart\App\Models\Order
496
+ 'customer' => $order->customer, // \FluentCart\App\Models\Customer
497
+ 'reminder' => [
498
+ 'stage' => 'overdue_3', // string — e.g., 'overdue_1', 'overdue_3', 'overdue_7'
499
+ 'order_id' => 123, // int — order ID
500
+ 'order_ref' => 'INV-00123', // string — invoice number or '#123' fallback
501
+ 'due_at' => '2025-01-15 00:00:00', // string — GMT formatted due date
502
+ 'due_amount' => 5000, // int — outstanding amount in cents
503
+ 'payment_link' => 'https://example.com/checkout/pay/uuid', // string — customer payment URL
504
+ ],
505
+ ];
506
+ ```
507
+
508
+ #### Usage Example:
509
+ ```php
510
+ // Hook when an overdue invoice reminder is triggered
511
+ add_action('fluent_cart/invoice_reminder_overdue', function ($data) {
512
+ // Extract order, customer, and overdue reminder details
513
+ $order = $data['order'];
514
+ $customer = $data['customer'];
515
+ $reminder = $data['reminder'];
516
+
517
+ // Send a payment reminder with a direct payment link
518
+ wp_mail(
519
+ $customer->email,
520
+ sprintf('Payment Overdue for %s', $reminder['order_ref']),
521
+ sprintf(
522
+ "Your payment of %s for order %s is overdue.\n\nPay now: %s",
523
+ number_format($reminder['due_amount'] / 100, 2),
524
+ $reminder['order_ref'],
525
+ $reminder['payment_link']
526
+ )
527
+ );
528
+ }, 10, 1);
529
+ ```
530
+
531
+ ---
532
+
533
+ ### `invoice_reminder_due`
534
+ `fluent_cart/invoice_reminder_due` — Fires when an invoice due-date reminder is triggered
535
+
536
+ * **When it runs:** This action fires on a scheduled basis when an order with an outstanding balance has reached its due date (stage `before_0`). This is the on-due-date notification, as opposed to the overdue reminders that fire after the due date has passed. Shares the same parameter structure as the overdue reminder.
537
+ * **Note:** This hook is currently defined in the codebase but the queueing logic for the `before_0` stage is commented out pending the full invoice feature deployment. It is documented here for forward compatibility.
538
+ * **Source:** `app/Services/Reminders/InvoiceReminderService.php`
539
+
540
+ #### Parameters:
541
+ `$data` *(array)*: Invoice due reminder data
542
+ ```php
543
+ $data = [
544
+ 'order' => $order, // \FluentCart\App\Models\Order
545
+ 'customer' => $order->customer, // \FluentCart\App\Models\Customer
546
+ 'reminder' => [
547
+ 'stage' => 'before_0', // string — always 'before_0' for due-date reminders
548
+ 'order_id' => 123, // int — order ID
549
+ 'order_ref' => 'INV-00123', // string — invoice number or '#123' fallback
550
+ 'due_at' => '2025-01-15 00:00:00', // string — GMT formatted due date
551
+ 'due_amount' => 5000, // int — outstanding amount in cents
552
+ 'payment_link' => 'https://example.com/checkout/pay/uuid', // string — customer payment URL
553
+ ],
554
+ ];
555
+ ```
556
+
557
+ #### Usage Example:
558
+ ```php
559
+ // Hook when an invoice due-date reminder is triggered
560
+ add_action('fluent_cart/invoice_reminder_due', function ($data) {
561
+ // Extract order, customer, and due reminder details
562
+ $order = $data['order'];
563
+ $customer = $data['customer'];
564
+ $reminder = $data['reminder'];
565
+
566
+ // Notify customer that their invoice is due today via email
567
+ wp_mail(
568
+ $customer->email,
569
+ sprintf('Payment Due Today for %s', $reminder['order_ref']),
570
+ sprintf(
571
+ "Your payment of %s for order %s is due today.\n\nPay now: %s",
572
+ number_format($reminder['due_amount'] / 100, 2),
573
+ $reminder['order_ref'],
574
+ $reminder['payment_link']
575
+ )
576
+ );
577
+ }, 10, 1);
578
+ ```
579
+
580
+ ---
581
+
582
+ ## Subscription Upgrades & Early Payments (Pro)
583
+
584
+ ### `early_payment_completed` (Pro)
585
+ `fluent_cart/subscription/early_payment_completed` — Fires when an early installment payment is completed
586
+
587
+ * **When it runs:** This action fires when a customer makes an early installment payment on their subscription, paying for one or more future billing cycles ahead of schedule.
588
+ * **Source:** `fluent-cart-pro/app/Hooks/Handlers/EarlyInstallmentPaymentHandler.php` (line 279)
589
+
590
+ #### Parameters:
591
+ `$data` *(array)*: Early payment completion data
592
+ ```php
593
+ $data = [
594
+ 'subscription' => $subscription, // \FluentCart\App\Models\Subscription
595
+ 'order' => $order, // \FluentCart\App\Models\Order
596
+ 'installment_count' => $installmentCount, // int — number of installments paid early
597
+ ];
598
+ ```
599
+
600
+ #### Usage Example:
601
+ ```php
602
+ // Hook when an early installment payment is completed (Pro extension)
603
+ add_action('fluent_cart/subscription/early_payment_completed', function ($data) {
604
+ // Extract subscription, order, and installment count details
605
+ $subscription = $data['subscription'];
606
+ $order = $data['order'];
607
+ $installmentCount = $data['installment_count'];
608
+
609
+ // Log early installment payment event
610
+ fluent_cart_add_log(
611
+ 'Early Payment Completed',
612
+ sprintf('Subscription #%d received %d early installment(s) via order #%d', $subscription->id, $installmentCount, $order->id),
613
+ 'info'
614
+ );
615
+ }, 10, 1);
616
+ ```
617
+
618
+ ---
619
+
620
+ ### `order_upgraded` (Pro)
621
+ `fluent_cart/order/upgraded` — Fires when a plan upgrade is completed
622
+
623
+ * **When it runs:** This action fires when a customer completes a plan upgrade, transitioning from one product variant to another. The upgrade creates a new order and transaction record.
624
+ * **Source:** `fluent-cart-pro/app/Hooks/Handlers/UpgradeHandler.php` (line 242)
625
+
626
+ #### Parameters:
627
+ `$data` *(array)*: Upgrade completion data
628
+ ```php
629
+ $data = [
630
+ 'order' => $newOrder, // \FluentCart\App\Models\Order — the new upgrade order
631
+ 'from_order' => $upgradeFromOrder, // \FluentCart\App\Models\Order — the original order
632
+ 'cart' => $cartModel, // \FluentCart\App\Models\Cart — the cart used for the upgrade
633
+ 'from_variant_id' => $fromVariantId, // int — ID of the original product variant
634
+ 'transaction' => $transaction, // \FluentCart\App\Models\OrderTransaction — the upgrade payment transaction
635
+ ];
636
+ ```
637
+
638
+ #### Usage Example:
639
+ ```php
640
+ // Hook when a plan upgrade is completed (Pro extension)
641
+ add_action('fluent_cart/order/upgraded', function ($data) {
642
+ // Extract upgraded order models and payment transaction
643
+ $order = $data['order'];
644
+ $fromOrder = $data['from_order'];
645
+ $fromVariantId = $data['from_variant_id'];
646
+ $transaction = $data['transaction'];
647
+
648
+ // Log plan upgrade event
649
+ fluent_cart_add_log(
650
+ 'Plan Upgraded',
651
+ sprintf(
652
+ 'Order #%d upgraded from order #%d (variant %d). Transaction: %s',
653
+ $order->id,
654
+ $fromOrder->id,
655
+ $fromVariantId,
656
+ $transaction->charge_id
657
+ ),
658
+ 'info'
659
+ );
660
+ }, 10, 1);
661
+ ```