fluentcart-developer 2.0.2 → 2.3.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/README.md +59 -59
- package/dist/cards/fluentcart/tools.d.ts.map +1 -1
- package/dist/cards/fluentcart/tools.js +184 -18
- package/dist/cards/fluentcart/tools.js.map +1 -1
- package/dist/skills/fluentcart-developer/.claude-plugin/plugin.json +12 -12
- package/dist/skills/fluentcart-developer/.mcp.json +11 -11
- package/dist/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/fluent-cart/checkout.php +32 -32
- package/dist/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/functions.php +40 -40
- package/dist/skills/fluentcart-developer/examples/sample-fee-surcharge-plugin/fluentcart-fee-surcharge.php +38 -38
- package/dist/skills/fluentcart-developer/references/action-hooks-cart-checkout.md +1355 -1355
- package/dist/skills/fluentcart-developer/references/action-hooks-customers-users.md +266 -266
- package/dist/skills/fluentcart-developer/references/action-hooks-licenses.md +855 -855
- package/dist/skills/fluentcart-developer/references/action-hooks-orders.md +631 -631
- package/dist/skills/fluentcart-developer/references/action-hooks-payments-integrations.md +963 -963
- package/dist/skills/fluentcart-developer/references/action-hooks-products-coupons.md +585 -585
- package/dist/skills/fluentcart-developer/references/action-hooks-subscriptions.md +661 -661
- package/dist/skills/fluentcart-developer/references/database-models-query-builder.md +194 -194
- package/dist/skills/fluentcart-developer/references/database-models-reference.md +604 -604
- package/dist/skills/fluentcart-developer/references/engineering-notes.md +154 -154
- package/dist/skills/fluentcart-developer/references/fee-system-guide.md +449 -449
- package/dist/skills/fluentcart-developer/references/filter-hooks-cart-checkout.md +1202 -1202
- package/dist/skills/fluentcart-developer/references/filter-hooks-integrations-advanced.md +1598 -1598
- package/dist/skills/fluentcart-developer/references/filter-hooks-products-pricing.md +628 -628
- package/dist/skills/fluentcart-developer/references/filter-hooks-settings-configuration.md +1177 -1177
- package/dist/skills/fluentcart-developer/references/fluentcart-developer-guide.md +154 -154
- package/dist/skills/fluentcart-developer/references/ghost-product-selling.md +458 -458
- package/dist/skills/fluentcart-developer/references/modules-and-extensions-reference.md +224 -224
- package/dist/skills/fluentcart-developer/references/payment-gateway-integration.md +761 -761
- package/dist/skills/fluentcart-developer/references/rest-api-customer-profile.md +190 -190
- package/dist/skills/fluentcart-developer/references/rest-api-customers.md +1121 -1121
- package/dist/skills/fluentcart-developer/references/rest-api-dashboard-utilities.md +219 -219
- package/dist/skills/fluentcart-developer/references/rest-api-email-notifications.md +619 -619
- package/dist/skills/fluentcart-developer/references/rest-api-files.md +290 -290
- package/dist/skills/fluentcart-developer/references/rest-api-integrations.md +324 -324
- package/dist/skills/fluentcart-developer/references/rest-api-labels-attributes.md +321 -321
- package/dist/skills/fluentcart-developer/references/rest-api-order-bumps.md +200 -200
- package/dist/skills/fluentcart-developer/references/rest-api-overview.md +131 -131
- package/dist/skills/fluentcart-developer/references/rest-api-public-shop.md +172 -172
- package/dist/skills/fluentcart-developer/references/rest-api-reference.md +552 -552
- package/dist/skills/fluentcart-developer/references/rest-api-reports.md +377 -377
- package/dist/skills/fluentcart-developer/references/rest-api-roles-permissions.md +147 -147
- package/dist/skills/fluentcart-developer/references/rest-api-settings.md +528 -528
- package/dist/skills/fluentcart-developer/references/rest-api-shipping.md +799 -799
- package/dist/skills/fluentcart-developer/references/rest-api-tax.md +356 -356
- package/dist/skills/fluentcart-developer/references/subscription-customization.md +197 -197
- package/dist/skills/fluentcart-developer/scripts/cli.js +1 -1
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/package.json +65 -65
- package/dist/skills/fluentcart-developer/references/client-integration-contract.md +0 -299
- package/dist/skills/fluentcart-developer/references/device-licensing-and-hardware-tracking.md +0 -241
- package/dist/skills/fluentcart-developer/references/trial-abuse-prevention.md +0 -304
|
@@ -1,631 +1,631 @@
|
|
|
1
|
-
# Action Hooks: Orders
|
|
2
|
-
|
|
3
|
-
All hooks related to order lifecycle, status transitions, payments, shipping, refunds, and order items. These action hooks allow you to respond to key order events in FluentCart.
|
|
4
|
-
|
|
5
|
-
Each hook passes an associative array as its single parameter. The order value is always an `\FluentCart\App\Models\Order` model instance with the `customer`, `shipping_address`, and `billing_address` relationships eager-loaded (unless noted otherwise).
|
|
6
|
-
|
|
7
|
-
Amounts are in cents. All monetary values (`total`, `refunded_amount`, etc.) are stored as integers in the smallest currency unit. Use `Helper::toDecimal($amount)` to convert for display.
|
|
8
|
-
|
|
9
|
-
---
|
|
10
|
-
|
|
11
|
-
## Order Status Changes
|
|
12
|
-
Fired when the order status field changes (e.g. `processing` → `completed`). Both a dynamic, status-specific hook and a generic hook fire on every change.
|
|
13
|
-
|
|
14
|
-
### `order_status_changed_to_{status}`
|
|
15
|
-
`fluent_cart/order_status_changed_to_{$newStatus}` — Fires when the order status changes to a specific status
|
|
16
|
-
|
|
17
|
-
* **When it runs:** Fires inside `OrderStatusUpdated::afterDispatch()` whenever the order status type transitions to a new value. The `{$newStatus}` portion is replaced dynamically with the target status, so you can listen for a single status you care about.
|
|
18
|
-
* **Available dynamic variants:** `completed`, `canceled`, `processing`, `on-hold`, `failed`
|
|
19
|
-
* **Source:** `app/Events/Order/OrderStatusUpdated.php` (line 91)
|
|
20
|
-
|
|
21
|
-
#### Parameters:
|
|
22
|
-
`$data` *(array)*: Order status change data
|
|
23
|
-
```php
|
|
24
|
-
$data = [
|
|
25
|
-
'order' => $order, // \FluentCart\App\Models\Order (with customer, addresses loaded)
|
|
26
|
-
'old_status' => 'processing', // Previous order status string
|
|
27
|
-
'new_status' => 'completed', // New order status string (matches the dynamic suffix)
|
|
28
|
-
'manageStock' => true, // Whether stock management should be applied
|
|
29
|
-
'activity' => [ // Optional activity log context
|
|
30
|
-
'title' => '',
|
|
31
|
-
'content' => '',
|
|
32
|
-
],
|
|
33
|
-
];
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
#### Usage Example:
|
|
37
|
-
```php
|
|
38
|
-
// Hook into order status change to 'completed'
|
|
39
|
-
add_action('fluent_cart/order_status_changed_to_completed', function ($data) {
|
|
40
|
-
// Extract order model from event data
|
|
41
|
-
$order = $data['order'];
|
|
42
|
-
// Grant digital access when order completes
|
|
43
|
-
grant_digital_access($order->customer_id, $order->id);
|
|
44
|
-
}, 10, 1);
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
---
|
|
48
|
-
|
|
49
|
-
### `order_status_changed`
|
|
50
|
-
`fluent_cart/order_status_changed` — Fires on any order status change
|
|
51
|
-
|
|
52
|
-
* **When it runs:** Fires immediately after the dynamic `order_status_changed_to_{$newStatus}` hook, on every order status transition regardless of the target status. Use this when you need to react to all status changes in a single callback.
|
|
53
|
-
* **Source:** `app/Events/Order/OrderStatusUpdated.php` (line 92)
|
|
54
|
-
|
|
55
|
-
#### Parameters:
|
|
56
|
-
`$data` *(array)*: Order status change data
|
|
57
|
-
```php
|
|
58
|
-
$data = [
|
|
59
|
-
'order' => $order, // \FluentCart\App\Models\Order
|
|
60
|
-
'old_status' => 'processing', // Previous order status
|
|
61
|
-
'new_status' => 'completed', // New order status
|
|
62
|
-
'manageStock' => true, // Whether stock management applies
|
|
63
|
-
'activity' => [
|
|
64
|
-
'title' => '',
|
|
65
|
-
'content' => '',
|
|
66
|
-
],
|
|
67
|
-
];
|
|
68
|
-
```
|
|
69
|
-
|
|
70
|
-
#### Usage Example:
|
|
71
|
-
```php
|
|
72
|
-
// Hook into any order status change
|
|
73
|
-
add_action('fluent_cart/order_status_changed', function ($data) {
|
|
74
|
-
// Extract order model from event data
|
|
75
|
-
$order = $data['order'];
|
|
76
|
-
// Log every status transition into FluentCart logs
|
|
77
|
-
fluent_cart_add_log(
|
|
78
|
-
'Order status changed',
|
|
79
|
-
sprintf('Order #%d: %s -> %s', $order->id, $data['old_status'], $data['new_status']),
|
|
80
|
-
'info'
|
|
81
|
-
);
|
|
82
|
-
}, 10, 1);
|
|
83
|
-
```
|
|
84
|
-
|
|
85
|
-
---
|
|
86
|
-
|
|
87
|
-
## Payment Status Changes
|
|
88
|
-
Fired when the payment status field changes (e.g. `pending` → `paid`). Both a dynamic, status-specific hook and a generic hook fire on every change.
|
|
89
|
-
|
|
90
|
-
### `payment_status_changed_to_{status}`
|
|
91
|
-
`fluent_cart/payment_status_changed_to_{$newStatus}` — Fires when payment status changes to a specific status
|
|
92
|
-
|
|
93
|
-
* **When it runs:** Fires inside `OrderStatusUpdated::afterDispatch()` when the status change type is `payment_status`. The `{$newStatus}` suffix is replaced dynamically so you can target a single payment state.
|
|
94
|
-
* **Available dynamic variants:** `pending`, `paid`, `partially_paid`, `failed`, `refunded`, `partially_refunded`, `authorized`
|
|
95
|
-
* **Source:** `app/Events/Order/OrderStatusUpdated.php` (line 81)
|
|
96
|
-
|
|
97
|
-
#### Parameters:
|
|
98
|
-
`$data` *(array)*: Payment status change data
|
|
99
|
-
```php
|
|
100
|
-
$data = [
|
|
101
|
-
'order' => $order, // \FluentCart\App\Models\Order
|
|
102
|
-
'old_status' => 'pending', // Previous payment status
|
|
103
|
-
'new_status' => 'paid', // New payment status (matches the dynamic suffix)
|
|
104
|
-
'manageStock' => true, // Whether stock management applies
|
|
105
|
-
'activity' => [
|
|
106
|
-
'title' => '',
|
|
107
|
-
'content' => '',
|
|
108
|
-
],
|
|
109
|
-
];
|
|
110
|
-
```
|
|
111
|
-
|
|
112
|
-
#### Usage Example:
|
|
113
|
-
```php
|
|
114
|
-
// Hook into payment status change to 'paid'
|
|
115
|
-
add_action('fluent_cart/payment_status_changed_to_paid', function ($data) {
|
|
116
|
-
// Extract order model from event data
|
|
117
|
-
$order = $data['order'];
|
|
118
|
-
// Trigger fulfillment workflow when payment is confirmed
|
|
119
|
-
do_action('my_custom_fulfillment_start', $order->id);
|
|
120
|
-
}, 10, 1);
|
|
121
|
-
```
|
|
122
|
-
|
|
123
|
-
---
|
|
124
|
-
|
|
125
|
-
### `payment_status_changed`
|
|
126
|
-
`fluent_cart/payment_status_changed` — Fires on any payment status change
|
|
127
|
-
|
|
128
|
-
* **When it runs:** Fires immediately after the dynamic `payment_status_changed_to_{$newStatus}` hook, on every payment status transition. Use this when you need a single callback for all payment status changes.
|
|
129
|
-
* **Source:** `app/Events/Order/OrderStatusUpdated.php` (line 82)
|
|
130
|
-
|
|
131
|
-
#### Parameters:
|
|
132
|
-
`$data` *(array)*: Payment status change data
|
|
133
|
-
```php
|
|
134
|
-
$data = [
|
|
135
|
-
'order' => $order, // \FluentCart\App\Models\Order
|
|
136
|
-
'old_status' => 'pending', // Previous payment status
|
|
137
|
-
'new_status' => 'paid', // New payment status
|
|
138
|
-
'manageStock' => true, // Whether stock management applies
|
|
139
|
-
'activity' => [
|
|
140
|
-
'title' => '',
|
|
141
|
-
'content' => '',
|
|
142
|
-
],
|
|
143
|
-
];
|
|
144
|
-
```
|
|
145
|
-
|
|
146
|
-
#### Usage Example:
|
|
147
|
-
```php
|
|
148
|
-
// Hook into any payment status change
|
|
149
|
-
add_action('fluent_cart/payment_status_changed', function ($data) {
|
|
150
|
-
// Extract order model from event data
|
|
151
|
-
$order = $data['order'];
|
|
152
|
-
// Send payment status update notification email if paid
|
|
153
|
-
if ($data['new_status'] === 'paid') {
|
|
154
|
-
wp_mail($order->customer->email, 'Payment Confirmed', 'Your payment has been received.');
|
|
155
|
-
}
|
|
156
|
-
}, 10, 1);
|
|
157
|
-
```
|
|
158
|
-
|
|
159
|
-
---
|
|
160
|
-
|
|
161
|
-
## Shipping Status Changes
|
|
162
|
-
Fired when the shipping status field changes (e.g. `unshipped` → `shipped`). Both a dynamic, status-specific hook and a generic hook fire on every change.
|
|
163
|
-
|
|
164
|
-
### `shipping_status_changed_to_{status}`
|
|
165
|
-
`fluent_cart/shipping_status_changed_to_{$newStatus}` — Fires when shipping status changes to a specific status
|
|
166
|
-
|
|
167
|
-
* **When it runs:** Fires inside `OrderStatusUpdated::afterDispatch()` when the status change type is `shipping_status`. The `{$newStatus}` suffix is replaced dynamically so you can target a single shipping state.
|
|
168
|
-
* **Available dynamic variants:** `unshipped`, `shipped`, `delivered`, `unshippable`
|
|
169
|
-
* **Source:** `app/Events/Order/OrderStatusUpdated.php` (line 86)
|
|
170
|
-
|
|
171
|
-
#### Parameters:
|
|
172
|
-
`$data` *(array)*: Shipping status change data
|
|
173
|
-
```php
|
|
174
|
-
$data = [
|
|
175
|
-
'order' => $order, // \FluentCart\App\Models\Order
|
|
176
|
-
'old_status' => 'unshipped', // Previous shipping status
|
|
177
|
-
'new_status' => 'shipped', // New shipping status (matches the dynamic suffix)
|
|
178
|
-
'manageStock' => true, // Whether stock management applies
|
|
179
|
-
'activity' => [
|
|
180
|
-
'title' => '',
|
|
181
|
-
'content' => '',
|
|
182
|
-
],
|
|
183
|
-
];
|
|
184
|
-
```
|
|
185
|
-
|
|
186
|
-
#### Usage Example:
|
|
187
|
-
```php
|
|
188
|
-
// Hook into shipping status change to 'shipped'
|
|
189
|
-
add_action('fluent_cart/shipping_status_changed_to_shipped', function ($data) {
|
|
190
|
-
// Extract order model from event data
|
|
191
|
-
$order = $data['order'];
|
|
192
|
-
// Notify customer that their order has shipped via email
|
|
193
|
-
wp_mail(
|
|
194
|
-
$order->customer->email,
|
|
195
|
-
'Your Order Has Shipped!',
|
|
196
|
-
sprintf('Order #%d has been shipped.', $order->id)
|
|
197
|
-
);
|
|
198
|
-
}, 10, 1);
|
|
199
|
-
```
|
|
200
|
-
|
|
201
|
-
---
|
|
202
|
-
|
|
203
|
-
### `shipping_status_changed`
|
|
204
|
-
`fluent_cart/shipping_status_changed` — Fires on any shipping status change
|
|
205
|
-
|
|
206
|
-
* **When it runs:** Fires immediately after the dynamic `shipping_status_changed_to_{$newStatus}` hook, on every shipping status transition. Use this when you need a single callback for all shipping status changes.
|
|
207
|
-
* **Source:** `app/Events/Order/OrderStatusUpdated.php` (line 87)
|
|
208
|
-
|
|
209
|
-
#### Parameters:
|
|
210
|
-
`$data` *(array)*: Shipping status change data
|
|
211
|
-
```php
|
|
212
|
-
$data = [
|
|
213
|
-
'order' => $order, // \FluentCart\App\Models\Order
|
|
214
|
-
'old_status' => 'unshipped', // Previous shipping status
|
|
215
|
-
'new_status' => 'shipped', // New shipping status
|
|
216
|
-
'manageStock' => true, // Whether stock management applies
|
|
217
|
-
'activity' => [
|
|
218
|
-
'title' => '',
|
|
219
|
-
'content' => '',
|
|
220
|
-
],
|
|
221
|
-
];
|
|
222
|
-
```
|
|
223
|
-
|
|
224
|
-
#### Usage Example:
|
|
225
|
-
```php
|
|
226
|
-
// Hook into any shipping status change
|
|
227
|
-
add_action('fluent_cart/shipping_status_changed', function ($data) {
|
|
228
|
-
// Extract order model from event data
|
|
229
|
-
$order = $data['order'];
|
|
230
|
-
// Log all shipping status transitions in system logs
|
|
231
|
-
fluent_cart_add_log(
|
|
232
|
-
'Shipping status changed',
|
|
233
|
-
sprintf('Order #%d: %s -> %s', $order->id, $data['old_status'], $data['new_status']),
|
|
234
|
-
'info'
|
|
235
|
-
);
|
|
236
|
-
}, 10, 1);
|
|
237
|
-
```
|
|
238
|
-
|
|
239
|
-
---
|
|
240
|
-
|
|
241
|
-
## Refunds
|
|
242
|
-
Fired during the refund flow after transaction records have been created. The generic `order_refunded` hook fires on every refund, followed by either `order_fully_refunded` or `order_partially_refunded` depending on the refund type. Refund data includes the Order, OrderItem, OrderTransaction, and Customer models.
|
|
243
|
-
|
|
244
|
-
### `order_refunded`
|
|
245
|
-
`fluent_cart/order_refunded` — Fires after any refund (full or partial)
|
|
246
|
-
|
|
247
|
-
* **When it runs:** Fires inside `OrderRefund::afterDispatch()` after a refund transaction is recorded and the refund amount is calculated. This hook fires for both full and partial refunds. It fires before the type-specific hooks below.
|
|
248
|
-
* **Source:** `app/Events/Order/OrderRefund.php` (line 141)
|
|
249
|
-
|
|
250
|
-
#### Parameters:
|
|
251
|
-
`$data` *(array)*: Refund data
|
|
252
|
-
```php
|
|
253
|
-
$data = [
|
|
254
|
-
'order' => $order, // \FluentCart\App\Models\Order
|
|
255
|
-
'refunded_items' => [], // Array of OrderItem models (looked up from refundedItemIds)
|
|
256
|
-
'new_refunded_items' => [], // Raw refunded items array with restore_quantity info
|
|
257
|
-
'refunded_amount' => 5000, // Newly refunded amount in cents
|
|
258
|
-
'manage_stock' => true, // Whether stock should be restored
|
|
259
|
-
'transaction' => $transaction, // \FluentCart\App\Models\OrderTransaction (the refund transaction)
|
|
260
|
-
'customer' => $customer, // \FluentCart\App\Models\Customer
|
|
261
|
-
'type' => 'full', // 'full' or 'partial'
|
|
262
|
-
];
|
|
263
|
-
```
|
|
264
|
-
|
|
265
|
-
#### Usage Example:
|
|
266
|
-
```php
|
|
267
|
-
// Hook into any order refund event (full or partial)
|
|
268
|
-
add_action('fluent_cart/order_refunded', function ($data) {
|
|
269
|
-
// Extract order model and calculate formatted decimal refund amount
|
|
270
|
-
$order = $data['order'];
|
|
271
|
-
$amount = \FluentCart\App\Helpers\Helper::toDecimal($data['refunded_amount']);
|
|
272
|
-
// Notify admin of any processed refund
|
|
273
|
-
wp_mail(
|
|
274
|
-
get_option('admin_email'),
|
|
275
|
-
sprintf('Refund on Order #%d', $order->id),
|
|
276
|
-
sprintf('A %s refund of %s has been processed.', $data['type'], $amount)
|
|
277
|
-
);
|
|
278
|
-
}, 10, 1);
|
|
279
|
-
```
|
|
280
|
-
|
|
281
|
-
---
|
|
282
|
-
|
|
283
|
-
### `order_fully_refunded`
|
|
284
|
-
`fluent_cart/order_fully_refunded` — Fires only when an order is fully refunded
|
|
285
|
-
|
|
286
|
-
* **When it runs:** Fires inside `OrderRefund::afterDispatch()` immediately after the generic `order_refunded` hook, but only when the total refunded amount meets or exceeds the order's total paid amount (i.e. full refund).
|
|
287
|
-
* **Source:** `app/Events/Order/OrderRefund.php` (line 144)
|
|
288
|
-
|
|
289
|
-
#### Parameters:
|
|
290
|
-
`$data` *(array)*: Full refund data (identical structure to `order_refunded`)
|
|
291
|
-
```php
|
|
292
|
-
$data = [
|
|
293
|
-
'order' => $order, // \FluentCart\App\Models\Order
|
|
294
|
-
'refunded_items' => [], // Array of OrderItem models
|
|
295
|
-
'new_refunded_items' => [], // Raw refunded items with restore_quantity
|
|
296
|
-
'refunded_amount' => 10000, // Refunded amount in cents
|
|
297
|
-
'manage_stock' => true, // Whether stock should be restored
|
|
298
|
-
'transaction' => $transaction, // \FluentCart\App\Models\OrderTransaction
|
|
299
|
-
'customer' => $customer, // \FluentCart\App\Models\Customer
|
|
300
|
-
'type' => 'full', // Always 'full' for this hook
|
|
301
|
-
];
|
|
302
|
-
```
|
|
303
|
-
|
|
304
|
-
#### Usage Example:
|
|
305
|
-
```php
|
|
306
|
-
// Hook into full order refund event
|
|
307
|
-
add_action('fluent_cart/order_fully_refunded', function ($data) {
|
|
308
|
-
// Extract order model from event data
|
|
309
|
-
$order = $data['order'];
|
|
310
|
-
// Revoke digital access on full refund
|
|
311
|
-
update_user_meta($order->customer_id, 'membership_active', false);
|
|
312
|
-
}, 10, 1);
|
|
313
|
-
```
|
|
314
|
-
|
|
315
|
-
---
|
|
316
|
-
|
|
317
|
-
### `order_partially_refunded`
|
|
318
|
-
`fluent_cart/order_partially_refunded` — Fires only when an order is partially refunded
|
|
319
|
-
|
|
320
|
-
* **When it runs:** Fires inside `OrderRefund::afterDispatch()` immediately after the generic `order_refunded` hook, but only when the total refunded amount is less than the order's total paid amount (i.e. partial refund).
|
|
321
|
-
* **Source:** `app/Events/Order/OrderRefund.php` (line 146)
|
|
322
|
-
|
|
323
|
-
#### Parameters:
|
|
324
|
-
`$data` *(array)*: Partial refund data (identical structure to `order_refunded`)
|
|
325
|
-
```php
|
|
326
|
-
$data = [
|
|
327
|
-
'order' => $order, // \FluentCart\App\Models\Order
|
|
328
|
-
'refunded_items' => [], // Array of OrderItem models
|
|
329
|
-
'new_refunded_items' => [], // Raw refunded items with restore_quantity
|
|
330
|
-
'refunded_amount' => 3000, // Refunded amount in cents
|
|
331
|
-
'manage_stock' => true, // Whether stock should be restored
|
|
332
|
-
'transaction' => $transaction, // \FluentCart\App\Models\OrderTransaction
|
|
333
|
-
'customer' => $customer, // \FluentCart\App\Models\Customer
|
|
334
|
-
'type' => 'partial', // Always 'partial' for this hook
|
|
335
|
-
];
|
|
336
|
-
```
|
|
337
|
-
|
|
338
|
-
#### Usage Example:
|
|
339
|
-
```php
|
|
340
|
-
// Hook into partial order refund event
|
|
341
|
-
add_action('fluent_cart/order_partially_refunded', function ($data) {
|
|
342
|
-
// Extract order and customer models from event data
|
|
343
|
-
$order = $data['order'];
|
|
344
|
-
$customer = $data['customer'];
|
|
345
|
-
// Notify customer of partial refund via email
|
|
346
|
-
wp_mail(
|
|
347
|
-
$customer->email,
|
|
348
|
-
'Partial Refund Processed',
|
|
349
|
-
sprintf('A partial refund has been issued for Order #%d.', $order->id)
|
|
350
|
-
);
|
|
351
|
-
}, 10, 1);
|
|
352
|
-
```
|
|
353
|
-
|
|
354
|
-
---
|
|
355
|
-
|
|
356
|
-
## Order Items
|
|
357
|
-
Hooks that fire when custom line items on an order are being deleted. These are useful for cleanup or audit logging on custom `OrderItem` records.
|
|
358
|
-
|
|
359
|
-
### `order/before_custom_items_deleted`
|
|
360
|
-
`fluent_cart/order/before_custom_items_deleted` — Fires before custom line items are deleted
|
|
361
|
-
|
|
362
|
-
* **When it runs:** Fires inside `OrderResource::updateOrderItems()` just before custom order items (flagged as `is_custom`) are permanently deleted from the database. Only fires if the filtered collection of custom items is not empty.
|
|
363
|
-
* **Source:** `api/Resource/OrderResource.php` (line 535)
|
|
364
|
-
|
|
365
|
-
#### Parameters:
|
|
366
|
-
* `$customItems` *(\Illuminate\Support\Collection)*: Collection of `\FluentCart\App\Models\OrderItem` models about to be deleted (only items where `is_custom` is `true`)
|
|
367
|
-
* `$order` *(\FluentCart\App\Models\Order)*: The parent order model
|
|
368
|
-
|
|
369
|
-
#### Usage Example:
|
|
370
|
-
```php
|
|
371
|
-
// Hook before custom order items are deleted
|
|
372
|
-
add_action('fluent_cart/order/before_custom_items_deleted', function ($customItems, $order) {
|
|
373
|
-
// Archive custom items before they are removed from the database
|
|
374
|
-
foreach ($customItems as $item) {
|
|
375
|
-
fluent_cart_add_log(
|
|
376
|
-
'Custom item removed',
|
|
377
|
-
sprintf('Item "%s" removed from Order #%d', $item->title, $order->id),
|
|
378
|
-
'info'
|
|
379
|
-
);
|
|
380
|
-
}
|
|
381
|
-
}, 10, 2);
|
|
382
|
-
```
|
|
383
|
-
|
|
384
|
-
---
|
|
385
|
-
|
|
386
|
-
### `order/after_custom_items_deleted`
|
|
387
|
-
`fluent_cart/order/after_custom_items_deleted` — Fires after custom line items are deleted
|
|
388
|
-
|
|
389
|
-
* **When it runs:** Fires inside `OrderResource::updateOrderItems()` immediately after custom order items have been permanently deleted from the database. The collection still holds the model instances (now removed from DB). Only fires if the collection is not empty.
|
|
390
|
-
* **Source:** `api/Resource/OrderResource.php` (line 541)
|
|
391
|
-
|
|
392
|
-
#### Parameters:
|
|
393
|
-
* `$customItems` *(\Illuminate\Support\Collection)*: Collection of `\FluentCart\App\Models\OrderItem` models that were just deleted
|
|
394
|
-
* `$order` *(\FluentCart\App\Models\Order)*: The parent order model
|
|
395
|
-
|
|
396
|
-
#### Usage Example:
|
|
397
|
-
```php
|
|
398
|
-
// Hook after custom order items are deleted
|
|
399
|
-
add_action('fluent_cart/order/after_custom_items_deleted', function ($customItems, $order) {
|
|
400
|
-
// Recalculate order totals after custom items are removed
|
|
401
|
-
$order->recalculateTotals();
|
|
402
|
-
}, 10, 2);
|
|
403
|
-
```
|
|
404
|
-
|
|
405
|
-
---
|
|
406
|
-
|
|
407
|
-
## Order Lifecycle
|
|
408
|
-
General lifecycle hooks that fire at key moments during an Order's existence: invoice generation, Customer changes, payment completion, license generation, and receipt viewing.
|
|
409
|
-
|
|
410
|
-
### `order/invoice_number_added`
|
|
411
|
-
`fluent_cart/order/invoice_number_added` — Fires after an invoice/receipt number is assigned to an order
|
|
412
|
-
|
|
413
|
-
* **When it runs:** Fires in two places:
|
|
414
|
-
1. Inside the `Order::booted()` created callback, immediately after a new order is persisted to the database with an invoice number already set (when payment status is `paid` at creation time).
|
|
415
|
-
2. Inside `Order::generateReceiptNumber()`, when a receipt number is generated for an existing order that did not previously have one.
|
|
416
|
-
* **Source:** `app/Models/Order.php` (lines 60 and 734)
|
|
417
|
-
|
|
418
|
-
#### Parameters:
|
|
419
|
-
`$data` *(array)*: Order data
|
|
420
|
-
```php
|
|
421
|
-
$data = [
|
|
422
|
-
'order' => $order, // \FluentCart\App\Models\Order
|
|
423
|
-
];
|
|
424
|
-
```
|
|
425
|
-
|
|
426
|
-
#### Usage Example:
|
|
427
|
-
```php
|
|
428
|
-
// Hook when invoice/receipt number is assigned to an order
|
|
429
|
-
add_action('fluent_cart/order/invoice_number_added', function ($data) {
|
|
430
|
-
// Extract order model from event data
|
|
431
|
-
$order = $data['order'];
|
|
432
|
-
// Sync invoice number to external accounting system
|
|
433
|
-
sync_to_accounting($order->id, $order->invoice_no, $order->receipt_number);
|
|
434
|
-
}, 10, 1);
|
|
435
|
-
```
|
|
436
|
-
|
|
437
|
-
---
|
|
438
|
-
|
|
439
|
-
### `order_customer_changed`
|
|
440
|
-
`fluent_cart/order_customer_changed` — Fires when the customer assigned to an order changes
|
|
441
|
-
|
|
442
|
-
* **When it runs:** Fires inside `OrderController::changeCustomer()` after the order (and any child orders and subscriptions) have been reassigned to a new customer, and both the old and new customer stats have been recounted.
|
|
443
|
-
* **Source:** `app/Http/Controllers/OrderController.php` (line 427)
|
|
444
|
-
|
|
445
|
-
#### Parameters:
|
|
446
|
-
`$data` *(array)*: Customer change data
|
|
447
|
-
```php
|
|
448
|
-
$data = [
|
|
449
|
-
'order' => $order, // \FluentCart\App\Models\Order
|
|
450
|
-
'old_customer' => $oldCustomer, // \FluentCart\App\Models\Customer|null
|
|
451
|
-
'new_customer' => $newCustomer, // \FluentCart\App\Models\Customer
|
|
452
|
-
'connected_order_ids' => [123, 124], // Array of all order IDs updated (parent + children)
|
|
453
|
-
];
|
|
454
|
-
```
|
|
455
|
-
|
|
456
|
-
#### Usage Example:
|
|
457
|
-
```php
|
|
458
|
-
// Hook when the customer assigned to an order changes
|
|
459
|
-
add_action('fluent_cart/order_customer_changed', function ($data) {
|
|
460
|
-
// Extract order and customer models from event data
|
|
461
|
-
$order = $data['order'];
|
|
462
|
-
$oldCustomer = $data['old_customer'];
|
|
463
|
-
$newCustomer = $data['new_customer'];
|
|
464
|
-
// Notify the new customer about the order account transfer
|
|
465
|
-
wp_mail(
|
|
466
|
-
$newCustomer->email,
|
|
467
|
-
'Order Transferred to Your Account',
|
|
468
|
-
sprintf('Order #%d has been assigned to your account.', $order->id)
|
|
469
|
-
);
|
|
470
|
-
}, 10, 1);
|
|
471
|
-
```
|
|
472
|
-
|
|
473
|
-
---
|
|
474
|
-
|
|
475
|
-
### `order/generateMissingLicenses`
|
|
476
|
-
`fluent_cart/order/generateMissingLicenses` — Fires when an admin triggers license generation for an order
|
|
477
|
-
|
|
478
|
-
* **When it runs:** Fires inside `OrderController::generateLicense()` when an admin requests license generation for an order that has fewer licenses than expected. This allows license modules to hook in and create the missing license keys.
|
|
479
|
-
* **Source:** `app/Http/Controllers/OrderController.php` (line 225)
|
|
480
|
-
|
|
481
|
-
#### Parameters:
|
|
482
|
-
`$data` *(array)*: Order data
|
|
483
|
-
```php
|
|
484
|
-
$data = [
|
|
485
|
-
'order' => $order, // \FluentCart\App\Models\Order (with order_items and licenses loaded)
|
|
486
|
-
];
|
|
487
|
-
```
|
|
488
|
-
|
|
489
|
-
#### Usage Example:
|
|
490
|
-
```php
|
|
491
|
-
// Hook when admin requests missing license generation for an order
|
|
492
|
-
add_action('fluent_cart/order/generateMissingLicenses', function ($data) {
|
|
493
|
-
// Extract order model from event data
|
|
494
|
-
$order = $data['order'];
|
|
495
|
-
// Generate licenses for each eligible order item
|
|
496
|
-
foreach ($order->order_items as $item) {
|
|
497
|
-
generate_license_key($order->id, $item->product_id);
|
|
498
|
-
}
|
|
499
|
-
}, 10, 1);
|
|
500
|
-
```
|
|
501
|
-
|
|
502
|
-
---
|
|
503
|
-
|
|
504
|
-
### `order_placed_offline`
|
|
505
|
-
`fluent_cart/order_placed_offline` — Fires when an order is placed via Cash on Delivery or other offline payment
|
|
506
|
-
|
|
507
|
-
* **When it runs:** Fires inside `CodHandler::processPayment()` after the order and its transaction have been created for an offline/COD payment. The Order, Customer, and transaction data are all available at this point. The order has its `customer`, `shipping_address`, and `billing_address` relationships loaded.
|
|
508
|
-
* **Source:** `app/Modules/PaymentMethods/Cod/CodHandler.php` (line 55)
|
|
509
|
-
|
|
510
|
-
#### Parameters:
|
|
511
|
-
`$data` *(array)*: Offline order data
|
|
512
|
-
```php
|
|
513
|
-
$data = [
|
|
514
|
-
'order' => $order, // \FluentCart\App\Models\Order
|
|
515
|
-
'customer' => $order->customer ?? [], // \FluentCart\App\Models\Customer or empty array
|
|
516
|
-
'transaction' => $transaction ?? [], // \FluentCart\App\Models\OrderTransaction or empty array
|
|
517
|
-
];
|
|
518
|
-
```
|
|
519
|
-
|
|
520
|
-
#### Usage Example:
|
|
521
|
-
```php
|
|
522
|
-
// Hook when an order is placed via Cash on Delivery or offline payment
|
|
523
|
-
add_action('fluent_cart/order_placed_offline', function ($data) {
|
|
524
|
-
// Extract order model from event data
|
|
525
|
-
$order = $data['order'];
|
|
526
|
-
// Notify warehouse of new COD order
|
|
527
|
-
wp_mail(
|
|
528
|
-
'warehouse@example.com',
|
|
529
|
-
sprintf('New COD Order #%d', $order->id),
|
|
530
|
-
'A new Cash on Delivery order needs to be prepared for shipment.'
|
|
531
|
-
);
|
|
532
|
-
}, 10, 1);
|
|
533
|
-
```
|
|
534
|
-
|
|
535
|
-
---
|
|
536
|
-
|
|
537
|
-
### `order_paid_done`
|
|
538
|
-
`fluent_cart/order_paid_done` — Main lifecycle hook when order payment completes (recommended for integrations)
|
|
539
|
-
|
|
540
|
-
* **When it runs:** Fires asynchronously via Action Scheduler after an order's payment is confirmed as paid. The `OrderPaid` event enqueues a `fluent_cart/order_paid_ansyc_private_handle` async action, which validates the order is still paid, then dispatches this hook. This is the recommended hook for third-party integrations because it runs outside the payment gateway request cycle, avoiding race conditions and timeouts. For subscription or renewal orders, the associated Subscription model is included in the data.
|
|
541
|
-
* **Note:** The `subscription` key is only present when the order type is subscription or renewal.
|
|
542
|
-
* **Source:** `app/Hooks/actions.php` (line 159)
|
|
543
|
-
|
|
544
|
-
#### Parameters:
|
|
545
|
-
`$data` *(array)*: Order payment completion data
|
|
546
|
-
```php
|
|
547
|
-
$data = [
|
|
548
|
-
'order' => $order, // \FluentCart\App\Models\Order
|
|
549
|
-
'transaction' => $transaction, // \FluentCart\App\Models\OrderTransaction (latest successful transaction)
|
|
550
|
-
'customer' => $customer, // \FluentCart\App\Models\Customer
|
|
551
|
-
'subscription' => $subscription, // \FluentCart\App\Models\Subscription (only for subscription/renewal orders)
|
|
552
|
-
];
|
|
553
|
-
```
|
|
554
|
-
|
|
555
|
-
#### Usage Example:
|
|
556
|
-
```php
|
|
557
|
-
// Main lifecycle hook when order payment completes (recommended for integrations)
|
|
558
|
-
add_action('fluent_cart/order_paid_done', function ($data) {
|
|
559
|
-
// Extract order and customer models from event data
|
|
560
|
-
$order = $data['order'];
|
|
561
|
-
$customer = $data['customer'];
|
|
562
|
-
|
|
563
|
-
// Grant membership access after payment
|
|
564
|
-
update_user_meta($customer->user_id, 'membership_active', true);
|
|
565
|
-
|
|
566
|
-
// Handle subscription orders differently if subscription instance exists
|
|
567
|
-
if (!empty($data['subscription'])) {
|
|
568
|
-
$subscription = $data['subscription'];
|
|
569
|
-
update_user_meta($customer->user_id, 'subscription_id', $subscription->id);
|
|
570
|
-
}
|
|
571
|
-
}, 10, 1);
|
|
572
|
-
```
|
|
573
|
-
|
|
574
|
-
---
|
|
575
|
-
|
|
576
|
-
### `order_paid_ansyc_private_handle`
|
|
577
|
-
`fluent_cart/order_paid_ansyc_private_handle` — Internal async handler that processes post-payment integrations
|
|
578
|
-
|
|
579
|
-
* **When it runs:** Enqueued by `OrderPaid::afterDispatch()` as an Action Scheduler async action. The handler in `app/Hooks/actions.php` validates the order, clears the scheduler meta, and then dispatches `fluent_cart/order_paid_done`. It is also dispatched manually in `IntegrationEventListener` for retry scenarios. You should generally hook into `order_paid_done` instead of this hook.
|
|
580
|
-
* **Source:** `app/Listeners/IntegrationEventListener.php` (line 360), `app/Hooks/actions.php` (line 126)
|
|
581
|
-
|
|
582
|
-
#### Parameters:
|
|
583
|
-
`$data` *(array)*: Order identifier
|
|
584
|
-
```php
|
|
585
|
-
$data = [
|
|
586
|
-
'order_id' => 123, // int: The order ID to process
|
|
587
|
-
];
|
|
588
|
-
```
|
|
589
|
-
|
|
590
|
-
#### Usage Example:
|
|
591
|
-
```php
|
|
592
|
-
// Internal async handler (Not recommended for third-party use; use fluent_cart/order_paid_done instead)
|
|
593
|
-
add_action('fluent_cart/order_paid_ansyc_private_handle', function ($data) {
|
|
594
|
-
// Extract order ID from event data
|
|
595
|
-
$orderId = $data['order_id'];
|
|
596
|
-
// Internal processing only
|
|
597
|
-
}, 10, 1);
|
|
598
|
-
```
|
|
599
|
-
|
|
600
|
-
---
|
|
601
|
-
|
|
602
|
-
### `order/receipt_viewed`
|
|
603
|
-
`fluent_cart/order/receipt_viewed` — Fires the first time a customer views their order receipt
|
|
604
|
-
|
|
605
|
-
* **When it runs:** Fires at the end of receipt rendering (both the `ReceiptRenderer` class and the `receipt_slip.php` view template) when the `$is_first_time` flag is `true`. This means it only fires once per order, the very first time the receipt page is loaded. Subsequent views do not trigger this hook. The data includes both the Order and OrderOperation models.
|
|
606
|
-
* **Source:** `app/Services/Renderer/Receipt/ReceiptRenderer.php` (line 151), `app/Views/invoice/receipt_slip.php` (line 482)
|
|
607
|
-
|
|
608
|
-
#### Parameters:
|
|
609
|
-
`$data` *(array)*: Receipt view data
|
|
610
|
-
```php
|
|
611
|
-
$data = [
|
|
612
|
-
'order' => $order, // \FluentCart\App\Models\Order
|
|
613
|
-
'order_operation' => $order_operation, // \FluentCart\App\Models\OrderOperation
|
|
614
|
-
];
|
|
615
|
-
```
|
|
616
|
-
|
|
617
|
-
#### Usage Example:
|
|
618
|
-
```php
|
|
619
|
-
// Hook when customer views their order receipt for the first time
|
|
620
|
-
add_action('fluent_cart/order/receipt_viewed', function ($data) {
|
|
621
|
-
// Extract order model from event data
|
|
622
|
-
$order = $data['order'];
|
|
623
|
-
// Track receipt view for analytics logging
|
|
624
|
-
fluent_cart_add_log(
|
|
625
|
-
'Receipt viewed',
|
|
626
|
-
sprintf('Customer viewed receipt for Order #%d', $order->id),
|
|
627
|
-
'info',
|
|
628
|
-
['module_name' => 'order', 'module_id' => $order->id]
|
|
629
|
-
);
|
|
630
|
-
}, 10, 1);
|
|
631
|
-
```
|
|
1
|
+
# Action Hooks: Orders
|
|
2
|
+
|
|
3
|
+
All hooks related to order lifecycle, status transitions, payments, shipping, refunds, and order items. These action hooks allow you to respond to key order events in FluentCart.
|
|
4
|
+
|
|
5
|
+
Each hook passes an associative array as its single parameter. The order value is always an `\FluentCart\App\Models\Order` model instance with the `customer`, `shipping_address`, and `billing_address` relationships eager-loaded (unless noted otherwise).
|
|
6
|
+
|
|
7
|
+
Amounts are in cents. All monetary values (`total`, `refunded_amount`, etc.) are stored as integers in the smallest currency unit. Use `Helper::toDecimal($amount)` to convert for display.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## Order Status Changes
|
|
12
|
+
Fired when the order status field changes (e.g. `processing` → `completed`). Both a dynamic, status-specific hook and a generic hook fire on every change.
|
|
13
|
+
|
|
14
|
+
### `order_status_changed_to_{status}`
|
|
15
|
+
`fluent_cart/order_status_changed_to_{$newStatus}` — Fires when the order status changes to a specific status
|
|
16
|
+
|
|
17
|
+
* **When it runs:** Fires inside `OrderStatusUpdated::afterDispatch()` whenever the order status type transitions to a new value. The `{$newStatus}` portion is replaced dynamically with the target status, so you can listen for a single status you care about.
|
|
18
|
+
* **Available dynamic variants:** `completed`, `canceled`, `processing`, `on-hold`, `failed`
|
|
19
|
+
* **Source:** `app/Events/Order/OrderStatusUpdated.php` (line 91)
|
|
20
|
+
|
|
21
|
+
#### Parameters:
|
|
22
|
+
`$data` *(array)*: Order status change data
|
|
23
|
+
```php
|
|
24
|
+
$data = [
|
|
25
|
+
'order' => $order, // \FluentCart\App\Models\Order (with customer, addresses loaded)
|
|
26
|
+
'old_status' => 'processing', // Previous order status string
|
|
27
|
+
'new_status' => 'completed', // New order status string (matches the dynamic suffix)
|
|
28
|
+
'manageStock' => true, // Whether stock management should be applied
|
|
29
|
+
'activity' => [ // Optional activity log context
|
|
30
|
+
'title' => '',
|
|
31
|
+
'content' => '',
|
|
32
|
+
],
|
|
33
|
+
];
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
#### Usage Example:
|
|
37
|
+
```php
|
|
38
|
+
// Hook into order status change to 'completed'
|
|
39
|
+
add_action('fluent_cart/order_status_changed_to_completed', function ($data) {
|
|
40
|
+
// Extract order model from event data
|
|
41
|
+
$order = $data['order'];
|
|
42
|
+
// Grant digital access when order completes
|
|
43
|
+
grant_digital_access($order->customer_id, $order->id);
|
|
44
|
+
}, 10, 1);
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
### `order_status_changed`
|
|
50
|
+
`fluent_cart/order_status_changed` — Fires on any order status change
|
|
51
|
+
|
|
52
|
+
* **When it runs:** Fires immediately after the dynamic `order_status_changed_to_{$newStatus}` hook, on every order status transition regardless of the target status. Use this when you need to react to all status changes in a single callback.
|
|
53
|
+
* **Source:** `app/Events/Order/OrderStatusUpdated.php` (line 92)
|
|
54
|
+
|
|
55
|
+
#### Parameters:
|
|
56
|
+
`$data` *(array)*: Order status change data
|
|
57
|
+
```php
|
|
58
|
+
$data = [
|
|
59
|
+
'order' => $order, // \FluentCart\App\Models\Order
|
|
60
|
+
'old_status' => 'processing', // Previous order status
|
|
61
|
+
'new_status' => 'completed', // New order status
|
|
62
|
+
'manageStock' => true, // Whether stock management applies
|
|
63
|
+
'activity' => [
|
|
64
|
+
'title' => '',
|
|
65
|
+
'content' => '',
|
|
66
|
+
],
|
|
67
|
+
];
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
#### Usage Example:
|
|
71
|
+
```php
|
|
72
|
+
// Hook into any order status change
|
|
73
|
+
add_action('fluent_cart/order_status_changed', function ($data) {
|
|
74
|
+
// Extract order model from event data
|
|
75
|
+
$order = $data['order'];
|
|
76
|
+
// Log every status transition into FluentCart logs
|
|
77
|
+
fluent_cart_add_log(
|
|
78
|
+
'Order status changed',
|
|
79
|
+
sprintf('Order #%d: %s -> %s', $order->id, $data['old_status'], $data['new_status']),
|
|
80
|
+
'info'
|
|
81
|
+
);
|
|
82
|
+
}, 10, 1);
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
---
|
|
86
|
+
|
|
87
|
+
## Payment Status Changes
|
|
88
|
+
Fired when the payment status field changes (e.g. `pending` → `paid`). Both a dynamic, status-specific hook and a generic hook fire on every change.
|
|
89
|
+
|
|
90
|
+
### `payment_status_changed_to_{status}`
|
|
91
|
+
`fluent_cart/payment_status_changed_to_{$newStatus}` — Fires when payment status changes to a specific status
|
|
92
|
+
|
|
93
|
+
* **When it runs:** Fires inside `OrderStatusUpdated::afterDispatch()` when the status change type is `payment_status`. The `{$newStatus}` suffix is replaced dynamically so you can target a single payment state.
|
|
94
|
+
* **Available dynamic variants:** `pending`, `paid`, `partially_paid`, `failed`, `refunded`, `partially_refunded`, `authorized`
|
|
95
|
+
* **Source:** `app/Events/Order/OrderStatusUpdated.php` (line 81)
|
|
96
|
+
|
|
97
|
+
#### Parameters:
|
|
98
|
+
`$data` *(array)*: Payment status change data
|
|
99
|
+
```php
|
|
100
|
+
$data = [
|
|
101
|
+
'order' => $order, // \FluentCart\App\Models\Order
|
|
102
|
+
'old_status' => 'pending', // Previous payment status
|
|
103
|
+
'new_status' => 'paid', // New payment status (matches the dynamic suffix)
|
|
104
|
+
'manageStock' => true, // Whether stock management applies
|
|
105
|
+
'activity' => [
|
|
106
|
+
'title' => '',
|
|
107
|
+
'content' => '',
|
|
108
|
+
],
|
|
109
|
+
];
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
#### Usage Example:
|
|
113
|
+
```php
|
|
114
|
+
// Hook into payment status change to 'paid'
|
|
115
|
+
add_action('fluent_cart/payment_status_changed_to_paid', function ($data) {
|
|
116
|
+
// Extract order model from event data
|
|
117
|
+
$order = $data['order'];
|
|
118
|
+
// Trigger fulfillment workflow when payment is confirmed
|
|
119
|
+
do_action('my_custom_fulfillment_start', $order->id);
|
|
120
|
+
}, 10, 1);
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
### `payment_status_changed`
|
|
126
|
+
`fluent_cart/payment_status_changed` — Fires on any payment status change
|
|
127
|
+
|
|
128
|
+
* **When it runs:** Fires immediately after the dynamic `payment_status_changed_to_{$newStatus}` hook, on every payment status transition. Use this when you need a single callback for all payment status changes.
|
|
129
|
+
* **Source:** `app/Events/Order/OrderStatusUpdated.php` (line 82)
|
|
130
|
+
|
|
131
|
+
#### Parameters:
|
|
132
|
+
`$data` *(array)*: Payment status change data
|
|
133
|
+
```php
|
|
134
|
+
$data = [
|
|
135
|
+
'order' => $order, // \FluentCart\App\Models\Order
|
|
136
|
+
'old_status' => 'pending', // Previous payment status
|
|
137
|
+
'new_status' => 'paid', // New payment status
|
|
138
|
+
'manageStock' => true, // Whether stock management applies
|
|
139
|
+
'activity' => [
|
|
140
|
+
'title' => '',
|
|
141
|
+
'content' => '',
|
|
142
|
+
],
|
|
143
|
+
];
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
#### Usage Example:
|
|
147
|
+
```php
|
|
148
|
+
// Hook into any payment status change
|
|
149
|
+
add_action('fluent_cart/payment_status_changed', function ($data) {
|
|
150
|
+
// Extract order model from event data
|
|
151
|
+
$order = $data['order'];
|
|
152
|
+
// Send payment status update notification email if paid
|
|
153
|
+
if ($data['new_status'] === 'paid') {
|
|
154
|
+
wp_mail($order->customer->email, 'Payment Confirmed', 'Your payment has been received.');
|
|
155
|
+
}
|
|
156
|
+
}, 10, 1);
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
---
|
|
160
|
+
|
|
161
|
+
## Shipping Status Changes
|
|
162
|
+
Fired when the shipping status field changes (e.g. `unshipped` → `shipped`). Both a dynamic, status-specific hook and a generic hook fire on every change.
|
|
163
|
+
|
|
164
|
+
### `shipping_status_changed_to_{status}`
|
|
165
|
+
`fluent_cart/shipping_status_changed_to_{$newStatus}` — Fires when shipping status changes to a specific status
|
|
166
|
+
|
|
167
|
+
* **When it runs:** Fires inside `OrderStatusUpdated::afterDispatch()` when the status change type is `shipping_status`. The `{$newStatus}` suffix is replaced dynamically so you can target a single shipping state.
|
|
168
|
+
* **Available dynamic variants:** `unshipped`, `shipped`, `delivered`, `unshippable`
|
|
169
|
+
* **Source:** `app/Events/Order/OrderStatusUpdated.php` (line 86)
|
|
170
|
+
|
|
171
|
+
#### Parameters:
|
|
172
|
+
`$data` *(array)*: Shipping status change data
|
|
173
|
+
```php
|
|
174
|
+
$data = [
|
|
175
|
+
'order' => $order, // \FluentCart\App\Models\Order
|
|
176
|
+
'old_status' => 'unshipped', // Previous shipping status
|
|
177
|
+
'new_status' => 'shipped', // New shipping status (matches the dynamic suffix)
|
|
178
|
+
'manageStock' => true, // Whether stock management applies
|
|
179
|
+
'activity' => [
|
|
180
|
+
'title' => '',
|
|
181
|
+
'content' => '',
|
|
182
|
+
],
|
|
183
|
+
];
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
#### Usage Example:
|
|
187
|
+
```php
|
|
188
|
+
// Hook into shipping status change to 'shipped'
|
|
189
|
+
add_action('fluent_cart/shipping_status_changed_to_shipped', function ($data) {
|
|
190
|
+
// Extract order model from event data
|
|
191
|
+
$order = $data['order'];
|
|
192
|
+
// Notify customer that their order has shipped via email
|
|
193
|
+
wp_mail(
|
|
194
|
+
$order->customer->email,
|
|
195
|
+
'Your Order Has Shipped!',
|
|
196
|
+
sprintf('Order #%d has been shipped.', $order->id)
|
|
197
|
+
);
|
|
198
|
+
}, 10, 1);
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
---
|
|
202
|
+
|
|
203
|
+
### `shipping_status_changed`
|
|
204
|
+
`fluent_cart/shipping_status_changed` — Fires on any shipping status change
|
|
205
|
+
|
|
206
|
+
* **When it runs:** Fires immediately after the dynamic `shipping_status_changed_to_{$newStatus}` hook, on every shipping status transition. Use this when you need a single callback for all shipping status changes.
|
|
207
|
+
* **Source:** `app/Events/Order/OrderStatusUpdated.php` (line 87)
|
|
208
|
+
|
|
209
|
+
#### Parameters:
|
|
210
|
+
`$data` *(array)*: Shipping status change data
|
|
211
|
+
```php
|
|
212
|
+
$data = [
|
|
213
|
+
'order' => $order, // \FluentCart\App\Models\Order
|
|
214
|
+
'old_status' => 'unshipped', // Previous shipping status
|
|
215
|
+
'new_status' => 'shipped', // New shipping status
|
|
216
|
+
'manageStock' => true, // Whether stock management applies
|
|
217
|
+
'activity' => [
|
|
218
|
+
'title' => '',
|
|
219
|
+
'content' => '',
|
|
220
|
+
],
|
|
221
|
+
];
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
#### Usage Example:
|
|
225
|
+
```php
|
|
226
|
+
// Hook into any shipping status change
|
|
227
|
+
add_action('fluent_cart/shipping_status_changed', function ($data) {
|
|
228
|
+
// Extract order model from event data
|
|
229
|
+
$order = $data['order'];
|
|
230
|
+
// Log all shipping status transitions in system logs
|
|
231
|
+
fluent_cart_add_log(
|
|
232
|
+
'Shipping status changed',
|
|
233
|
+
sprintf('Order #%d: %s -> %s', $order->id, $data['old_status'], $data['new_status']),
|
|
234
|
+
'info'
|
|
235
|
+
);
|
|
236
|
+
}, 10, 1);
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
---
|
|
240
|
+
|
|
241
|
+
## Refunds
|
|
242
|
+
Fired during the refund flow after transaction records have been created. The generic `order_refunded` hook fires on every refund, followed by either `order_fully_refunded` or `order_partially_refunded` depending on the refund type. Refund data includes the Order, OrderItem, OrderTransaction, and Customer models.
|
|
243
|
+
|
|
244
|
+
### `order_refunded`
|
|
245
|
+
`fluent_cart/order_refunded` — Fires after any refund (full or partial)
|
|
246
|
+
|
|
247
|
+
* **When it runs:** Fires inside `OrderRefund::afterDispatch()` after a refund transaction is recorded and the refund amount is calculated. This hook fires for both full and partial refunds. It fires before the type-specific hooks below.
|
|
248
|
+
* **Source:** `app/Events/Order/OrderRefund.php` (line 141)
|
|
249
|
+
|
|
250
|
+
#### Parameters:
|
|
251
|
+
`$data` *(array)*: Refund data
|
|
252
|
+
```php
|
|
253
|
+
$data = [
|
|
254
|
+
'order' => $order, // \FluentCart\App\Models\Order
|
|
255
|
+
'refunded_items' => [], // Array of OrderItem models (looked up from refundedItemIds)
|
|
256
|
+
'new_refunded_items' => [], // Raw refunded items array with restore_quantity info
|
|
257
|
+
'refunded_amount' => 5000, // Newly refunded amount in cents
|
|
258
|
+
'manage_stock' => true, // Whether stock should be restored
|
|
259
|
+
'transaction' => $transaction, // \FluentCart\App\Models\OrderTransaction (the refund transaction)
|
|
260
|
+
'customer' => $customer, // \FluentCart\App\Models\Customer
|
|
261
|
+
'type' => 'full', // 'full' or 'partial'
|
|
262
|
+
];
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
#### Usage Example:
|
|
266
|
+
```php
|
|
267
|
+
// Hook into any order refund event (full or partial)
|
|
268
|
+
add_action('fluent_cart/order_refunded', function ($data) {
|
|
269
|
+
// Extract order model and calculate formatted decimal refund amount
|
|
270
|
+
$order = $data['order'];
|
|
271
|
+
$amount = \FluentCart\App\Helpers\Helper::toDecimal($data['refunded_amount']);
|
|
272
|
+
// Notify admin of any processed refund
|
|
273
|
+
wp_mail(
|
|
274
|
+
get_option('admin_email'),
|
|
275
|
+
sprintf('Refund on Order #%d', $order->id),
|
|
276
|
+
sprintf('A %s refund of %s has been processed.', $data['type'], $amount)
|
|
277
|
+
);
|
|
278
|
+
}, 10, 1);
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
---
|
|
282
|
+
|
|
283
|
+
### `order_fully_refunded`
|
|
284
|
+
`fluent_cart/order_fully_refunded` — Fires only when an order is fully refunded
|
|
285
|
+
|
|
286
|
+
* **When it runs:** Fires inside `OrderRefund::afterDispatch()` immediately after the generic `order_refunded` hook, but only when the total refunded amount meets or exceeds the order's total paid amount (i.e. full refund).
|
|
287
|
+
* **Source:** `app/Events/Order/OrderRefund.php` (line 144)
|
|
288
|
+
|
|
289
|
+
#### Parameters:
|
|
290
|
+
`$data` *(array)*: Full refund data (identical structure to `order_refunded`)
|
|
291
|
+
```php
|
|
292
|
+
$data = [
|
|
293
|
+
'order' => $order, // \FluentCart\App\Models\Order
|
|
294
|
+
'refunded_items' => [], // Array of OrderItem models
|
|
295
|
+
'new_refunded_items' => [], // Raw refunded items with restore_quantity
|
|
296
|
+
'refunded_amount' => 10000, // Refunded amount in cents
|
|
297
|
+
'manage_stock' => true, // Whether stock should be restored
|
|
298
|
+
'transaction' => $transaction, // \FluentCart\App\Models\OrderTransaction
|
|
299
|
+
'customer' => $customer, // \FluentCart\App\Models\Customer
|
|
300
|
+
'type' => 'full', // Always 'full' for this hook
|
|
301
|
+
];
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
#### Usage Example:
|
|
305
|
+
```php
|
|
306
|
+
// Hook into full order refund event
|
|
307
|
+
add_action('fluent_cart/order_fully_refunded', function ($data) {
|
|
308
|
+
// Extract order model from event data
|
|
309
|
+
$order = $data['order'];
|
|
310
|
+
// Revoke digital access on full refund
|
|
311
|
+
update_user_meta($order->customer_id, 'membership_active', false);
|
|
312
|
+
}, 10, 1);
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
---
|
|
316
|
+
|
|
317
|
+
### `order_partially_refunded`
|
|
318
|
+
`fluent_cart/order_partially_refunded` — Fires only when an order is partially refunded
|
|
319
|
+
|
|
320
|
+
* **When it runs:** Fires inside `OrderRefund::afterDispatch()` immediately after the generic `order_refunded` hook, but only when the total refunded amount is less than the order's total paid amount (i.e. partial refund).
|
|
321
|
+
* **Source:** `app/Events/Order/OrderRefund.php` (line 146)
|
|
322
|
+
|
|
323
|
+
#### Parameters:
|
|
324
|
+
`$data` *(array)*: Partial refund data (identical structure to `order_refunded`)
|
|
325
|
+
```php
|
|
326
|
+
$data = [
|
|
327
|
+
'order' => $order, // \FluentCart\App\Models\Order
|
|
328
|
+
'refunded_items' => [], // Array of OrderItem models
|
|
329
|
+
'new_refunded_items' => [], // Raw refunded items with restore_quantity
|
|
330
|
+
'refunded_amount' => 3000, // Refunded amount in cents
|
|
331
|
+
'manage_stock' => true, // Whether stock should be restored
|
|
332
|
+
'transaction' => $transaction, // \FluentCart\App\Models\OrderTransaction
|
|
333
|
+
'customer' => $customer, // \FluentCart\App\Models\Customer
|
|
334
|
+
'type' => 'partial', // Always 'partial' for this hook
|
|
335
|
+
];
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
#### Usage Example:
|
|
339
|
+
```php
|
|
340
|
+
// Hook into partial order refund event
|
|
341
|
+
add_action('fluent_cart/order_partially_refunded', function ($data) {
|
|
342
|
+
// Extract order and customer models from event data
|
|
343
|
+
$order = $data['order'];
|
|
344
|
+
$customer = $data['customer'];
|
|
345
|
+
// Notify customer of partial refund via email
|
|
346
|
+
wp_mail(
|
|
347
|
+
$customer->email,
|
|
348
|
+
'Partial Refund Processed',
|
|
349
|
+
sprintf('A partial refund has been issued for Order #%d.', $order->id)
|
|
350
|
+
);
|
|
351
|
+
}, 10, 1);
|
|
352
|
+
```
|
|
353
|
+
|
|
354
|
+
---
|
|
355
|
+
|
|
356
|
+
## Order Items
|
|
357
|
+
Hooks that fire when custom line items on an order are being deleted. These are useful for cleanup or audit logging on custom `OrderItem` records.
|
|
358
|
+
|
|
359
|
+
### `order/before_custom_items_deleted`
|
|
360
|
+
`fluent_cart/order/before_custom_items_deleted` — Fires before custom line items are deleted
|
|
361
|
+
|
|
362
|
+
* **When it runs:** Fires inside `OrderResource::updateOrderItems()` just before custom order items (flagged as `is_custom`) are permanently deleted from the database. Only fires if the filtered collection of custom items is not empty.
|
|
363
|
+
* **Source:** `api/Resource/OrderResource.php` (line 535)
|
|
364
|
+
|
|
365
|
+
#### Parameters:
|
|
366
|
+
* `$customItems` *(\Illuminate\Support\Collection)*: Collection of `\FluentCart\App\Models\OrderItem` models about to be deleted (only items where `is_custom` is `true`)
|
|
367
|
+
* `$order` *(\FluentCart\App\Models\Order)*: The parent order model
|
|
368
|
+
|
|
369
|
+
#### Usage Example:
|
|
370
|
+
```php
|
|
371
|
+
// Hook before custom order items are deleted
|
|
372
|
+
add_action('fluent_cart/order/before_custom_items_deleted', function ($customItems, $order) {
|
|
373
|
+
// Archive custom items before they are removed from the database
|
|
374
|
+
foreach ($customItems as $item) {
|
|
375
|
+
fluent_cart_add_log(
|
|
376
|
+
'Custom item removed',
|
|
377
|
+
sprintf('Item "%s" removed from Order #%d', $item->title, $order->id),
|
|
378
|
+
'info'
|
|
379
|
+
);
|
|
380
|
+
}
|
|
381
|
+
}, 10, 2);
|
|
382
|
+
```
|
|
383
|
+
|
|
384
|
+
---
|
|
385
|
+
|
|
386
|
+
### `order/after_custom_items_deleted`
|
|
387
|
+
`fluent_cart/order/after_custom_items_deleted` — Fires after custom line items are deleted
|
|
388
|
+
|
|
389
|
+
* **When it runs:** Fires inside `OrderResource::updateOrderItems()` immediately after custom order items have been permanently deleted from the database. The collection still holds the model instances (now removed from DB). Only fires if the collection is not empty.
|
|
390
|
+
* **Source:** `api/Resource/OrderResource.php` (line 541)
|
|
391
|
+
|
|
392
|
+
#### Parameters:
|
|
393
|
+
* `$customItems` *(\Illuminate\Support\Collection)*: Collection of `\FluentCart\App\Models\OrderItem` models that were just deleted
|
|
394
|
+
* `$order` *(\FluentCart\App\Models\Order)*: The parent order model
|
|
395
|
+
|
|
396
|
+
#### Usage Example:
|
|
397
|
+
```php
|
|
398
|
+
// Hook after custom order items are deleted
|
|
399
|
+
add_action('fluent_cart/order/after_custom_items_deleted', function ($customItems, $order) {
|
|
400
|
+
// Recalculate order totals after custom items are removed
|
|
401
|
+
$order->recalculateTotals();
|
|
402
|
+
}, 10, 2);
|
|
403
|
+
```
|
|
404
|
+
|
|
405
|
+
---
|
|
406
|
+
|
|
407
|
+
## Order Lifecycle
|
|
408
|
+
General lifecycle hooks that fire at key moments during an Order's existence: invoice generation, Customer changes, payment completion, license generation, and receipt viewing.
|
|
409
|
+
|
|
410
|
+
### `order/invoice_number_added`
|
|
411
|
+
`fluent_cart/order/invoice_number_added` — Fires after an invoice/receipt number is assigned to an order
|
|
412
|
+
|
|
413
|
+
* **When it runs:** Fires in two places:
|
|
414
|
+
1. Inside the `Order::booted()` created callback, immediately after a new order is persisted to the database with an invoice number already set (when payment status is `paid` at creation time).
|
|
415
|
+
2. Inside `Order::generateReceiptNumber()`, when a receipt number is generated for an existing order that did not previously have one.
|
|
416
|
+
* **Source:** `app/Models/Order.php` (lines 60 and 734)
|
|
417
|
+
|
|
418
|
+
#### Parameters:
|
|
419
|
+
`$data` *(array)*: Order data
|
|
420
|
+
```php
|
|
421
|
+
$data = [
|
|
422
|
+
'order' => $order, // \FluentCart\App\Models\Order
|
|
423
|
+
];
|
|
424
|
+
```
|
|
425
|
+
|
|
426
|
+
#### Usage Example:
|
|
427
|
+
```php
|
|
428
|
+
// Hook when invoice/receipt number is assigned to an order
|
|
429
|
+
add_action('fluent_cart/order/invoice_number_added', function ($data) {
|
|
430
|
+
// Extract order model from event data
|
|
431
|
+
$order = $data['order'];
|
|
432
|
+
// Sync invoice number to external accounting system
|
|
433
|
+
sync_to_accounting($order->id, $order->invoice_no, $order->receipt_number);
|
|
434
|
+
}, 10, 1);
|
|
435
|
+
```
|
|
436
|
+
|
|
437
|
+
---
|
|
438
|
+
|
|
439
|
+
### `order_customer_changed`
|
|
440
|
+
`fluent_cart/order_customer_changed` — Fires when the customer assigned to an order changes
|
|
441
|
+
|
|
442
|
+
* **When it runs:** Fires inside `OrderController::changeCustomer()` after the order (and any child orders and subscriptions) have been reassigned to a new customer, and both the old and new customer stats have been recounted.
|
|
443
|
+
* **Source:** `app/Http/Controllers/OrderController.php` (line 427)
|
|
444
|
+
|
|
445
|
+
#### Parameters:
|
|
446
|
+
`$data` *(array)*: Customer change data
|
|
447
|
+
```php
|
|
448
|
+
$data = [
|
|
449
|
+
'order' => $order, // \FluentCart\App\Models\Order
|
|
450
|
+
'old_customer' => $oldCustomer, // \FluentCart\App\Models\Customer|null
|
|
451
|
+
'new_customer' => $newCustomer, // \FluentCart\App\Models\Customer
|
|
452
|
+
'connected_order_ids' => [123, 124], // Array of all order IDs updated (parent + children)
|
|
453
|
+
];
|
|
454
|
+
```
|
|
455
|
+
|
|
456
|
+
#### Usage Example:
|
|
457
|
+
```php
|
|
458
|
+
// Hook when the customer assigned to an order changes
|
|
459
|
+
add_action('fluent_cart/order_customer_changed', function ($data) {
|
|
460
|
+
// Extract order and customer models from event data
|
|
461
|
+
$order = $data['order'];
|
|
462
|
+
$oldCustomer = $data['old_customer'];
|
|
463
|
+
$newCustomer = $data['new_customer'];
|
|
464
|
+
// Notify the new customer about the order account transfer
|
|
465
|
+
wp_mail(
|
|
466
|
+
$newCustomer->email,
|
|
467
|
+
'Order Transferred to Your Account',
|
|
468
|
+
sprintf('Order #%d has been assigned to your account.', $order->id)
|
|
469
|
+
);
|
|
470
|
+
}, 10, 1);
|
|
471
|
+
```
|
|
472
|
+
|
|
473
|
+
---
|
|
474
|
+
|
|
475
|
+
### `order/generateMissingLicenses`
|
|
476
|
+
`fluent_cart/order/generateMissingLicenses` — Fires when an admin triggers license generation for an order
|
|
477
|
+
|
|
478
|
+
* **When it runs:** Fires inside `OrderController::generateLicense()` when an admin requests license generation for an order that has fewer licenses than expected. This allows license modules to hook in and create the missing license keys.
|
|
479
|
+
* **Source:** `app/Http/Controllers/OrderController.php` (line 225)
|
|
480
|
+
|
|
481
|
+
#### Parameters:
|
|
482
|
+
`$data` *(array)*: Order data
|
|
483
|
+
```php
|
|
484
|
+
$data = [
|
|
485
|
+
'order' => $order, // \FluentCart\App\Models\Order (with order_items and licenses loaded)
|
|
486
|
+
];
|
|
487
|
+
```
|
|
488
|
+
|
|
489
|
+
#### Usage Example:
|
|
490
|
+
```php
|
|
491
|
+
// Hook when admin requests missing license generation for an order
|
|
492
|
+
add_action('fluent_cart/order/generateMissingLicenses', function ($data) {
|
|
493
|
+
// Extract order model from event data
|
|
494
|
+
$order = $data['order'];
|
|
495
|
+
// Generate licenses for each eligible order item
|
|
496
|
+
foreach ($order->order_items as $item) {
|
|
497
|
+
generate_license_key($order->id, $item->product_id);
|
|
498
|
+
}
|
|
499
|
+
}, 10, 1);
|
|
500
|
+
```
|
|
501
|
+
|
|
502
|
+
---
|
|
503
|
+
|
|
504
|
+
### `order_placed_offline`
|
|
505
|
+
`fluent_cart/order_placed_offline` — Fires when an order is placed via Cash on Delivery or other offline payment
|
|
506
|
+
|
|
507
|
+
* **When it runs:** Fires inside `CodHandler::processPayment()` after the order and its transaction have been created for an offline/COD payment. The Order, Customer, and transaction data are all available at this point. The order has its `customer`, `shipping_address`, and `billing_address` relationships loaded.
|
|
508
|
+
* **Source:** `app/Modules/PaymentMethods/Cod/CodHandler.php` (line 55)
|
|
509
|
+
|
|
510
|
+
#### Parameters:
|
|
511
|
+
`$data` *(array)*: Offline order data
|
|
512
|
+
```php
|
|
513
|
+
$data = [
|
|
514
|
+
'order' => $order, // \FluentCart\App\Models\Order
|
|
515
|
+
'customer' => $order->customer ?? [], // \FluentCart\App\Models\Customer or empty array
|
|
516
|
+
'transaction' => $transaction ?? [], // \FluentCart\App\Models\OrderTransaction or empty array
|
|
517
|
+
];
|
|
518
|
+
```
|
|
519
|
+
|
|
520
|
+
#### Usage Example:
|
|
521
|
+
```php
|
|
522
|
+
// Hook when an order is placed via Cash on Delivery or offline payment
|
|
523
|
+
add_action('fluent_cart/order_placed_offline', function ($data) {
|
|
524
|
+
// Extract order model from event data
|
|
525
|
+
$order = $data['order'];
|
|
526
|
+
// Notify warehouse of new COD order
|
|
527
|
+
wp_mail(
|
|
528
|
+
'warehouse@example.com',
|
|
529
|
+
sprintf('New COD Order #%d', $order->id),
|
|
530
|
+
'A new Cash on Delivery order needs to be prepared for shipment.'
|
|
531
|
+
);
|
|
532
|
+
}, 10, 1);
|
|
533
|
+
```
|
|
534
|
+
|
|
535
|
+
---
|
|
536
|
+
|
|
537
|
+
### `order_paid_done`
|
|
538
|
+
`fluent_cart/order_paid_done` — Main lifecycle hook when order payment completes (recommended for integrations)
|
|
539
|
+
|
|
540
|
+
* **When it runs:** Fires asynchronously via Action Scheduler after an order's payment is confirmed as paid. The `OrderPaid` event enqueues a `fluent_cart/order_paid_ansyc_private_handle` async action, which validates the order is still paid, then dispatches this hook. This is the recommended hook for third-party integrations because it runs outside the payment gateway request cycle, avoiding race conditions and timeouts. For subscription or renewal orders, the associated Subscription model is included in the data.
|
|
541
|
+
* **Note:** The `subscription` key is only present when the order type is subscription or renewal.
|
|
542
|
+
* **Source:** `app/Hooks/actions.php` (line 159)
|
|
543
|
+
|
|
544
|
+
#### Parameters:
|
|
545
|
+
`$data` *(array)*: Order payment completion data
|
|
546
|
+
```php
|
|
547
|
+
$data = [
|
|
548
|
+
'order' => $order, // \FluentCart\App\Models\Order
|
|
549
|
+
'transaction' => $transaction, // \FluentCart\App\Models\OrderTransaction (latest successful transaction)
|
|
550
|
+
'customer' => $customer, // \FluentCart\App\Models\Customer
|
|
551
|
+
'subscription' => $subscription, // \FluentCart\App\Models\Subscription (only for subscription/renewal orders)
|
|
552
|
+
];
|
|
553
|
+
```
|
|
554
|
+
|
|
555
|
+
#### Usage Example:
|
|
556
|
+
```php
|
|
557
|
+
// Main lifecycle hook when order payment completes (recommended for integrations)
|
|
558
|
+
add_action('fluent_cart/order_paid_done', function ($data) {
|
|
559
|
+
// Extract order and customer models from event data
|
|
560
|
+
$order = $data['order'];
|
|
561
|
+
$customer = $data['customer'];
|
|
562
|
+
|
|
563
|
+
// Grant membership access after payment
|
|
564
|
+
update_user_meta($customer->user_id, 'membership_active', true);
|
|
565
|
+
|
|
566
|
+
// Handle subscription orders differently if subscription instance exists
|
|
567
|
+
if (!empty($data['subscription'])) {
|
|
568
|
+
$subscription = $data['subscription'];
|
|
569
|
+
update_user_meta($customer->user_id, 'subscription_id', $subscription->id);
|
|
570
|
+
}
|
|
571
|
+
}, 10, 1);
|
|
572
|
+
```
|
|
573
|
+
|
|
574
|
+
---
|
|
575
|
+
|
|
576
|
+
### `order_paid_ansyc_private_handle`
|
|
577
|
+
`fluent_cart/order_paid_ansyc_private_handle` — Internal async handler that processes post-payment integrations
|
|
578
|
+
|
|
579
|
+
* **When it runs:** Enqueued by `OrderPaid::afterDispatch()` as an Action Scheduler async action. The handler in `app/Hooks/actions.php` validates the order, clears the scheduler meta, and then dispatches `fluent_cart/order_paid_done`. It is also dispatched manually in `IntegrationEventListener` for retry scenarios. You should generally hook into `order_paid_done` instead of this hook.
|
|
580
|
+
* **Source:** `app/Listeners/IntegrationEventListener.php` (line 360), `app/Hooks/actions.php` (line 126)
|
|
581
|
+
|
|
582
|
+
#### Parameters:
|
|
583
|
+
`$data` *(array)*: Order identifier
|
|
584
|
+
```php
|
|
585
|
+
$data = [
|
|
586
|
+
'order_id' => 123, // int: The order ID to process
|
|
587
|
+
];
|
|
588
|
+
```
|
|
589
|
+
|
|
590
|
+
#### Usage Example:
|
|
591
|
+
```php
|
|
592
|
+
// Internal async handler (Not recommended for third-party use; use fluent_cart/order_paid_done instead)
|
|
593
|
+
add_action('fluent_cart/order_paid_ansyc_private_handle', function ($data) {
|
|
594
|
+
// Extract order ID from event data
|
|
595
|
+
$orderId = $data['order_id'];
|
|
596
|
+
// Internal processing only
|
|
597
|
+
}, 10, 1);
|
|
598
|
+
```
|
|
599
|
+
|
|
600
|
+
---
|
|
601
|
+
|
|
602
|
+
### `order/receipt_viewed`
|
|
603
|
+
`fluent_cart/order/receipt_viewed` — Fires the first time a customer views their order receipt
|
|
604
|
+
|
|
605
|
+
* **When it runs:** Fires at the end of receipt rendering (both the `ReceiptRenderer` class and the `receipt_slip.php` view template) when the `$is_first_time` flag is `true`. This means it only fires once per order, the very first time the receipt page is loaded. Subsequent views do not trigger this hook. The data includes both the Order and OrderOperation models.
|
|
606
|
+
* **Source:** `app/Services/Renderer/Receipt/ReceiptRenderer.php` (line 151), `app/Views/invoice/receipt_slip.php` (line 482)
|
|
607
|
+
|
|
608
|
+
#### Parameters:
|
|
609
|
+
`$data` *(array)*: Receipt view data
|
|
610
|
+
```php
|
|
611
|
+
$data = [
|
|
612
|
+
'order' => $order, // \FluentCart\App\Models\Order
|
|
613
|
+
'order_operation' => $order_operation, // \FluentCart\App\Models\OrderOperation
|
|
614
|
+
];
|
|
615
|
+
```
|
|
616
|
+
|
|
617
|
+
#### Usage Example:
|
|
618
|
+
```php
|
|
619
|
+
// Hook when customer views their order receipt for the first time
|
|
620
|
+
add_action('fluent_cart/order/receipt_viewed', function ($data) {
|
|
621
|
+
// Extract order model from event data
|
|
622
|
+
$order = $data['order'];
|
|
623
|
+
// Track receipt view for analytics logging
|
|
624
|
+
fluent_cart_add_log(
|
|
625
|
+
'Receipt viewed',
|
|
626
|
+
sprintf('Customer viewed receipt for Order #%d', $order->id),
|
|
627
|
+
'info',
|
|
628
|
+
['module_name' => 'order', 'module_id' => $order->id]
|
|
629
|
+
);
|
|
630
|
+
}, 10, 1);
|
|
631
|
+
```
|