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.
- package/CLAUDE.md +22 -22
- package/LICENSE +21 -21
- package/README.md +169 -127
- package/SKILL.md +127 -127
- package/bin/index.js +281 -281
- package/package.json +48 -37
- package/skills/fluentcart-developer/SKILL.md +172 -172
- package/skills/fluentcart-developer/examples/README.md +25 -25
- package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/fluent-cart/checkout.php +32 -32
- package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/functions.php +40 -40
- package/skills/fluentcart-developer/examples/sample-custom-addon/fluentcart-custom-addon.php +114 -114
- package/skills/fluentcart-developer/examples/sample-custom-payment-gateway/fluentcart-custom-gateway-example.php +149 -149
- package/skills/fluentcart-developer/examples/sample-fee-surcharge-plugin/fluentcart-fee-surcharge.php +38 -38
- package/skills/fluentcart-developer/examples/sample-shipping-carrier/fluentcart-custom-shipping-carrier.php +62 -62
- package/skills/fluentcart-developer/references/action-hooks-admin-templates.md +787 -787
- package/skills/fluentcart-developer/references/action-hooks-cart-checkout.md +1355 -1355
- package/skills/fluentcart-developer/references/action-hooks-customers-users.md +266 -266
- package/skills/fluentcart-developer/references/action-hooks-licenses.md +855 -855
- package/skills/fluentcart-developer/references/action-hooks-orders.md +631 -631
- package/skills/fluentcart-developer/references/action-hooks-payments-integrations.md +963 -963
- package/skills/fluentcart-developer/references/action-hooks-products-coupons.md +585 -585
- package/skills/fluentcart-developer/references/action-hooks-subscriptions.md +661 -661
- package/skills/fluentcart-developer/references/database-models-query-builder.md +194 -194
- package/skills/fluentcart-developer/references/database-models-reference.md +604 -604
- package/skills/fluentcart-developer/references/database-schema-reference.md +940 -940
- package/skills/fluentcart-developer/references/engineering-notes.md +154 -154
- package/skills/fluentcart-developer/references/fee-system-guide.md +449 -449
- package/skills/fluentcart-developer/references/filter-hooks-cart-checkout.md +1202 -1202
- package/skills/fluentcart-developer/references/filter-hooks-customers-subscriptions.md +902 -902
- package/skills/fluentcart-developer/references/filter-hooks-integrations-advanced.md +1598 -1598
- package/skills/fluentcart-developer/references/filter-hooks-orders-payments.md +1319 -1319
- package/skills/fluentcart-developer/references/filter-hooks-products-pricing.md +628 -628
- package/skills/fluentcart-developer/references/filter-hooks-settings-configuration.md +1177 -1177
- package/skills/fluentcart-developer/references/fluentcart-developer-guide.md +154 -154
- package/skills/fluentcart-developer/references/ghost-product-selling.md +458 -458
- package/skills/fluentcart-developer/references/modules-and-extensions-reference.md +224 -224
- package/skills/fluentcart-developer/references/payment-gateway-integration.md +761 -761
- package/skills/fluentcart-developer/references/rest-api-checkout.md +286 -286
- package/skills/fluentcart-developer/references/rest-api-coupons.md +794 -794
- package/skills/fluentcart-developer/references/rest-api-customer-profile.md +190 -190
- package/skills/fluentcart-developer/references/rest-api-customers.md +1121 -1121
- package/skills/fluentcart-developer/references/rest-api-dashboard-utilities.md +219 -219
- package/skills/fluentcart-developer/references/rest-api-email-notifications.md +619 -619
- package/skills/fluentcart-developer/references/rest-api-files.md +290 -290
- package/skills/fluentcart-developer/references/rest-api-integrations.md +324 -324
- package/skills/fluentcart-developer/references/rest-api-labels-attributes.md +321 -321
- package/skills/fluentcart-developer/references/rest-api-licensing.md +171 -171
- package/skills/fluentcart-developer/references/rest-api-order-bumps.md +200 -200
- package/skills/fluentcart-developer/references/rest-api-orders.md +1241 -1241
- package/skills/fluentcart-developer/references/rest-api-overview.md +131 -131
- package/skills/fluentcart-developer/references/rest-api-products.md +2563 -2563
- package/skills/fluentcart-developer/references/rest-api-public-shop.md +172 -172
- package/skills/fluentcart-developer/references/rest-api-reference.md +552 -552
- package/skills/fluentcart-developer/references/rest-api-reports.md +377 -377
- package/skills/fluentcart-developer/references/rest-api-roles-permissions.md +147 -147
- package/skills/fluentcart-developer/references/rest-api-settings.md +528 -528
- package/skills/fluentcart-developer/references/rest-api-shipping.md +799 -799
- package/skills/fluentcart-developer/references/rest-api-subscriptions.md +606 -606
- package/skills/fluentcart-developer/references/rest-api-tax.md +356 -356
- package/skills/fluentcart-developer/references/subscription-customization.md +197 -197
- package/skills/fluentcart-developer/scripts/cli.js +1 -1
- package/.gitattributes +0 -2
- package/CONTRIBUTING.md +0 -73
- package/copy-skills.js +0 -43
- 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
|
+
```
|