fluentcart-developer 2.3.0 → 2.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/README.md +59 -59
  2. package/dist/cards/fluentcart/tools.d.ts.map +1 -1
  3. package/dist/cards/fluentcart/tools.js +160 -12
  4. package/dist/cards/fluentcart/tools.js.map +1 -1
  5. package/dist/skills/fluentcart-developer/.claude-plugin/plugin.json +12 -12
  6. package/dist/skills/fluentcart-developer/.mcp.json +11 -11
  7. package/dist/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/fluent-cart/checkout.php +32 -32
  8. package/dist/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/functions.php +40 -40
  9. package/dist/skills/fluentcart-developer/examples/sample-fee-surcharge-plugin/fluentcart-fee-surcharge.php +38 -38
  10. package/dist/skills/fluentcart-developer/references/action-hooks-cart-checkout.md +1355 -1355
  11. package/dist/skills/fluentcart-developer/references/action-hooks-customers-users.md +266 -266
  12. package/dist/skills/fluentcart-developer/references/action-hooks-licenses.md +855 -855
  13. package/dist/skills/fluentcart-developer/references/action-hooks-orders.md +631 -631
  14. package/dist/skills/fluentcart-developer/references/action-hooks-payments-integrations.md +963 -963
  15. package/dist/skills/fluentcart-developer/references/action-hooks-products-coupons.md +585 -585
  16. package/dist/skills/fluentcart-developer/references/action-hooks-subscriptions.md +661 -661
  17. package/dist/skills/fluentcart-developer/references/database-models-query-builder.md +194 -194
  18. package/dist/skills/fluentcart-developer/references/database-models-reference.md +604 -604
  19. package/dist/skills/fluentcart-developer/references/engineering-notes.md +154 -154
  20. package/dist/skills/fluentcart-developer/references/fee-system-guide.md +449 -449
  21. package/dist/skills/fluentcart-developer/references/filter-hooks-cart-checkout.md +1202 -1202
  22. package/dist/skills/fluentcart-developer/references/filter-hooks-integrations-advanced.md +1598 -1598
  23. package/dist/skills/fluentcart-developer/references/filter-hooks-products-pricing.md +628 -628
  24. package/dist/skills/fluentcart-developer/references/filter-hooks-settings-configuration.md +1177 -1177
  25. package/dist/skills/fluentcart-developer/references/fluentcart-developer-guide.md +154 -154
  26. package/dist/skills/fluentcart-developer/references/ghost-product-selling.md +458 -458
  27. package/dist/skills/fluentcart-developer/references/modules-and-extensions-reference.md +224 -224
  28. package/dist/skills/fluentcart-developer/references/payment-gateway-integration.md +761 -761
  29. package/dist/skills/fluentcart-developer/references/rest-api-customer-profile.md +190 -190
  30. package/dist/skills/fluentcart-developer/references/rest-api-customers.md +1121 -1121
  31. package/dist/skills/fluentcart-developer/references/rest-api-dashboard-utilities.md +219 -219
  32. package/dist/skills/fluentcart-developer/references/rest-api-email-notifications.md +619 -619
  33. package/dist/skills/fluentcart-developer/references/rest-api-files.md +290 -290
  34. package/dist/skills/fluentcart-developer/references/rest-api-integrations.md +324 -324
  35. package/dist/skills/fluentcart-developer/references/rest-api-labels-attributes.md +321 -321
  36. package/dist/skills/fluentcart-developer/references/rest-api-order-bumps.md +200 -200
  37. package/dist/skills/fluentcart-developer/references/rest-api-overview.md +131 -131
  38. package/dist/skills/fluentcart-developer/references/rest-api-public-shop.md +172 -172
  39. package/dist/skills/fluentcart-developer/references/rest-api-reference.md +552 -552
  40. package/dist/skills/fluentcart-developer/references/rest-api-reports.md +377 -377
  41. package/dist/skills/fluentcart-developer/references/rest-api-roles-permissions.md +147 -147
  42. package/dist/skills/fluentcart-developer/references/rest-api-settings.md +528 -528
  43. package/dist/skills/fluentcart-developer/references/rest-api-shipping.md +799 -799
  44. package/dist/skills/fluentcart-developer/references/rest-api-tax.md +356 -356
  45. package/dist/skills/fluentcart-developer/references/subscription-customization.md +197 -197
  46. package/dist/skills/fluentcart-developer/scripts/cli.js +1 -1
  47. package/dist/version.d.ts +1 -1
  48. package/dist/version.js +1 -1
  49. package/package.json +65 -65
@@ -1,1355 +1,1355 @@
1
- # Action Hooks: Cart & Checkout
2
-
3
- All hooks related to the shopping flow — from adding items to the Cart through checkout rendering and the receipt/thank-you page.
4
-
5
- ---
6
-
7
- ## Cart Events
8
-
9
- ### `item_added`
10
- `fluent_cart/cart/item_added` — Fired after an item is added to the cart
11
-
12
- * **When it runs:** This action fires immediately after a product item has been successfully added to the Cart model and saved to the database. It runs before the `cart_data_items_updated` hook with the `item_added` scope.
13
- * **Source:** `app/Models/Cart.php`
14
-
15
- #### Parameters:
16
- `$data` *(array)*: Cart and item data
17
- ```php
18
- $data = [
19
- 'cart' => $cart, // \FluentCart\App\Models\Cart instance
20
- 'item' => $item, // array — the cart item that was just added
21
- ];
22
- ```
23
-
24
- #### Usage Example:
25
- ```php
26
- // Hook after an item is added to the cart
27
- add_action('fluent_cart/cart/item_added', function ($data) {
28
- // Extract cart model and item array from event data
29
- $cart = $data['cart'];
30
- $item = $data['item'];
31
-
32
- // Log the added product for analytics
33
- error_log('Product ' . $item['post_id'] . ' added to cart #' . $cart->id);
34
- }, 10, 1);
35
- ```
36
-
37
- ---
38
-
39
- ### `item_removed`
40
- `fluent_cart/cart/item_removed` — Fired after an item is removed from the cart
41
-
42
- * **When it runs:** This action fires after a product item has been removed from the Cart and saved, but only when the `$triggerEvent` parameter is `true` (the default). When an item is removed silently (e.g., during a replacement operation), this hook does not fire.
43
- * **Source:** `app/Models/Cart.php`
44
-
45
- #### Parameters:
46
- `$data` *(array)*: Cart and removal context
47
- ```php
48
- $data = [
49
- 'cart' => $cart, // \FluentCart\App\Models\Cart instance
50
- 'variation_id' => $variationId, // int — the variation ID that was removed
51
- 'extra_args' => $extraArgs, // array — additional matching arguments
52
- 'removed_item' => $removingItem, // array — the full cart item that was removed
53
- ];
54
- ```
55
-
56
- #### Usage Example:
57
- ```php
58
- // Hook after an item is removed from the cart
59
- add_action('fluent_cart/cart/item_removed', function ($data) {
60
- // Extract removed item array and cart model from event data
61
- $removedItem = $data['removed_item'];
62
- $cart = $data['cart'];
63
-
64
- // Track removal for abandoned cart analytics
65
- do_action('my_plugin/track_cart_removal', [
66
- 'variation_id' => $data['variation_id'],
67
- 'product_id' => $removedItem['post_id'] ?? null,
68
- 'cart_id' => $cart->id,
69
- ]);
70
- }, 10, 1);
71
- ```
72
-
73
- ---
74
-
75
- ### `cart_data_items_updated`
76
- `fluent_cart/cart/cart_data_items_updated` — General-purpose hook for any cart data change
77
-
78
- * **When it runs:** This action fires whenever the cart data array is modified. The `scope` field tells you what operation triggered the update. It fires on item add, item remove, coupon apply, coupon remove, discount recalculation, and checkout page loading.
79
- * **Source:** `app/Models/Cart.php`, `app/Hooks/Handlers/ShortCodes/Checkout/CheckoutPageHandler.php`
80
-
81
- #### Parameters:
82
- `$data` *(array)*: Cart and scope context
83
- ```php
84
- $data = [
85
- 'cart' => $cart, // \FluentCart\App\Models\Cart instance
86
- 'scope' => 'item_added', // string — one of the scope values below
87
- 'scope_data' => $scopeData, // mixed — context data depending on scope
88
- ];
89
- ```
90
-
91
- #### Possible Scope Values and `scope_data`:
92
- | Scope | `scope_data` Description |
93
- |---|---|
94
- | `'item_added'` | The cart item array that was added |
95
- | `'item_removed'` | The variation ID (`int`) that was removed |
96
- | `'discounts_recalculated'` | Array of applied coupon codes |
97
- | `'remove_coupon'` | Array of coupon codes that were removed |
98
- | `'apply_coupons'` | Array of coupon codes that were applied |
99
- | `'loading'` | Empty string (fired on checkout page load) |
100
-
101
- #### Usage Example:
102
- ```php
103
- // General-purpose hook for any cart data change
104
- add_action('fluent_cart/cart/cart_data_items_updated', function ($data) {
105
- // Extract cart model and update scope string
106
- $cart = $data['cart'];
107
- $scope = $data['scope'];
108
-
109
- // Recalculate custom surcharges when cart items change
110
- if ($scope === 'item_added' || $scope === 'item_removed') {
111
- my_plugin_recalculate_surcharges($cart);
112
- }
113
-
114
- // Log applied coupons if scope is apply_coupons
115
- if ($scope === 'apply_coupons') {
116
- error_log('Coupons applied to cart #' . $cart->id . ': ' . implode(', ', $data['scope_data']));
117
- }
118
- }, 10, 1);
119
- ```
120
-
121
- ---
122
-
123
- ### `cart_completed`
124
- `fluent_cart/cart_completed` — Fired when a cart is marked as completed after payment
125
-
126
- * **When it runs:** This action fires when the cart's stage is set to `completed` after a successful Order payment. The cart's `completed_at` timestamp has already been saved at this point. This is triggered inside `StatusHelper` during order status transitions when payment is marked as paid.
127
- * **Source:** `app/Helpers/StatusHelper.php`
128
-
129
- #### Parameters:
130
- `$data` *(array)*: Completed cart and associated order
131
- ```php
132
- $data = [
133
- 'cart' => $relatedCart, // \FluentCart\App\Models\Cart instance (stage = 'completed')
134
- 'order' => $order, // \FluentCart\App\Models\Order instance
135
- ];
136
- ```
137
-
138
- #### Usage Example:
139
- ```php
140
- // Hook when a cart is marked as completed after payment
141
- add_action('fluent_cart/cart_completed', function ($data) {
142
- // Extract completed cart and associated order models
143
- $cart = $data['cart'];
144
- $order = $data['order'];
145
-
146
- // Fire a conversion pixel or sync to analytics
147
- my_plugin_track_conversion([
148
- 'order_id' => $order->id,
149
- 'total' => $order->total_amount,
150
- 'customer_id' => $order->customer_id,
151
- ]);
152
- }, 10, 1);
153
- ```
154
-
155
- ---
156
-
157
- ## Checkout Data Events
158
-
159
- ### `prepare_other_data`
160
- `fluent_cart/checkout/prepare_other_data` — After order creation, before finalizing
161
-
162
- * **When it runs:** This action fires during the checkout submission flow, after the draft Order has been created but before it is finalized (before addresses and items are attached). This gives modules a chance to attach additional data to the order.
163
- * **Source:** `api/Checkout/CheckoutApi.php`
164
-
165
- #### Parameters:
166
- `$data` *(array)*: Full checkout context
167
- ```php
168
- $data = [
169
- 'cart' => $cart, // \FluentCart\App\Models\Cart instance
170
- 'order' => $createdOrder, // \FluentCart\App\Models\Order — the newly created draft order
171
- 'prev_order' => $prevOrder, // \FluentCart\App\Models\Order|null — previous order if retrying
172
- 'request_data' => $data, // array — raw validated request data from checkout form
173
- 'validated_data' => $validatedData, // array — sanitized/validated checkout field values
174
- ];
175
- ```
176
-
177
- #### Usage Example:
178
- ```php
179
- // Hook after draft order creation, before finalizing checkout
180
- add_action('fluent_cart/checkout/prepare_other_data', function ($data) {
181
- // Extract draft order and request data array
182
- $order = $data['order'];
183
- $requestData = $data['request_data'];
184
-
185
- // Attach custom metadata to the order before it finalizes
186
- $customField = sanitize_text_field($requestData['custom_gift_message'] ?? '');
187
- if ($customField) {
188
- $order->updateMeta('gift_message', $customField);
189
- }
190
- }, 10, 1);
191
- ```
192
-
193
- ---
194
-
195
- ### `cart_amount_updated`
196
- `fluent_cart/checkout/cart_amount_updated` — Fired when the cart total may have changed
197
-
198
- * **When it runs:** This action fires whenever an operation changes (or may change) the cart total. This includes: item removal (silent mode), coupon application, coupon removal, discount recalculation, quantity updates, order bump toggles, and tax recalculations. Use this hook to react to price changes regardless of the specific cause.
199
- * **Source:** `app/Models/Cart.php`, `app/Hooks/Cart/WebCheckoutHandler.php`, `app/Modules/Tax/TaxModule.php`
200
-
201
- #### Parameters:
202
- `$data` *(array)*: The affected cart
203
- ```php
204
- $data = [
205
- 'cart' => $cart, // \FluentCart\App\Models\Cart instance
206
- ];
207
- ```
208
-
209
- #### Usage Example:
210
- ```php
211
- // Hook when the cart total amount is updated
212
- add_action('fluent_cart/checkout/cart_amount_updated', function ($data) {
213
- // Extract cart model instance
214
- $cart = $data['cart'];
215
-
216
- // Recalculate a custom fee based on the new cart total
217
- $estimatedTotal = $cart->getEstimatedTotal();
218
- if ($estimatedTotal > 10000) { // over $100.00 in cents
219
- // Apply free shipping threshold logic
220
- my_plugin_apply_free_shipping($cart);
221
- }
222
- }, 10, 1);
223
- ```
224
-
225
- ---
226
-
227
- ### `shipping_data_changed`
228
- `fluent_cart/checkout/shipping_data_changed` — Fired when shipping data changes
229
-
230
- * **When it runs:** This action fires when shipping-related data on the cart changes, such as when a new shipping method is selected, the shipping charge changes, or the shipping address is updated in a way that affects shipping calculations.
231
- * **Source:** `app/Helpers/CartHelper.php`, `app/Hooks/Cart/WebCheckoutHandler.php`
232
-
233
- #### Parameters:
234
- `$data` *(array)*: The affected cart
235
- ```php
236
- $data = [
237
- 'cart' => $cart, // \FluentCart\App\Models\Cart instance
238
- ];
239
- ```
240
-
241
- #### Usage Example:
242
- ```php
243
- // Hook when shipping-related data on the cart changes
244
- add_action('fluent_cart/checkout/shipping_data_changed', function ($data) {
245
- // Extract cart model and shipping data array
246
- $cart = $data['cart'];
247
- $shippingData = $cart->checkout_data['shipping_data'] ?? [];
248
-
249
- // Log shipping method selection for analytics
250
- error_log('Cart #' . $cart->id . ' shipping method: ' . ($shippingData['shipping_method_id'] ?? 'none'));
251
- }, 10, 1);
252
- ```
253
-
254
- ---
255
-
256
- ### `form_data_changed`
257
- `fluent_cart/checkout/form_data_changed` — Fired when checkout form data changes
258
-
259
- * **When it runs:** This action fires when the checkout form data is updated via AJAX, such as when a customer changes their address, toggles "ship to different address", or any form field is updated that triggers a server-side recalculation.
260
- * **Source:** `app/Hooks/Cart/WebCheckoutHandler.php`
261
-
262
- #### Parameters:
263
- `$data` *(array)*: The affected cart
264
- ```php
265
- $data = [
266
- 'cart' => $cart, // \FluentCart\App\Models\Cart instance
267
- ];
268
- ```
269
-
270
- #### Usage Example:
271
- ```php
272
- // Hook when checkout form data is updated via AJAX
273
- add_action('fluent_cart/checkout/form_data_changed', function ($data) {
274
- // Extract cart model and checkout form data array
275
- $cart = $data['cart'];
276
- $formData = $cart->checkout_data['form_data'] ?? [];
277
-
278
- // Check if the billing country requires special handling
279
- $billingCountry = $formData['billing_country'] ?? '';
280
- if (in_array($billingCountry, ['BR', 'IN'])) {
281
- // Add country-specific checkout notices
282
- my_plugin_add_country_notice($cart, $billingCountry);
283
- }
284
- }, 10, 1);
285
- ```
286
-
287
- ---
288
-
289
- ### `customer_data_saved`
290
- `fluent_cart/checkout/customer_data_saved` — Fired when customer checkout data is saved
291
-
292
- * **When it runs:** This action fires when a specific piece of customer data is saved during the checkout process. The hook provides both the old and new values, making it useful for detecting changes. It fires after the data has already been persisted to the cart model.
293
- * **Source:** `app/Hooks/Cart/WebCheckoutHandler.php`
294
-
295
- #### Parameters:
296
- `$data` *(array)*: Customer data change context
297
- ```php
298
- $data = [
299
- 'cart' => $cart, // \FluentCart\App\Models\Cart instance
300
- 'key' => $key, // string — the data key that changed (e.g. 'billing_country')
301
- 'value' => $value, // mixed — the new value
302
- 'old_value' => $prevValue, // mixed — the previous value
303
- 'old_data' => $oldCheckoutData, // array — the full previous checkout_data array
304
- ];
305
- ```
306
-
307
- #### Usage Example:
308
- ```php
309
- // Hook when customer checkout data key is saved
310
- add_action('fluent_cart/checkout/customer_data_saved', function ($data) {
311
- // Extract cart model and change key metadata
312
- $cart = $data['cart'];
313
- $key = $data['key'];
314
-
315
- // React to billing country changes for tax recalculation
316
- if ($key === 'billing_country' && $data['value'] !== $data['old_value']) {
317
- error_log('Cart #' . $cart->id . ' billing country changed from '
318
- . $data['old_value'] . ' to ' . $data['value']);
319
- }
320
- }, 10, 1);
321
- ```
322
-
323
- ---
324
-
325
- ### `tax/reverse_charge_applied`
326
- `fluent_cart/tax/reverse_charge_applied` — Fired when the EU VAT reverse charge is applied to the cart
327
-
328
- * **When it runs:** This action fires during cart tax calculation (`TaxModule::calculateCartTax()`) when the reverse charge mechanism has just been applied — a qualifying business customer (e.g. validated EU VAT number) is liable for the VAT, so tax has been removed and inclusive product lines and fees have been adjusted to net prices. It fires after those adjustments are written into the cart's checkout data.
329
- * **Source:** `app/Modules/Tax/TaxModule.php` (line 750)
330
-
331
- #### Parameters:
332
- `$data` *(array)*: Reverse charge context
333
- ```php
334
- $data = [
335
- 'checkout_data' => $checkoutData, // array — the cart's checkout_data (includes the updated 'tax_data')
336
- 'product_lines' => $productLines, // array — cart product line items, already adjusted to net prices
337
- ];
338
- ```
339
-
340
- #### Usage Example:
341
- ```php
342
- // Hook when EU VAT reverse charge is applied to the cart
343
- add_action('fluent_cart/tax/reverse_charge_applied', function ($data) {
344
- // Extract tax data array from checkout data
345
- $taxData = $data['checkout_data']['tax_data'] ?? [];
346
-
347
- // Log or sync with an external tax service
348
- my_tax_service_flag_reverse_charge($taxData);
349
- }, 10, 1);
350
- ```
351
-
352
- ---
353
-
354
- ### `tax/reverse_charge_removed`
355
- `fluent_cart/tax/reverse_charge_removed` — Fired when the EU VAT reverse charge is removed from the cart
356
-
357
- * **When it runs:** This action fires during cart tax calculation (`TaxModule::calculateCartTax()`) when a previously applicable reverse charge no longer applies (e.g. the VAT number was removed or the billing country changed). Product lines have already been restored to gross prices and the reverse charge fee adjustments cleared before it fires.
358
- * **Source:** `app/Modules/Tax/TaxModule.php` (line 762)
359
-
360
- #### Parameters:
361
- `$data` *(array)*: Reverse charge context
362
- ```php
363
- $data = [
364
- 'checkout_data' => $checkoutData, // array — the cart's checkout_data (includes 'tax_data')
365
- 'product_lines' => $productLines, // array — cart product line items, restored to gross prices
366
- ];
367
- ```
368
-
369
- #### Usage Example:
370
- ```php
371
- // Hook when EU VAT reverse charge is removed from the cart
372
- add_action('fluent_cart/tax/reverse_charge_removed', function ($data) {
373
- // React to the customer no longer qualifying for reverse charge
374
- my_tax_service_clear_reverse_charge($data['checkout_data']);
375
- }, 10, 1);
376
- ```
377
-
378
- ---
379
-
380
- ## Checkout Page Rendering
381
- All hooks in this section fire during server-side HTML rendering of the checkout page. They use output buffering, so you should `echo` (not return) any custom HTML you want to inject.
382
-
383
- ### `before_checkout_page_start`
384
- `fluent_cart/before_checkout_page_start` — Before the checkout page wrapper div
385
-
386
- * **When it runs:** This action fires immediately before the main checkout page `<div>` wrapper is opened. Use it to output HTML or scripts that should appear above the entire checkout page.
387
- * **Source:** `app/Services/Renderer/CheckoutRenderer.php`
388
-
389
- #### Parameters:
390
- `$data` *(array)*: The current cart
391
- ```php
392
- $data = [
393
- 'cart' => $cart, // \FluentCart\App\Models\Cart instance
394
- ];
395
- ```
396
-
397
- #### Usage Example:
398
- ```php
399
- // Hook before the checkout page wrapper div is rendered
400
- add_action('fluent_cart/before_checkout_page_start', function ($data) {
401
- // Extract cart model instance
402
- $cart = $data['cart'];
403
- // Output custom promotional banner HTML
404
- echo '<div class="my-checkout-banner">';
405
- echo '<p>Free shipping on orders over $50!</p>';
406
- echo '</div>';
407
- }, 10, 1);
408
- ```
409
-
410
- ---
411
-
412
- ### `afrer_checkout_page_start`
413
- `fluent_cart/afrer_checkout_page_start` — After the checkout page wrapper div opens
414
-
415
- * **When it runs:** This action fires right after the main checkout page `<div>` wrapper opens. Note the typo in the hook name (`afrer` instead of `after`) — this matches the actual hook name in the source code and must be used as-is.
416
- * **Source:** `app/Services/Renderer/CheckoutRenderer.php`
417
-
418
- #### Parameters:
419
- `$data` *(array)*: The current cart
420
- ```php
421
- $data = [
422
- 'cart' => $cart, // \FluentCart\App\Models\Cart instance
423
- ];
424
- ```
425
-
426
- #### Usage Example:
427
- ```php
428
- // Hook after the checkout page wrapper div opens (note 'afrer' spelling in hook name)
429
- add_action('fluent_cart/afrer_checkout_page_start', function ($data) {
430
- // Extract cart model instance
431
- $cart = $data['cart'];
432
- // Insert a progress indicator at the top of the checkout page
433
- echo '<div class="my-checkout-progress-bar">Step 1 of 3: Checkout</div>';
434
- }, 10, 1);
435
- ```
436
-
437
- ---
438
-
439
- ### `before_checkout_form`
440
- `fluent_cart/before_checkout_form` — Before the checkout form element
441
-
442
- * **When it runs:** This action fires just before the `<form>` tag for the checkout form is rendered.
443
- * **Source:** `app/Services/Renderer/CheckoutRenderer.php`
444
-
445
- #### Parameters:
446
- `$data` *(array)*: The current cart
447
- ```php
448
- $data = [
449
- 'cart' => $cart, // \FluentCart\App\Models\Cart instance
450
- ];
451
- ```
452
-
453
- #### Usage Example:
454
- ```php
455
- // Hook before the checkout form element is rendered
456
- add_action('fluent_cart/before_checkout_form', function ($data) {
457
- // Render security and trust badges HTML
458
- echo '<div class="my-trust-badges">';
459
- echo '<img src="/wp-content/uploads/secure-checkout.svg" alt="Secure Checkout" />';
460
- echo '</div>';
461
- }, 10, 1);
462
- ```
463
-
464
- ---
465
-
466
- ### `checkout_form_opening`
467
- `fluent_cart/checkout_form_opening` — Right after the checkout form tag opens
468
-
469
- * **When it runs:** This action fires immediately after the `<form>` tag opens, before any form fields are rendered. Use it to insert hidden fields, nonce fields, or other elements that must be inside the form.
470
- * **Source:** `app/Services/Renderer/CheckoutRenderer.php`
471
-
472
- #### Parameters:
473
- `$data` *(array)*: The current cart
474
- ```php
475
- $data = [
476
- 'cart' => $cart, // \FluentCart\App\Models\Cart instance
477
- ];
478
- ```
479
-
480
- #### Usage Example:
481
- ```php
482
- // Hook right after the checkout form tag opens
483
- add_action('fluent_cart/checkout_form_opening', function ($data) {
484
- // Add a hidden input field for tracking
485
- echo '<input type="hidden" name="my_tracking_ref" value="' . esc_attr(my_get_tracking_ref()) . '" />';
486
- }, 10, 1);
487
- ```
488
-
489
- ---
490
-
491
- ### `before_billing_fields`
492
- `fluent_cart/before_billing_fields` — Before billing address fields
493
-
494
- * **When it runs:** This action fires after the name/email fields and the "create account" checkbox, but before the billing address fields section is rendered.
495
- * **Source:** `app/Services/Renderer/CheckoutRenderer.php`
496
-
497
- #### Parameters:
498
- `$data` *(array)*: The current cart
499
- ```php
500
- $data = [
501
- 'cart' => $cart, // \FluentCart\App\Models\Cart instance
502
- ];
503
- ```
504
-
505
- #### Usage Example:
506
- ```php
507
- // Hook before billing address fields section
508
- add_action('fluent_cart/before_billing_fields', function ($data) {
509
- // Output custom billing instructions paragraph
510
- echo '<p class="my-billing-note">Please enter your billing address exactly as it appears on your card statement.</p>';
511
- }, 10, 1);
512
- ```
513
-
514
- ---
515
-
516
- ### `before_billing_fields_section`
517
- `fluent_cart/before_billing_fields_section` — Before the billing address field section renders
518
-
519
- * **When it runs:** This action fires right before the billing address form section (with its heading and input fields) is rendered. It fires inside the `renderBillingAddressFields()` method, after billing field data has been prepared and filtered.
520
- * **Source:** `app/Services/Renderer/CheckoutRenderer.php`
521
-
522
- #### Parameters:
523
- `$data` *(array)*: The current cart
524
- ```php
525
- $data = [
526
- 'cart' => $cart, // \FluentCart\App\Models\Cart instance
527
- ];
528
- ```
529
-
530
- #### Usage Example:
531
- ```php
532
- // Hook before the billing address field section heading renders
533
- add_action('fluent_cart/before_billing_fields_section', function ($data) {
534
- // Output billing section introduction heading
535
- echo '<div class="my-billing-section-intro">';
536
- echo '<h4>Where should we send the invoice?</h4>';
537
- echo '</div>';
538
- }, 10, 1);
539
- ```
540
-
541
- ---
542
-
543
- ### `after_billing_fields_section`
544
- `fluent_cart/after_billing_fields_section` — After the billing address field section
545
-
546
- * **When it runs:** This action fires after the billing address fields section and the "ship to different address" checkbox have been rendered. It only fires when the cart requires shipping.
547
- * **Source:** `app/Services/Renderer/CheckoutRenderer.php`
548
-
549
- #### Parameters:
550
- `$data` *(array)*: The current cart
551
- ```php
552
- $data = [
553
- 'cart' => $cart, // \FluentCart\App\Models\Cart instance
554
- ];
555
- ```
556
-
557
- #### Usage Example:
558
- ```php
559
- // Hook after the billing address field section
560
- add_action('fluent_cart/after_billing_fields_section', function ($data) {
561
- // Extract cart model instance
562
- $cart = $data['cart'];
563
- // Add a note between billing and shipping sections
564
- echo '<div class="my-address-note">';
565
- echo '<p>Shipping is calculated based on your delivery address.</p>';
566
- echo '</div>';
567
- }, 10, 1);
568
- ```
569
-
570
- ---
571
-
572
- ### `before_shipping_fields_section`
573
- `fluent_cart/before_shipping_fields_section` — Before the shipping address field section
574
-
575
- * **When it runs:** This action fires right before the shipping address form section is rendered. The shipping section may be hidden via CSS if "ship to different address" is not checked.
576
- * **Source:** `app/Services/Renderer/CheckoutRenderer.php`
577
-
578
- #### Parameters:
579
- `$data` *(array)*: The current cart
580
- ```php
581
- $data = [
582
- 'cart' => $cart, // \FluentCart\App\Models\Cart instance
583
- ];
584
- ```
585
-
586
- #### Usage Example:
587
- ```php
588
- // Hook before the shipping address field section
589
- add_action('fluent_cart/before_shipping_fields_section', function ($data) {
590
- // Output shipping address entry guidance
591
- echo '<p class="my-shipping-note">Enter the address where you want us to deliver your order.</p>';
592
- }, 10, 1);
593
- ```
594
-
595
- ---
596
-
597
- ### `after_shipping_fields_section`
598
- `fluent_cart/after_shipping_fields_section` — After the shipping address field section
599
-
600
- * **When it runs:** This action fires immediately after the shipping address form section is rendered.
601
- * **Source:** `app/Services/Renderer/CheckoutRenderer.php`
602
-
603
- #### Parameters:
604
- `$data` *(array)*: The current cart
605
- ```php
606
- $data = [
607
- 'cart' => $cart, // \FluentCart\App\Models\Cart instance
608
- ];
609
- ```
610
-
611
- #### Usage Example:
612
- ```php
613
- // Hook after the shipping address field section
614
- add_action('fluent_cart/after_shipping_fields_section', function ($data) {
615
- // Display estimated delivery timeframe note
616
- echo '<div class="my-delivery-estimate">';
617
- echo '<p>Estimated delivery: 3-5 business days</p>';
618
- echo '</div>';
619
- }, 10, 1);
620
- ```
621
-
622
- ---
623
-
624
- ### `before_payment_methods`
625
- `fluent_cart/before_payment_methods` — Before payment method options
626
-
627
- * **When it runs:** This action fires before the payment methods section is rendered on the checkout page. It also fires in the modal checkout renderer and the Gutenberg block inner blocks renderer.
628
- * **Source:** `app/Services/Renderer/CheckoutRenderer.php`, `app/Services/Renderer/ModalCheckoutRenderer.php`, `app/Hooks/Handlers/BlockEditors/Checkout/InnerBlocks/InnerBlocks.php`
629
-
630
- #### Parameters:
631
- `$data` *(array)*: The current cart
632
- ```php
633
- $data = [
634
- 'cart' => $cart, // \FluentCart\App\Models\Cart instance
635
- ];
636
- ```
637
-
638
- #### Usage Example:
639
- ```php
640
- // Hook before payment method options are rendered
641
- add_action('fluent_cart/before_payment_methods', function ($data) {
642
- // Display payment security notice
643
- echo '<div class="my-payment-security-note">';
644
- echo '<p>All transactions are encrypted and secure.</p>';
645
- echo '</div>';
646
- }, 10, 1);
647
- ```
648
-
649
- ---
650
-
651
- ### `after_payment_methods`
652
- `fluent_cart/after_payment_methods` — After payment method options
653
-
654
- * **When it runs:** This action fires after the payment methods section has been rendered, before the checkout submit button.
655
- * **Source:** `app/Services/Renderer/CheckoutRenderer.php`
656
-
657
- #### Parameters:
658
- `$data` *(array)*: The current cart
659
- ```php
660
- $data = [
661
- 'cart' => $cart, // \FluentCart\App\Models\Cart instance
662
- ];
663
- ```
664
-
665
- #### Usage Example:
666
- ```php
667
- // Hook after payment method options are rendered
668
- add_action('fluent_cart/after_payment_methods', function ($data) {
669
- // Render accepted payment gateway logo icons
670
- echo '<div class="my-payment-icons">';
671
- echo '<img src="/wp-content/uploads/visa.svg" alt="Visa" />';
672
- echo '<img src="/wp-content/uploads/mastercard.svg" alt="Mastercard" />';
673
- echo '</div>';
674
- }, 10, 1);
675
- ```
676
-
677
- ---
678
-
679
- ### `after_checkout_button`
680
- `fluent_cart/after_checkout_button` — After the checkout submit button
681
-
682
- * **When it runs:** This action fires immediately after the "Place order" submit button is rendered.
683
- * **Source:** `app/Services/Renderer/CheckoutRenderer.php`
684
-
685
- #### Parameters:
686
- `$data` *(array)*: The current cart
687
- ```php
688
- $data = [
689
- 'cart' => $cart, // \FluentCart\App\Models\Cart instance
690
- ];
691
- ```
692
-
693
- #### Usage Example:
694
- ```php
695
- // Hook after the checkout submit button
696
- add_action('fluent_cart/after_checkout_button', function ($data) {
697
- // Render terms and conditions disclaimer text
698
- echo '<p class="my-checkout-disclaimer">';
699
- echo 'By placing your order you agree to our <a href="/terms">Terms of Service</a>.';
700
- echo '</p>';
701
- }, 10, 1);
702
- ```
703
-
704
- ---
705
-
706
- ### `after_order_notes`
707
- `fluent_cart/after_order_notes` — After the order notes section in the summary sidebar
708
-
709
- * **When it runs:** This action fires after the order notes field in the checkout summary/sidebar section, inside the order summary wrapper.
710
- * **Source:** `app/Services/Renderer/CheckoutRenderer.php`
711
-
712
- #### Parameters:
713
- `$data` *(array)*: The current cart
714
- ```php
715
- $data = [
716
- 'cart' => $cart, // \FluentCart\App\Models\Cart instance
717
- ];
718
- ```
719
-
720
- #### Usage Example:
721
- ```php
722
- // Hook after the order notes section in the summary sidebar
723
- add_action('fluent_cart/after_order_notes', function ($data) {
724
- // Render gift wrap upsell checkbox
725
- echo '<div class="my-gift-wrap-option">';
726
- echo '<label><input type="checkbox" name="gift_wrap" value="yes" /> Add gift wrapping (+$5.00)</label>';
727
- echo '</div>';
728
- }, 10, 1);
729
- ```
730
-
731
- ---
732
-
733
- ### `after_order_notes_field`
734
- `fluent_cart/after_order_notes_field` — After the order notes form field
735
-
736
- * **When it runs:** This action fires right after the order notes textarea field is rendered, inside the `renderOrderNoteField()` method. Note that the order notes field only appears when the cart requires shipping (unless overridden by the `fluent_cart/disable_order_notes_for_digital_products` filter).
737
- * **Source:** `app/Services/Renderer/CheckoutRenderer.php`
738
-
739
- #### Parameters:
740
- `$data` *(array)*: The current cart
741
- ```php
742
- $data = [
743
- 'cart' => $cart, // \FluentCart\App\Models\Cart instance
744
- ];
745
- ```
746
-
747
- #### Usage Example:
748
- ```php
749
- // Hook after the order notes form textarea field
750
- add_action('fluent_cart/after_order_notes_field', function ($data) {
751
- // Render example order notes hint
752
- echo '<p class="my-notes-hint"><em>Example: Leave package at the back door.</em></p>';
753
- }, 10, 1);
754
- ```
755
-
756
- ---
757
-
758
- ### `after_checkout_form`
759
- `fluent_cart/after_checkout_form` — After the checkout form closes
760
-
761
- * **When it runs:** This action fires immediately after the closing `</form>` tag of the checkout form.
762
- * **Source:** `app/Services/Renderer/CheckoutRenderer.php`
763
-
764
- #### Parameters:
765
- `$data` *(array)*: The current cart
766
- ```php
767
- $data = [
768
- 'cart' => $cart, // \FluentCart\App\Models\Cart instance
769
- ];
770
- ```
771
-
772
- #### Usage Example:
773
- ```php
774
- // Hook after the checkout form closes
775
- add_action('fluent_cart/after_checkout_form', function ($data) {
776
- // Render a support chat widget below the form
777
- echo '<div class="my-checkout-support">';
778
- echo '<p>Need help? <a href="#" onclick="openChat()">Chat with us</a></p>';
779
- echo '</div>';
780
- }, 10, 1);
781
- ```
782
-
783
- ---
784
-
785
- ### `before_checkout_page_close`
786
- `fluent_cart/before_checkout_page_close` — Before the checkout page wrapper div closes
787
-
788
- * **When it runs:** This action fires just before the closing `</div>` of the main checkout page wrapper.
789
- * **Source:** `app/Services/Renderer/CheckoutRenderer.php`
790
-
791
- #### Parameters:
792
- `$data` *(array)*: The current cart
793
- ```php
794
- $data = [
795
- 'cart' => $cart, // \FluentCart\App\Models\Cart instance
796
- ];
797
- ```
798
-
799
- #### Usage Example:
800
- ```php
801
- // Hook before the checkout page wrapper div closes
802
- add_action('fluent_cart/before_checkout_page_close', function ($data) {
803
- // Render money-back guarantee footer badge
804
- echo '<div class="my-checkout-footer-badges">';
805
- echo '<p>30-day money-back guarantee</p>';
806
- echo '</div>';
807
- }, 10, 1);
808
- ```
809
-
810
- ---
811
-
812
- ### `after_checkout_page`
813
- `fluent_cart/after_checkout_page` — After the entire checkout page wrapper
814
-
815
- * **When it runs:** This action fires after the checkout page wrapper `</div>` has been closed. Use it for scripts, tracking pixels, or other content that should appear after the entire checkout page.
816
- * **Source:** `app/Services/Renderer/CheckoutRenderer.php`
817
-
818
- #### Parameters:
819
- `$data` *(array)*: The current cart
820
- ```php
821
- $data = [
822
- 'cart' => $cart, // \FluentCart\App\Models\Cart instance
823
- ];
824
- ```
825
-
826
- #### Usage Example:
827
- ```php
828
- // Hook after the entire checkout page wrapper closes
829
- add_action('fluent_cart/after_checkout_page', function ($data) {
830
- // Extract cart model instance
831
- $cart = $data['cart'];
832
- // Output a tracking script after the checkout page
833
- echo '<script>myAnalytics.trackCheckoutView({ cartId: ' . intval($cart->id) . ' });</script>';
834
- }, 10, 1);
835
- ```
836
-
837
- ---
838
-
839
- ### `before_summary_total`
840
- `fluent_cart/checkout/before_summary_total` — Before the total line in the cart summary
841
-
842
- * **When it runs:** This action fires in the cart summary sidebar, after the subtotal, shipping, and discount lines but before the coupon input field and the final total line.
843
- * **Source:** `app/Services/Renderer/CartSummaryRender.php`
844
-
845
- #### Parameters:
846
- `$data` *(array)*: The current cart
847
- ```php
848
- $data = [
849
- 'cart' => $cart, // \FluentCart\App\Models\Cart instance
850
- ];
851
- ```
852
-
853
- #### Usage Example:
854
- ```php
855
- // Hook before the total line in the cart summary sidebar
856
- add_action('fluent_cart/checkout/before_summary_total', function ($data) {
857
- // Extract cart model instance
858
- $cart = $data['cart'];
859
- // Add a custom fee line in the summary sidebar
860
- echo '<li class="my-custom-fee">';
861
- echo '<span class="fct_summary_label">Processing Fee</span>';
862
- echo '<span class="fct_summary_value">$2.50</span>';
863
- echo '</li>';
864
- }, 10, 1);
865
- ```
866
-
867
- ---
868
-
869
- ## Cart Line Items Rendering
870
- These hooks fire during the rendering of individual cart line items on the checkout page. They all receive the same parameter structure from `CartItemRenderer::getEventInfo()`, which includes Cart, Product, and ProductVariation model instances. Use `echo` to output custom HTML.
871
-
872
- ### `line_meta`
873
- `fluent_cart/cart/line_item/line_meta` — After line item content, for custom metadata
874
-
875
- * **When it runs:** This action fires after the main item content (title, variant info, child variants) inside the item info area, but before the price section. Use it to display custom per-item metadata such as personalization details or custom options.
876
- * **Source:** `app/Services/Renderer/CartItemRenderer.php`
877
-
878
- #### Parameters:
879
- `$data` *(array)*: Line item rendering context
880
- * `item` *(array)* — The cart item data (`post_id`, `title`, `quantity`, `unit_price`, etc.)
881
- * `cart` *(\FluentCart\App\Models\Cart|null)* — Cart instance or `null`
882
- * `product` *(\FluentCart\App\Models\Product|null)* — Product model or `null`
883
- * `variant` *(\FluentCart\App\Models\ProductVariation|null)* — ProductVariation model or `null`
884
-
885
- #### Usage Example:
886
- ```php
887
- // Hook after cart line item content for custom metadata
888
- add_action('fluent_cart/cart/line_item/line_meta', function ($data) {
889
- // Extract item array from event data
890
- $item = $data['item'];
891
-
892
- // Display custom engraving text if present
893
- $engraving = $item['custom_fields']['engraving'] ?? '';
894
- if ($engraving) {
895
- echo '<div class="my-engraving-preview">';
896
- echo '<small>Engraving: ' . esc_html($engraving) . '</small>';
897
- echo '</div>';
898
- }
899
- }, 10, 1);
900
- ```
901
-
902
- ---
903
-
904
- ### `before_total`
905
- `fluent_cart/cart/line_item/before_total` — Before the line item price/total
906
-
907
- * **When it runs:** This action fires inside the price area of a cart line item, before the item total (and any promotional strikethrough price) is displayed.
908
- * **Source:** `app/Services/Renderer/CartItemRenderer.php`
909
-
910
- #### Parameters:
911
- `$data` *(array)*: Line item rendering context (same structure as `line_meta`)
912
-
913
- #### Usage Example:
914
- ```php
915
- // Hook before the cart line item price/total
916
- add_action('fluent_cart/cart/line_item/before_total', function ($data) {
917
- // Extract item array and calculate promotional savings amount
918
- $item = $data['item'];
919
- $savings = ($item['other_info']['original_price'] ?? 0) - ($item['unit_price'] ?? 0);
920
- if ($savings > 0) {
921
- echo '<span class="my-savings-badge">You save ' . esc_html(\FluentCart\App\Helpers\Helper::toDecimal($savings)) . '</span>';
922
- }
923
- }, 10, 1);
924
- ```
925
-
926
- ---
927
-
928
- ### `after_total`
929
- `fluent_cart/cart/line_item/after_total` — After the line item price/total
930
-
931
- * **When it runs:** This action fires inside the price area of a cart line item, after the item total is displayed.
932
- * **Source:** `app/Services/Renderer/CartItemRenderer.php`
933
-
934
- #### Parameters:
935
- `$data` *(array)*: Line item rendering context (same structure as `line_meta`)
936
-
937
- #### Usage Example:
938
- ```php
939
- // Hook after the cart line item price/total
940
- add_action('fluent_cart/cart/line_item/after_total', function ($data) {
941
- // Extract item array from event data
942
- $item = $data['item'];
943
- $paymentType = $item['other_info']['payment_type'] ?? '';
944
- if ($paymentType === 'subscription') {
945
- echo '<span class="my-recurring-label"><small>Recurring</small></span>';
946
- }
947
- }, 10, 1);
948
- ```
949
-
950
- ---
951
-
952
- ### `before_main_title`
953
- `fluent_cart/cart/line_item/before_main_title` — Before the product title in a line item
954
-
955
- * **When it runs:** This action fires at the very beginning of the item title area, before the quantity badge, product name, and variant title.
956
- * **Source:** `app/Services/Renderer/CartItemRenderer.php`
957
-
958
- #### Parameters:
959
- `$data` *(array)*: Line item rendering context (same structure as `line_meta`)
960
-
961
- #### Usage Example:
962
- ```php
963
- // Hook before the product title in a cart line item
964
- add_action('fluent_cart/cart/line_item/before_main_title', function ($data) {
965
- // Extract item array from event data
966
- $item = $data['item'];
967
- // Add a "Sale" badge before the product title if on sale
968
- if (!empty($item['other_info']['is_on_sale'])) {
969
- echo '<span class="my-sale-badge">Sale</span>';
970
- }
971
- }, 10, 1);
972
- ```
973
-
974
- ---
975
-
976
- ### `after_main_title`
977
- `fluent_cart/cart/line_item/after_main_title` — After the product title in a line item
978
-
979
- * **When it runs:** This action fires at the end of the item title area, after the product name, variant title, and payment type information (subscription details / per-unit price).
980
- * **Source:** `app/Services/Renderer/CartItemRenderer.php`
981
-
982
- #### Parameters:
983
- `$data` *(array)*: Line item rendering context (same structure as `line_meta`)
984
-
985
- #### Usage Example:
986
- ```php
987
- // Hook after the product title in a cart line item
988
- add_action('fluent_cart/cart/line_item/after_main_title', function ($data) {
989
- // Extract item array from event data
990
- $item = $data['item'];
991
- // Show estimated delivery date per line item
992
- $deliveryDays = $item['other_info']['delivery_days'] ?? null;
993
- if ($deliveryDays) {
994
- $date = date('M j', strtotime("+{$deliveryDays} days"));
995
- echo '<div class="my-delivery-estimate"><small>Est. delivery: ' . esc_html($date) . '</small></div>';
996
- }
997
- }, 10, 1);
998
- ```
999
-
1000
- ---
1001
-
1002
- ## Receipt / Thank You Page
1003
- These hooks fire during the rendering of the thank-you / receipt page shown after a successful checkout. The `$config` parameter passed to most hooks contains the Order model instance along with view context. All rendering hooks use output buffering — use `echo` to inject custom HTML.
1004
-
1005
- ### `before_header`
1006
- `fluent_cart/receipt/thank_you/before_header` — Before the thank-you page header
1007
-
1008
- * **When it runs:** This action fires at the very beginning of the thank-you page content, before the header section (which contains the success/pending icon and title).
1009
- * **Source:** `app/Services/Renderer/Receipt/ThankYouRender.php`
1010
-
1011
- #### Parameters:
1012
- `$config` *(array)*: Thank-you page configuration
1013
- ```php
1014
- $config = [
1015
- 'order' => $order, // \FluentCart\App\Models\Order instance
1016
- 'is_first_time' => true|false, // bool — whether this is the first view of this receipt
1017
- 'order_operation' => $orderOperation, // mixed — order operation context or null
1018
- ];
1019
- ```
1020
-
1021
- #### Usage Example:
1022
- ```php
1023
- // Hook before the thank-you page header
1024
- add_action('fluent_cart/receipt/thank_you/before_header', function ($config) {
1025
- // Extract order model from thank-you config array
1026
- $order = $config['order'];
1027
- echo '<div class="my-confetti-wrapper" data-order-id="' . intval($order->id) . '"></div>';
1028
- }, 10, 1);
1029
- ```
1030
-
1031
- ---
1032
-
1033
- ### `after_header`
1034
- `fluent_cart/receipt/thank_you/after_header` — After the thank-you page header
1035
-
1036
- * **When it runs:** This action fires after the header section (the success/pending icon and title) is fully rendered, before the body section begins.
1037
- * **Source:** `app/Services/Renderer/Receipt/ThankYouRender.php`
1038
-
1039
- #### Parameters:
1040
- `$config` *(array)*: Thank-you page configuration (same structure as `before_header`)
1041
-
1042
- #### Usage Example:
1043
- ```php
1044
- // Hook after the thank-you page header
1045
- add_action('fluent_cart/receipt/thank_you/after_header', function ($config) {
1046
- // Extract order model from thank-you config array
1047
- $order = $config['order'];
1048
- if ($order->payment_status === 'paid') {
1049
- echo '<div class="my-share-prompt">';
1050
- echo '<p>Love your purchase? Share it with friends!</p>';
1051
- echo '</div>';
1052
- }
1053
- }, 10, 1);
1054
- ```
1055
-
1056
- ---
1057
-
1058
- ### `after_header_title`
1059
- `fluent_cart/receipt/thank_you/after_header_title` — After the header title text
1060
-
1061
- * **When it runs:** This action fires inside the header section, after the "Purchase Successful!" or "Payment Pending!" heading, but still within the header wrapper div. Use it to add a subtitle or additional context below the main title.
1062
- * **Source:** `app/Services/Renderer/Receipt/ThankYouRender.php`
1063
-
1064
- #### Parameters:
1065
- `$config` *(array)*: Thank-you page configuration (same structure as `before_header`)
1066
-
1067
- #### Usage Example:
1068
- ```php
1069
- // Hook after the header title text on thank-you page
1070
- add_action('fluent_cart/receipt/thank_you/after_header_title', function ($config) {
1071
- // Extract order model from thank-you config array
1072
- $order = $config['order'];
1073
- echo '<p class="my-order-ref">Order Reference: #' . esc_html($order->invoice_no) . '</p>';
1074
- }, 10, 1);
1075
- ```
1076
-
1077
- ---
1078
-
1079
- ### `before_body`
1080
- `fluent_cart/receipt/thank_you/before_body` — Before the thank-you page body
1081
-
1082
- * **When it runs:** This action fires after the header section and before the body section, which contains the order details, items, subscriptions, downloads, licenses, and addresses.
1083
- * **Source:** `app/Services/Renderer/Receipt/ThankYouRender.php`
1084
-
1085
- #### Parameters:
1086
- `$config` *(array)*: Thank-you page configuration (same structure as `before_header`)
1087
-
1088
- #### Usage Example:
1089
- ```php
1090
- // Hook before the thank-you page body section
1091
- add_action('fluent_cart/receipt/thank_you/before_body', function ($config) {
1092
- // Render confirmation email sent message
1093
- echo '<div class="my-receipt-notice">';
1094
- echo '<p>A confirmation email has been sent to your email address.</p>';
1095
- echo '</div>';
1096
- }, 10, 1);
1097
- ```
1098
-
1099
- ---
1100
-
1101
- ### `after_body`
1102
- `fluent_cart/receipt/thank_you/after_body` — After the thank-you page body
1103
-
1104
- * **When it runs:** This action fires after the body section (order details, items, addresses) is fully rendered, before the page wrapper closes.
1105
- * **Source:** `app/Services/Renderer/Receipt/ThankYouRender.php`
1106
-
1107
- #### Parameters:
1108
- `$config` *(array)*: Thank-you page configuration (same structure as `before_header`)
1109
-
1110
- #### Usage Example:
1111
- ```php
1112
- // Hook after the thank-you page body section
1113
- add_action('fluent_cart/receipt/thank_you/after_body', function ($config) {
1114
- // Render recommended upsell products block
1115
- echo '<div class="my-upsell-section">';
1116
- echo '<h3>You might also like</h3>';
1117
- echo '</div>';
1118
- }, 10, 1);
1119
- ```
1120
-
1121
- ---
1122
-
1123
- ### `before_order_header`
1124
- `fluent_cart/receipt/thank_you/before_order_header` — Before the order header in the receipt body
1125
-
1126
- * **When it runs:** This action fires inside the receipt body, before the order header area (which shows the customer greeting and order number).
1127
- * **Source:** `app/Services/Renderer/Receipt/ThankYouRender.php`
1128
-
1129
- #### Parameters:
1130
- `$config` *(array)*: Thank-you page configuration (same structure as `before_header`)
1131
-
1132
- #### Usage Example:
1133
- ```php
1134
- // Hook before the order header in the receipt body
1135
- add_action('fluent_cart/receipt/thank_you/before_order_header', function ($config) {
1136
- // Render order placement date heading
1137
- echo '<div class="my-receipt-date">';
1138
- echo '<p>Order placed on: ' . esc_html(date('F j, Y')) . '</p>';
1139
- echo '</div>';
1140
- }, 10, 1);
1141
- ```
1142
-
1143
- ---
1144
-
1145
- ### `after_order_header`
1146
- `fluent_cart/receipt/thank_you/after_order_header` — After the order header in the receipt body
1147
-
1148
- * **When it runs:** This action fires after the order header (customer greeting, order number, and payment status message), before the tax information and order items.
1149
- * **Source:** `app/Services/Renderer/Receipt/ThankYouRender.php`
1150
-
1151
- #### Parameters:
1152
- `$config` *(array)*: Thank-you page configuration (same structure as `before_header`)
1153
-
1154
- #### Usage Example:
1155
- ```php
1156
- // Hook after the order header in the receipt body
1157
- add_action('fluent_cart/receipt/thank_you/after_order_header', function ($config) {
1158
- // Extract order model from thank-you config array
1159
- $order = $config['order'];
1160
- if ($order->note) {
1161
- echo '<div class="my-order-note">';
1162
- echo '<strong>Your note:</strong> ' . esc_html($order->note);
1163
- echo '</div>';
1164
- }
1165
- }, 10, 1);
1166
- ```
1167
-
1168
- ---
1169
-
1170
- ### `before_order_items`
1171
- `fluent_cart/receipt/thank_you/before_order_items` — Before the order items list in the receipt
1172
-
1173
- * **When it runs:** This action fires after the store tax information and before the order items table is rendered.
1174
- * **Source:** `app/Services/Renderer/Receipt/ThankYouRender.php`
1175
-
1176
- #### Parameters:
1177
- `$config` *(array)*: Thank-you page configuration (same structure as `before_header`)
1178
-
1179
- #### Usage Example:
1180
- ```php
1181
- // Hook before the order items list in the receipt
1182
- add_action('fluent_cart/receipt/thank_you/before_order_items', function ($config) {
1183
- // Render items section title
1184
- echo '<div class="my-items-intro"><h4>Here is what you ordered:</h4></div>';
1185
- }, 10, 1);
1186
- ```
1187
-
1188
- ---
1189
-
1190
- ### `after_order_items`
1191
- `fluent_cart/receipt/thank_you/after_order_items` — After the order items list in the receipt
1192
-
1193
- * **When it runs:** This action fires after the order items table (including the totals breakdown), before the subscription items, downloads, licenses, and address sections.
1194
- * **Source:** `app/Services/Renderer/Receipt/ThankYouRender.php`
1195
-
1196
- #### Parameters:
1197
- `$config` *(array)*: Thank-you page configuration (same structure as `before_header`)
1198
-
1199
- #### Usage Example:
1200
- ```php
1201
- // Hook after the order items list in the receipt
1202
- add_action('fluent_cart/receipt/thank_you/after_order_items', function ($config) {
1203
- // Extract order model from thank-you config array
1204
- $order = $config['order'];
1205
- // Show a customer referral code block after items list
1206
- echo '<div class="my-referral-block">';
1207
- echo '<p>Share your referral code <strong>REF-' . intval($order->customer_id) . '</strong> and earn 10% credit!</p>';
1208
- echo '</div>';
1209
- }, 10, 1);
1210
- ```
1211
-
1212
- ---
1213
-
1214
- ### `before_footer_buttons`
1215
- `fluent_cart/receipt/thank_you/before_footer_buttons` — Before the footer buttons
1216
-
1217
- * **When it runs:** This action fires in the receipt footer area, before the "View Order" and "Download Receipt" buttons are rendered.
1218
- * **Source:** `app/Services/Renderer/Receipt/ThankYouRender.php`
1219
-
1220
- #### Parameters:
1221
- `$config` *(array)*: Thank-you page configuration (same structure as `before_header`)
1222
-
1223
- #### Usage Example:
1224
- ```php
1225
- // Hook before the thank-you page footer buttons
1226
- add_action('fluent_cart/receipt/thank_you/before_footer_buttons', function ($config) {
1227
- // Render thank you footer message
1228
- echo '<div class="my-footer-message">';
1229
- echo '<p>Thank you for shopping with us!</p>';
1230
- echo '</div>';
1231
- }, 10, 1);
1232
- ```
1233
-
1234
- ---
1235
-
1236
- ### `after_footer_buttons`
1237
- `fluent_cart/receipt/thank_you/after_footer_buttons` — After the footer buttons
1238
-
1239
- * **When it runs:** This action fires in the receipt footer area, after the "View Order" and "Download Receipt" buttons have been rendered.
1240
- * **Source:** `app/Services/Renderer/Receipt/ThankYouRender.php`
1241
-
1242
- #### Parameters:
1243
- `$config` *(array)*: Thank-you page configuration (same structure as `before_header`)
1244
-
1245
- #### Usage Example:
1246
- ```php
1247
- // Hook after the thank-you page footer buttons
1248
- add_action('fluent_cart/receipt/thank_you/after_footer_buttons', function ($config) {
1249
- // Render social share buttons
1250
- echo '<div class="my-social-share">';
1251
- echo '<p>Follow us on social media for updates and exclusive offers.</p>';
1252
- echo '</div>';
1253
- }, 10, 1);
1254
- ```
1255
-
1256
- ---
1257
-
1258
- ### `after_receipt`
1259
- `fluent_cart/after_receipt` — After the entire receipt/thank-you page
1260
-
1261
- * **When it runs:** This action fires after the complete thank-you page has been rendered, including the footer. It fires on every receipt view (both first-time and returning visits). This hook is also present in the legacy `thank_you.php` view template.
1262
- * **Source:** `app/Services/Renderer/Receipt/ThankYouRender.php`, `app/Views/invoice/thank_you.php`
1263
-
1264
- #### Parameters:
1265
- `$data` *(array)*: Order and view context
1266
- ```php
1267
- $data = [
1268
- 'order' => $order, // \FluentCart\App\Models\Order instance
1269
- 'is_first_time' => true|false, // bool — whether this is the first view of this receipt
1270
- 'order_operation' => $orderOperation, // mixed — order operation context or null
1271
- ];
1272
- ```
1273
-
1274
- #### Usage Example:
1275
- ```php
1276
- // Hook after the entire receipt/thank-you page renders
1277
- add_action('fluent_cart/after_receipt', function ($data) {
1278
- // Extract order model instance
1279
- $order = $data['order'];
1280
-
1281
- // Render a customer satisfaction survey link
1282
- echo '<div class="my-survey-widget">';
1283
- echo '<h4>How was your experience?</h4>';
1284
- echo '<a href="/survey?order=' . intval($order->id) . '">Take a quick survey</a>';
1285
- echo '</div>';
1286
- }, 10, 1);
1287
- ```
1288
-
1289
- ---
1290
-
1291
- ### `after_receipt_first_time`
1292
- `fluent_cart/after_receipt_first_time` — Only on the first receipt view (for conversion tracking)
1293
-
1294
- * **When it runs:** This action fires only on the first time a customer views the receipt page after a purchase. It does not fire on subsequent visits to the same receipt URL. This is the ideal hook for firing conversion tracking pixels, analytics events, or affiliate postback URLs.
1295
- * **Source:** `app/Services/Renderer/Receipt/ThankYouRender.php`, `app/Views/invoice/thank_you.php`
1296
-
1297
- #### Parameters:
1298
- `$data` *(array)*: Order and operation context
1299
- ```php
1300
- $data = [
1301
- 'order' => $order, // \FluentCart\App\Models\Order instance
1302
- 'order_operation' => $orderOperation, // mixed — order operation context or null
1303
- ];
1304
- ```
1305
-
1306
- #### Usage Example:
1307
- ```php
1308
- // Hook on the first receipt view (ideal for conversion tracking)
1309
- add_action('fluent_cart/after_receipt_first_time', function ($data) {
1310
- // Extract order model and formatted decimal total
1311
- $order = $data['order'];
1312
- $total = \FluentCart\App\Helpers\Helper::toDecimal($order->total_amount);
1313
-
1314
- // Fire Meta Facebook conversion tracking pixel
1315
- echo '<script>';
1316
- echo 'fbq("track", "Purchase", { value: ' . esc_js($total) . ', currency: "' . esc_js($order->currency) . '" });';
1317
- echo '</script>';
1318
-
1319
- // Fire Google Ads conversion tracking script
1320
- echo '<script>';
1321
- echo 'gtag("event", "conversion", { send_to: "AW-XXXXX/YYYYY", value: ' . esc_js($total) . ', currency: "' . esc_js($order->currency) . '", transaction_id: "' . esc_js($order->invoice_no) . '" });';
1322
- echo '</script>';
1323
- }, 10, 1);
1324
- ```
1325
-
1326
- ---
1327
-
1328
- ### `before_render_redirect_page`
1329
- `fluent_cart/before_render_redirect_page` — Before the payment redirect/receipt page renders
1330
-
1331
- * **When it runs:** This action fires at the very beginning of the receipt shortcode handler, before any receipt or redirect page content is rendered. It provides the raw URL parameters used to identify the order and transaction. Use it for early validation, logging, or to set up resources needed by the receipt page.
1332
- * **Source:** `app/Hooks/Handlers/ShortCodes/ReceiptHandler.php`
1333
-
1334
- #### Parameters:
1335
- `$data` *(array)*: URL parameters for the receipt/redirect
1336
- ```php
1337
- $data = [
1338
- 'order_hash' => $orderHash, // string — the order UUID from the URL
1339
- 'trx_hash' => $transactionHash, // string — the transaction hash from the URL
1340
- 'method' => $method, // string — the payment method slug
1341
- 'is_receipt' => $isReceipt, // bool — true if this is a receipt page, false if redirect
1342
- ];
1343
- ```
1344
-
1345
- #### Usage Example:
1346
- ```php
1347
- // Hook before the payment redirect or receipt page renders
1348
- add_action('fluent_cart/before_render_redirect_page', function ($data) {
1349
- // Log receipt page visits for debugging payment callbacks
1350
- if ($data['is_receipt'] && $data['order_hash']) {
1351
- error_log('Receipt page visited for order: ' . $data['order_hash']
1352
- . ' via method: ' . $data['method']);
1353
- }
1354
- }, 10, 1);
1355
- ```
1
+ # Action Hooks: Cart & Checkout
2
+
3
+ All hooks related to the shopping flow — from adding items to the Cart through checkout rendering and the receipt/thank-you page.
4
+
5
+ ---
6
+
7
+ ## Cart Events
8
+
9
+ ### `item_added`
10
+ `fluent_cart/cart/item_added` — Fired after an item is added to the cart
11
+
12
+ * **When it runs:** This action fires immediately after a product item has been successfully added to the Cart model and saved to the database. It runs before the `cart_data_items_updated` hook with the `item_added` scope.
13
+ * **Source:** `app/Models/Cart.php`
14
+
15
+ #### Parameters:
16
+ `$data` *(array)*: Cart and item data
17
+ ```php
18
+ $data = [
19
+ 'cart' => $cart, // \FluentCart\App\Models\Cart instance
20
+ 'item' => $item, // array — the cart item that was just added
21
+ ];
22
+ ```
23
+
24
+ #### Usage Example:
25
+ ```php
26
+ // Hook after an item is added to the cart
27
+ add_action('fluent_cart/cart/item_added', function ($data) {
28
+ // Extract cart model and item array from event data
29
+ $cart = $data['cart'];
30
+ $item = $data['item'];
31
+
32
+ // Log the added product for analytics
33
+ error_log('Product ' . $item['post_id'] . ' added to cart #' . $cart->id);
34
+ }, 10, 1);
35
+ ```
36
+
37
+ ---
38
+
39
+ ### `item_removed`
40
+ `fluent_cart/cart/item_removed` — Fired after an item is removed from the cart
41
+
42
+ * **When it runs:** This action fires after a product item has been removed from the Cart and saved, but only when the `$triggerEvent` parameter is `true` (the default). When an item is removed silently (e.g., during a replacement operation), this hook does not fire.
43
+ * **Source:** `app/Models/Cart.php`
44
+
45
+ #### Parameters:
46
+ `$data` *(array)*: Cart and removal context
47
+ ```php
48
+ $data = [
49
+ 'cart' => $cart, // \FluentCart\App\Models\Cart instance
50
+ 'variation_id' => $variationId, // int — the variation ID that was removed
51
+ 'extra_args' => $extraArgs, // array — additional matching arguments
52
+ 'removed_item' => $removingItem, // array — the full cart item that was removed
53
+ ];
54
+ ```
55
+
56
+ #### Usage Example:
57
+ ```php
58
+ // Hook after an item is removed from the cart
59
+ add_action('fluent_cart/cart/item_removed', function ($data) {
60
+ // Extract removed item array and cart model from event data
61
+ $removedItem = $data['removed_item'];
62
+ $cart = $data['cart'];
63
+
64
+ // Track removal for abandoned cart analytics
65
+ do_action('my_plugin/track_cart_removal', [
66
+ 'variation_id' => $data['variation_id'],
67
+ 'product_id' => $removedItem['post_id'] ?? null,
68
+ 'cart_id' => $cart->id,
69
+ ]);
70
+ }, 10, 1);
71
+ ```
72
+
73
+ ---
74
+
75
+ ### `cart_data_items_updated`
76
+ `fluent_cart/cart/cart_data_items_updated` — General-purpose hook for any cart data change
77
+
78
+ * **When it runs:** This action fires whenever the cart data array is modified. The `scope` field tells you what operation triggered the update. It fires on item add, item remove, coupon apply, coupon remove, discount recalculation, and checkout page loading.
79
+ * **Source:** `app/Models/Cart.php`, `app/Hooks/Handlers/ShortCodes/Checkout/CheckoutPageHandler.php`
80
+
81
+ #### Parameters:
82
+ `$data` *(array)*: Cart and scope context
83
+ ```php
84
+ $data = [
85
+ 'cart' => $cart, // \FluentCart\App\Models\Cart instance
86
+ 'scope' => 'item_added', // string — one of the scope values below
87
+ 'scope_data' => $scopeData, // mixed — context data depending on scope
88
+ ];
89
+ ```
90
+
91
+ #### Possible Scope Values and `scope_data`:
92
+ | Scope | `scope_data` Description |
93
+ |---|---|
94
+ | `'item_added'` | The cart item array that was added |
95
+ | `'item_removed'` | The variation ID (`int`) that was removed |
96
+ | `'discounts_recalculated'` | Array of applied coupon codes |
97
+ | `'remove_coupon'` | Array of coupon codes that were removed |
98
+ | `'apply_coupons'` | Array of coupon codes that were applied |
99
+ | `'loading'` | Empty string (fired on checkout page load) |
100
+
101
+ #### Usage Example:
102
+ ```php
103
+ // General-purpose hook for any cart data change
104
+ add_action('fluent_cart/cart/cart_data_items_updated', function ($data) {
105
+ // Extract cart model and update scope string
106
+ $cart = $data['cart'];
107
+ $scope = $data['scope'];
108
+
109
+ // Recalculate custom surcharges when cart items change
110
+ if ($scope === 'item_added' || $scope === 'item_removed') {
111
+ my_plugin_recalculate_surcharges($cart);
112
+ }
113
+
114
+ // Log applied coupons if scope is apply_coupons
115
+ if ($scope === 'apply_coupons') {
116
+ error_log('Coupons applied to cart #' . $cart->id . ': ' . implode(', ', $data['scope_data']));
117
+ }
118
+ }, 10, 1);
119
+ ```
120
+
121
+ ---
122
+
123
+ ### `cart_completed`
124
+ `fluent_cart/cart_completed` — Fired when a cart is marked as completed after payment
125
+
126
+ * **When it runs:** This action fires when the cart's stage is set to `completed` after a successful Order payment. The cart's `completed_at` timestamp has already been saved at this point. This is triggered inside `StatusHelper` during order status transitions when payment is marked as paid.
127
+ * **Source:** `app/Helpers/StatusHelper.php`
128
+
129
+ #### Parameters:
130
+ `$data` *(array)*: Completed cart and associated order
131
+ ```php
132
+ $data = [
133
+ 'cart' => $relatedCart, // \FluentCart\App\Models\Cart instance (stage = 'completed')
134
+ 'order' => $order, // \FluentCart\App\Models\Order instance
135
+ ];
136
+ ```
137
+
138
+ #### Usage Example:
139
+ ```php
140
+ // Hook when a cart is marked as completed after payment
141
+ add_action('fluent_cart/cart_completed', function ($data) {
142
+ // Extract completed cart and associated order models
143
+ $cart = $data['cart'];
144
+ $order = $data['order'];
145
+
146
+ // Fire a conversion pixel or sync to analytics
147
+ my_plugin_track_conversion([
148
+ 'order_id' => $order->id,
149
+ 'total' => $order->total_amount,
150
+ 'customer_id' => $order->customer_id,
151
+ ]);
152
+ }, 10, 1);
153
+ ```
154
+
155
+ ---
156
+
157
+ ## Checkout Data Events
158
+
159
+ ### `prepare_other_data`
160
+ `fluent_cart/checkout/prepare_other_data` — After order creation, before finalizing
161
+
162
+ * **When it runs:** This action fires during the checkout submission flow, after the draft Order has been created but before it is finalized (before addresses and items are attached). This gives modules a chance to attach additional data to the order.
163
+ * **Source:** `api/Checkout/CheckoutApi.php`
164
+
165
+ #### Parameters:
166
+ `$data` *(array)*: Full checkout context
167
+ ```php
168
+ $data = [
169
+ 'cart' => $cart, // \FluentCart\App\Models\Cart instance
170
+ 'order' => $createdOrder, // \FluentCart\App\Models\Order — the newly created draft order
171
+ 'prev_order' => $prevOrder, // \FluentCart\App\Models\Order|null — previous order if retrying
172
+ 'request_data' => $data, // array — raw validated request data from checkout form
173
+ 'validated_data' => $validatedData, // array — sanitized/validated checkout field values
174
+ ];
175
+ ```
176
+
177
+ #### Usage Example:
178
+ ```php
179
+ // Hook after draft order creation, before finalizing checkout
180
+ add_action('fluent_cart/checkout/prepare_other_data', function ($data) {
181
+ // Extract draft order and request data array
182
+ $order = $data['order'];
183
+ $requestData = $data['request_data'];
184
+
185
+ // Attach custom metadata to the order before it finalizes
186
+ $customField = sanitize_text_field($requestData['custom_gift_message'] ?? '');
187
+ if ($customField) {
188
+ $order->updateMeta('gift_message', $customField);
189
+ }
190
+ }, 10, 1);
191
+ ```
192
+
193
+ ---
194
+
195
+ ### `cart_amount_updated`
196
+ `fluent_cart/checkout/cart_amount_updated` — Fired when the cart total may have changed
197
+
198
+ * **When it runs:** This action fires whenever an operation changes (or may change) the cart total. This includes: item removal (silent mode), coupon application, coupon removal, discount recalculation, quantity updates, order bump toggles, and tax recalculations. Use this hook to react to price changes regardless of the specific cause.
199
+ * **Source:** `app/Models/Cart.php`, `app/Hooks/Cart/WebCheckoutHandler.php`, `app/Modules/Tax/TaxModule.php`
200
+
201
+ #### Parameters:
202
+ `$data` *(array)*: The affected cart
203
+ ```php
204
+ $data = [
205
+ 'cart' => $cart, // \FluentCart\App\Models\Cart instance
206
+ ];
207
+ ```
208
+
209
+ #### Usage Example:
210
+ ```php
211
+ // Hook when the cart total amount is updated
212
+ add_action('fluent_cart/checkout/cart_amount_updated', function ($data) {
213
+ // Extract cart model instance
214
+ $cart = $data['cart'];
215
+
216
+ // Recalculate a custom fee based on the new cart total
217
+ $estimatedTotal = $cart->getEstimatedTotal();
218
+ if ($estimatedTotal > 10000) { // over $100.00 in cents
219
+ // Apply free shipping threshold logic
220
+ my_plugin_apply_free_shipping($cart);
221
+ }
222
+ }, 10, 1);
223
+ ```
224
+
225
+ ---
226
+
227
+ ### `shipping_data_changed`
228
+ `fluent_cart/checkout/shipping_data_changed` — Fired when shipping data changes
229
+
230
+ * **When it runs:** This action fires when shipping-related data on the cart changes, such as when a new shipping method is selected, the shipping charge changes, or the shipping address is updated in a way that affects shipping calculations.
231
+ * **Source:** `app/Helpers/CartHelper.php`, `app/Hooks/Cart/WebCheckoutHandler.php`
232
+
233
+ #### Parameters:
234
+ `$data` *(array)*: The affected cart
235
+ ```php
236
+ $data = [
237
+ 'cart' => $cart, // \FluentCart\App\Models\Cart instance
238
+ ];
239
+ ```
240
+
241
+ #### Usage Example:
242
+ ```php
243
+ // Hook when shipping-related data on the cart changes
244
+ add_action('fluent_cart/checkout/shipping_data_changed', function ($data) {
245
+ // Extract cart model and shipping data array
246
+ $cart = $data['cart'];
247
+ $shippingData = $cart->checkout_data['shipping_data'] ?? [];
248
+
249
+ // Log shipping method selection for analytics
250
+ error_log('Cart #' . $cart->id . ' shipping method: ' . ($shippingData['shipping_method_id'] ?? 'none'));
251
+ }, 10, 1);
252
+ ```
253
+
254
+ ---
255
+
256
+ ### `form_data_changed`
257
+ `fluent_cart/checkout/form_data_changed` — Fired when checkout form data changes
258
+
259
+ * **When it runs:** This action fires when the checkout form data is updated via AJAX, such as when a customer changes their address, toggles "ship to different address", or any form field is updated that triggers a server-side recalculation.
260
+ * **Source:** `app/Hooks/Cart/WebCheckoutHandler.php`
261
+
262
+ #### Parameters:
263
+ `$data` *(array)*: The affected cart
264
+ ```php
265
+ $data = [
266
+ 'cart' => $cart, // \FluentCart\App\Models\Cart instance
267
+ ];
268
+ ```
269
+
270
+ #### Usage Example:
271
+ ```php
272
+ // Hook when checkout form data is updated via AJAX
273
+ add_action('fluent_cart/checkout/form_data_changed', function ($data) {
274
+ // Extract cart model and checkout form data array
275
+ $cart = $data['cart'];
276
+ $formData = $cart->checkout_data['form_data'] ?? [];
277
+
278
+ // Check if the billing country requires special handling
279
+ $billingCountry = $formData['billing_country'] ?? '';
280
+ if (in_array($billingCountry, ['BR', 'IN'])) {
281
+ // Add country-specific checkout notices
282
+ my_plugin_add_country_notice($cart, $billingCountry);
283
+ }
284
+ }, 10, 1);
285
+ ```
286
+
287
+ ---
288
+
289
+ ### `customer_data_saved`
290
+ `fluent_cart/checkout/customer_data_saved` — Fired when customer checkout data is saved
291
+
292
+ * **When it runs:** This action fires when a specific piece of customer data is saved during the checkout process. The hook provides both the old and new values, making it useful for detecting changes. It fires after the data has already been persisted to the cart model.
293
+ * **Source:** `app/Hooks/Cart/WebCheckoutHandler.php`
294
+
295
+ #### Parameters:
296
+ `$data` *(array)*: Customer data change context
297
+ ```php
298
+ $data = [
299
+ 'cart' => $cart, // \FluentCart\App\Models\Cart instance
300
+ 'key' => $key, // string — the data key that changed (e.g. 'billing_country')
301
+ 'value' => $value, // mixed — the new value
302
+ 'old_value' => $prevValue, // mixed — the previous value
303
+ 'old_data' => $oldCheckoutData, // array — the full previous checkout_data array
304
+ ];
305
+ ```
306
+
307
+ #### Usage Example:
308
+ ```php
309
+ // Hook when customer checkout data key is saved
310
+ add_action('fluent_cart/checkout/customer_data_saved', function ($data) {
311
+ // Extract cart model and change key metadata
312
+ $cart = $data['cart'];
313
+ $key = $data['key'];
314
+
315
+ // React to billing country changes for tax recalculation
316
+ if ($key === 'billing_country' && $data['value'] !== $data['old_value']) {
317
+ error_log('Cart #' . $cart->id . ' billing country changed from '
318
+ . $data['old_value'] . ' to ' . $data['value']);
319
+ }
320
+ }, 10, 1);
321
+ ```
322
+
323
+ ---
324
+
325
+ ### `tax/reverse_charge_applied`
326
+ `fluent_cart/tax/reverse_charge_applied` — Fired when the EU VAT reverse charge is applied to the cart
327
+
328
+ * **When it runs:** This action fires during cart tax calculation (`TaxModule::calculateCartTax()`) when the reverse charge mechanism has just been applied — a qualifying business customer (e.g. validated EU VAT number) is liable for the VAT, so tax has been removed and inclusive product lines and fees have been adjusted to net prices. It fires after those adjustments are written into the cart's checkout data.
329
+ * **Source:** `app/Modules/Tax/TaxModule.php` (line 750)
330
+
331
+ #### Parameters:
332
+ `$data` *(array)*: Reverse charge context
333
+ ```php
334
+ $data = [
335
+ 'checkout_data' => $checkoutData, // array — the cart's checkout_data (includes the updated 'tax_data')
336
+ 'product_lines' => $productLines, // array — cart product line items, already adjusted to net prices
337
+ ];
338
+ ```
339
+
340
+ #### Usage Example:
341
+ ```php
342
+ // Hook when EU VAT reverse charge is applied to the cart
343
+ add_action('fluent_cart/tax/reverse_charge_applied', function ($data) {
344
+ // Extract tax data array from checkout data
345
+ $taxData = $data['checkout_data']['tax_data'] ?? [];
346
+
347
+ // Log or sync with an external tax service
348
+ my_tax_service_flag_reverse_charge($taxData);
349
+ }, 10, 1);
350
+ ```
351
+
352
+ ---
353
+
354
+ ### `tax/reverse_charge_removed`
355
+ `fluent_cart/tax/reverse_charge_removed` — Fired when the EU VAT reverse charge is removed from the cart
356
+
357
+ * **When it runs:** This action fires during cart tax calculation (`TaxModule::calculateCartTax()`) when a previously applicable reverse charge no longer applies (e.g. the VAT number was removed or the billing country changed). Product lines have already been restored to gross prices and the reverse charge fee adjustments cleared before it fires.
358
+ * **Source:** `app/Modules/Tax/TaxModule.php` (line 762)
359
+
360
+ #### Parameters:
361
+ `$data` *(array)*: Reverse charge context
362
+ ```php
363
+ $data = [
364
+ 'checkout_data' => $checkoutData, // array — the cart's checkout_data (includes 'tax_data')
365
+ 'product_lines' => $productLines, // array — cart product line items, restored to gross prices
366
+ ];
367
+ ```
368
+
369
+ #### Usage Example:
370
+ ```php
371
+ // Hook when EU VAT reverse charge is removed from the cart
372
+ add_action('fluent_cart/tax/reverse_charge_removed', function ($data) {
373
+ // React to the customer no longer qualifying for reverse charge
374
+ my_tax_service_clear_reverse_charge($data['checkout_data']);
375
+ }, 10, 1);
376
+ ```
377
+
378
+ ---
379
+
380
+ ## Checkout Page Rendering
381
+ All hooks in this section fire during server-side HTML rendering of the checkout page. They use output buffering, so you should `echo` (not return) any custom HTML you want to inject.
382
+
383
+ ### `before_checkout_page_start`
384
+ `fluent_cart/before_checkout_page_start` — Before the checkout page wrapper div
385
+
386
+ * **When it runs:** This action fires immediately before the main checkout page `<div>` wrapper is opened. Use it to output HTML or scripts that should appear above the entire checkout page.
387
+ * **Source:** `app/Services/Renderer/CheckoutRenderer.php`
388
+
389
+ #### Parameters:
390
+ `$data` *(array)*: The current cart
391
+ ```php
392
+ $data = [
393
+ 'cart' => $cart, // \FluentCart\App\Models\Cart instance
394
+ ];
395
+ ```
396
+
397
+ #### Usage Example:
398
+ ```php
399
+ // Hook before the checkout page wrapper div is rendered
400
+ add_action('fluent_cart/before_checkout_page_start', function ($data) {
401
+ // Extract cart model instance
402
+ $cart = $data['cart'];
403
+ // Output custom promotional banner HTML
404
+ echo '<div class="my-checkout-banner">';
405
+ echo '<p>Free shipping on orders over $50!</p>';
406
+ echo '</div>';
407
+ }, 10, 1);
408
+ ```
409
+
410
+ ---
411
+
412
+ ### `afrer_checkout_page_start`
413
+ `fluent_cart/afrer_checkout_page_start` — After the checkout page wrapper div opens
414
+
415
+ * **When it runs:** This action fires right after the main checkout page `<div>` wrapper opens. Note the typo in the hook name (`afrer` instead of `after`) — this matches the actual hook name in the source code and must be used as-is.
416
+ * **Source:** `app/Services/Renderer/CheckoutRenderer.php`
417
+
418
+ #### Parameters:
419
+ `$data` *(array)*: The current cart
420
+ ```php
421
+ $data = [
422
+ 'cart' => $cart, // \FluentCart\App\Models\Cart instance
423
+ ];
424
+ ```
425
+
426
+ #### Usage Example:
427
+ ```php
428
+ // Hook after the checkout page wrapper div opens (note 'afrer' spelling in hook name)
429
+ add_action('fluent_cart/afrer_checkout_page_start', function ($data) {
430
+ // Extract cart model instance
431
+ $cart = $data['cart'];
432
+ // Insert a progress indicator at the top of the checkout page
433
+ echo '<div class="my-checkout-progress-bar">Step 1 of 3: Checkout</div>';
434
+ }, 10, 1);
435
+ ```
436
+
437
+ ---
438
+
439
+ ### `before_checkout_form`
440
+ `fluent_cart/before_checkout_form` — Before the checkout form element
441
+
442
+ * **When it runs:** This action fires just before the `<form>` tag for the checkout form is rendered.
443
+ * **Source:** `app/Services/Renderer/CheckoutRenderer.php`
444
+
445
+ #### Parameters:
446
+ `$data` *(array)*: The current cart
447
+ ```php
448
+ $data = [
449
+ 'cart' => $cart, // \FluentCart\App\Models\Cart instance
450
+ ];
451
+ ```
452
+
453
+ #### Usage Example:
454
+ ```php
455
+ // Hook before the checkout form element is rendered
456
+ add_action('fluent_cart/before_checkout_form', function ($data) {
457
+ // Render security and trust badges HTML
458
+ echo '<div class="my-trust-badges">';
459
+ echo '<img src="/wp-content/uploads/secure-checkout.svg" alt="Secure Checkout" />';
460
+ echo '</div>';
461
+ }, 10, 1);
462
+ ```
463
+
464
+ ---
465
+
466
+ ### `checkout_form_opening`
467
+ `fluent_cart/checkout_form_opening` — Right after the checkout form tag opens
468
+
469
+ * **When it runs:** This action fires immediately after the `<form>` tag opens, before any form fields are rendered. Use it to insert hidden fields, nonce fields, or other elements that must be inside the form.
470
+ * **Source:** `app/Services/Renderer/CheckoutRenderer.php`
471
+
472
+ #### Parameters:
473
+ `$data` *(array)*: The current cart
474
+ ```php
475
+ $data = [
476
+ 'cart' => $cart, // \FluentCart\App\Models\Cart instance
477
+ ];
478
+ ```
479
+
480
+ #### Usage Example:
481
+ ```php
482
+ // Hook right after the checkout form tag opens
483
+ add_action('fluent_cart/checkout_form_opening', function ($data) {
484
+ // Add a hidden input field for tracking
485
+ echo '<input type="hidden" name="my_tracking_ref" value="' . esc_attr(my_get_tracking_ref()) . '" />';
486
+ }, 10, 1);
487
+ ```
488
+
489
+ ---
490
+
491
+ ### `before_billing_fields`
492
+ `fluent_cart/before_billing_fields` — Before billing address fields
493
+
494
+ * **When it runs:** This action fires after the name/email fields and the "create account" checkbox, but before the billing address fields section is rendered.
495
+ * **Source:** `app/Services/Renderer/CheckoutRenderer.php`
496
+
497
+ #### Parameters:
498
+ `$data` *(array)*: The current cart
499
+ ```php
500
+ $data = [
501
+ 'cart' => $cart, // \FluentCart\App\Models\Cart instance
502
+ ];
503
+ ```
504
+
505
+ #### Usage Example:
506
+ ```php
507
+ // Hook before billing address fields section
508
+ add_action('fluent_cart/before_billing_fields', function ($data) {
509
+ // Output custom billing instructions paragraph
510
+ echo '<p class="my-billing-note">Please enter your billing address exactly as it appears on your card statement.</p>';
511
+ }, 10, 1);
512
+ ```
513
+
514
+ ---
515
+
516
+ ### `before_billing_fields_section`
517
+ `fluent_cart/before_billing_fields_section` — Before the billing address field section renders
518
+
519
+ * **When it runs:** This action fires right before the billing address form section (with its heading and input fields) is rendered. It fires inside the `renderBillingAddressFields()` method, after billing field data has been prepared and filtered.
520
+ * **Source:** `app/Services/Renderer/CheckoutRenderer.php`
521
+
522
+ #### Parameters:
523
+ `$data` *(array)*: The current cart
524
+ ```php
525
+ $data = [
526
+ 'cart' => $cart, // \FluentCart\App\Models\Cart instance
527
+ ];
528
+ ```
529
+
530
+ #### Usage Example:
531
+ ```php
532
+ // Hook before the billing address field section heading renders
533
+ add_action('fluent_cart/before_billing_fields_section', function ($data) {
534
+ // Output billing section introduction heading
535
+ echo '<div class="my-billing-section-intro">';
536
+ echo '<h4>Where should we send the invoice?</h4>';
537
+ echo '</div>';
538
+ }, 10, 1);
539
+ ```
540
+
541
+ ---
542
+
543
+ ### `after_billing_fields_section`
544
+ `fluent_cart/after_billing_fields_section` — After the billing address field section
545
+
546
+ * **When it runs:** This action fires after the billing address fields section and the "ship to different address" checkbox have been rendered. It only fires when the cart requires shipping.
547
+ * **Source:** `app/Services/Renderer/CheckoutRenderer.php`
548
+
549
+ #### Parameters:
550
+ `$data` *(array)*: The current cart
551
+ ```php
552
+ $data = [
553
+ 'cart' => $cart, // \FluentCart\App\Models\Cart instance
554
+ ];
555
+ ```
556
+
557
+ #### Usage Example:
558
+ ```php
559
+ // Hook after the billing address field section
560
+ add_action('fluent_cart/after_billing_fields_section', function ($data) {
561
+ // Extract cart model instance
562
+ $cart = $data['cart'];
563
+ // Add a note between billing and shipping sections
564
+ echo '<div class="my-address-note">';
565
+ echo '<p>Shipping is calculated based on your delivery address.</p>';
566
+ echo '</div>';
567
+ }, 10, 1);
568
+ ```
569
+
570
+ ---
571
+
572
+ ### `before_shipping_fields_section`
573
+ `fluent_cart/before_shipping_fields_section` — Before the shipping address field section
574
+
575
+ * **When it runs:** This action fires right before the shipping address form section is rendered. The shipping section may be hidden via CSS if "ship to different address" is not checked.
576
+ * **Source:** `app/Services/Renderer/CheckoutRenderer.php`
577
+
578
+ #### Parameters:
579
+ `$data` *(array)*: The current cart
580
+ ```php
581
+ $data = [
582
+ 'cart' => $cart, // \FluentCart\App\Models\Cart instance
583
+ ];
584
+ ```
585
+
586
+ #### Usage Example:
587
+ ```php
588
+ // Hook before the shipping address field section
589
+ add_action('fluent_cart/before_shipping_fields_section', function ($data) {
590
+ // Output shipping address entry guidance
591
+ echo '<p class="my-shipping-note">Enter the address where you want us to deliver your order.</p>';
592
+ }, 10, 1);
593
+ ```
594
+
595
+ ---
596
+
597
+ ### `after_shipping_fields_section`
598
+ `fluent_cart/after_shipping_fields_section` — After the shipping address field section
599
+
600
+ * **When it runs:** This action fires immediately after the shipping address form section is rendered.
601
+ * **Source:** `app/Services/Renderer/CheckoutRenderer.php`
602
+
603
+ #### Parameters:
604
+ `$data` *(array)*: The current cart
605
+ ```php
606
+ $data = [
607
+ 'cart' => $cart, // \FluentCart\App\Models\Cart instance
608
+ ];
609
+ ```
610
+
611
+ #### Usage Example:
612
+ ```php
613
+ // Hook after the shipping address field section
614
+ add_action('fluent_cart/after_shipping_fields_section', function ($data) {
615
+ // Display estimated delivery timeframe note
616
+ echo '<div class="my-delivery-estimate">';
617
+ echo '<p>Estimated delivery: 3-5 business days</p>';
618
+ echo '</div>';
619
+ }, 10, 1);
620
+ ```
621
+
622
+ ---
623
+
624
+ ### `before_payment_methods`
625
+ `fluent_cart/before_payment_methods` — Before payment method options
626
+
627
+ * **When it runs:** This action fires before the payment methods section is rendered on the checkout page. It also fires in the modal checkout renderer and the Gutenberg block inner blocks renderer.
628
+ * **Source:** `app/Services/Renderer/CheckoutRenderer.php`, `app/Services/Renderer/ModalCheckoutRenderer.php`, `app/Hooks/Handlers/BlockEditors/Checkout/InnerBlocks/InnerBlocks.php`
629
+
630
+ #### Parameters:
631
+ `$data` *(array)*: The current cart
632
+ ```php
633
+ $data = [
634
+ 'cart' => $cart, // \FluentCart\App\Models\Cart instance
635
+ ];
636
+ ```
637
+
638
+ #### Usage Example:
639
+ ```php
640
+ // Hook before payment method options are rendered
641
+ add_action('fluent_cart/before_payment_methods', function ($data) {
642
+ // Display payment security notice
643
+ echo '<div class="my-payment-security-note">';
644
+ echo '<p>All transactions are encrypted and secure.</p>';
645
+ echo '</div>';
646
+ }, 10, 1);
647
+ ```
648
+
649
+ ---
650
+
651
+ ### `after_payment_methods`
652
+ `fluent_cart/after_payment_methods` — After payment method options
653
+
654
+ * **When it runs:** This action fires after the payment methods section has been rendered, before the checkout submit button.
655
+ * **Source:** `app/Services/Renderer/CheckoutRenderer.php`
656
+
657
+ #### Parameters:
658
+ `$data` *(array)*: The current cart
659
+ ```php
660
+ $data = [
661
+ 'cart' => $cart, // \FluentCart\App\Models\Cart instance
662
+ ];
663
+ ```
664
+
665
+ #### Usage Example:
666
+ ```php
667
+ // Hook after payment method options are rendered
668
+ add_action('fluent_cart/after_payment_methods', function ($data) {
669
+ // Render accepted payment gateway logo icons
670
+ echo '<div class="my-payment-icons">';
671
+ echo '<img src="/wp-content/uploads/visa.svg" alt="Visa" />';
672
+ echo '<img src="/wp-content/uploads/mastercard.svg" alt="Mastercard" />';
673
+ echo '</div>';
674
+ }, 10, 1);
675
+ ```
676
+
677
+ ---
678
+
679
+ ### `after_checkout_button`
680
+ `fluent_cart/after_checkout_button` — After the checkout submit button
681
+
682
+ * **When it runs:** This action fires immediately after the "Place order" submit button is rendered.
683
+ * **Source:** `app/Services/Renderer/CheckoutRenderer.php`
684
+
685
+ #### Parameters:
686
+ `$data` *(array)*: The current cart
687
+ ```php
688
+ $data = [
689
+ 'cart' => $cart, // \FluentCart\App\Models\Cart instance
690
+ ];
691
+ ```
692
+
693
+ #### Usage Example:
694
+ ```php
695
+ // Hook after the checkout submit button
696
+ add_action('fluent_cart/after_checkout_button', function ($data) {
697
+ // Render terms and conditions disclaimer text
698
+ echo '<p class="my-checkout-disclaimer">';
699
+ echo 'By placing your order you agree to our <a href="/terms">Terms of Service</a>.';
700
+ echo '</p>';
701
+ }, 10, 1);
702
+ ```
703
+
704
+ ---
705
+
706
+ ### `after_order_notes`
707
+ `fluent_cart/after_order_notes` — After the order notes section in the summary sidebar
708
+
709
+ * **When it runs:** This action fires after the order notes field in the checkout summary/sidebar section, inside the order summary wrapper.
710
+ * **Source:** `app/Services/Renderer/CheckoutRenderer.php`
711
+
712
+ #### Parameters:
713
+ `$data` *(array)*: The current cart
714
+ ```php
715
+ $data = [
716
+ 'cart' => $cart, // \FluentCart\App\Models\Cart instance
717
+ ];
718
+ ```
719
+
720
+ #### Usage Example:
721
+ ```php
722
+ // Hook after the order notes section in the summary sidebar
723
+ add_action('fluent_cart/after_order_notes', function ($data) {
724
+ // Render gift wrap upsell checkbox
725
+ echo '<div class="my-gift-wrap-option">';
726
+ echo '<label><input type="checkbox" name="gift_wrap" value="yes" /> Add gift wrapping (+$5.00)</label>';
727
+ echo '</div>';
728
+ }, 10, 1);
729
+ ```
730
+
731
+ ---
732
+
733
+ ### `after_order_notes_field`
734
+ `fluent_cart/after_order_notes_field` — After the order notes form field
735
+
736
+ * **When it runs:** This action fires right after the order notes textarea field is rendered, inside the `renderOrderNoteField()` method. Note that the order notes field only appears when the cart requires shipping (unless overridden by the `fluent_cart/disable_order_notes_for_digital_products` filter).
737
+ * **Source:** `app/Services/Renderer/CheckoutRenderer.php`
738
+
739
+ #### Parameters:
740
+ `$data` *(array)*: The current cart
741
+ ```php
742
+ $data = [
743
+ 'cart' => $cart, // \FluentCart\App\Models\Cart instance
744
+ ];
745
+ ```
746
+
747
+ #### Usage Example:
748
+ ```php
749
+ // Hook after the order notes form textarea field
750
+ add_action('fluent_cart/after_order_notes_field', function ($data) {
751
+ // Render example order notes hint
752
+ echo '<p class="my-notes-hint"><em>Example: Leave package at the back door.</em></p>';
753
+ }, 10, 1);
754
+ ```
755
+
756
+ ---
757
+
758
+ ### `after_checkout_form`
759
+ `fluent_cart/after_checkout_form` — After the checkout form closes
760
+
761
+ * **When it runs:** This action fires immediately after the closing `</form>` tag of the checkout form.
762
+ * **Source:** `app/Services/Renderer/CheckoutRenderer.php`
763
+
764
+ #### Parameters:
765
+ `$data` *(array)*: The current cart
766
+ ```php
767
+ $data = [
768
+ 'cart' => $cart, // \FluentCart\App\Models\Cart instance
769
+ ];
770
+ ```
771
+
772
+ #### Usage Example:
773
+ ```php
774
+ // Hook after the checkout form closes
775
+ add_action('fluent_cart/after_checkout_form', function ($data) {
776
+ // Render a support chat widget below the form
777
+ echo '<div class="my-checkout-support">';
778
+ echo '<p>Need help? <a href="#" onclick="openChat()">Chat with us</a></p>';
779
+ echo '</div>';
780
+ }, 10, 1);
781
+ ```
782
+
783
+ ---
784
+
785
+ ### `before_checkout_page_close`
786
+ `fluent_cart/before_checkout_page_close` — Before the checkout page wrapper div closes
787
+
788
+ * **When it runs:** This action fires just before the closing `</div>` of the main checkout page wrapper.
789
+ * **Source:** `app/Services/Renderer/CheckoutRenderer.php`
790
+
791
+ #### Parameters:
792
+ `$data` *(array)*: The current cart
793
+ ```php
794
+ $data = [
795
+ 'cart' => $cart, // \FluentCart\App\Models\Cart instance
796
+ ];
797
+ ```
798
+
799
+ #### Usage Example:
800
+ ```php
801
+ // Hook before the checkout page wrapper div closes
802
+ add_action('fluent_cart/before_checkout_page_close', function ($data) {
803
+ // Render money-back guarantee footer badge
804
+ echo '<div class="my-checkout-footer-badges">';
805
+ echo '<p>30-day money-back guarantee</p>';
806
+ echo '</div>';
807
+ }, 10, 1);
808
+ ```
809
+
810
+ ---
811
+
812
+ ### `after_checkout_page`
813
+ `fluent_cart/after_checkout_page` — After the entire checkout page wrapper
814
+
815
+ * **When it runs:** This action fires after the checkout page wrapper `</div>` has been closed. Use it for scripts, tracking pixels, or other content that should appear after the entire checkout page.
816
+ * **Source:** `app/Services/Renderer/CheckoutRenderer.php`
817
+
818
+ #### Parameters:
819
+ `$data` *(array)*: The current cart
820
+ ```php
821
+ $data = [
822
+ 'cart' => $cart, // \FluentCart\App\Models\Cart instance
823
+ ];
824
+ ```
825
+
826
+ #### Usage Example:
827
+ ```php
828
+ // Hook after the entire checkout page wrapper closes
829
+ add_action('fluent_cart/after_checkout_page', function ($data) {
830
+ // Extract cart model instance
831
+ $cart = $data['cart'];
832
+ // Output a tracking script after the checkout page
833
+ echo '<script>myAnalytics.trackCheckoutView({ cartId: ' . intval($cart->id) . ' });</script>';
834
+ }, 10, 1);
835
+ ```
836
+
837
+ ---
838
+
839
+ ### `before_summary_total`
840
+ `fluent_cart/checkout/before_summary_total` — Before the total line in the cart summary
841
+
842
+ * **When it runs:** This action fires in the cart summary sidebar, after the subtotal, shipping, and discount lines but before the coupon input field and the final total line.
843
+ * **Source:** `app/Services/Renderer/CartSummaryRender.php`
844
+
845
+ #### Parameters:
846
+ `$data` *(array)*: The current cart
847
+ ```php
848
+ $data = [
849
+ 'cart' => $cart, // \FluentCart\App\Models\Cart instance
850
+ ];
851
+ ```
852
+
853
+ #### Usage Example:
854
+ ```php
855
+ // Hook before the total line in the cart summary sidebar
856
+ add_action('fluent_cart/checkout/before_summary_total', function ($data) {
857
+ // Extract cart model instance
858
+ $cart = $data['cart'];
859
+ // Add a custom fee line in the summary sidebar
860
+ echo '<li class="my-custom-fee">';
861
+ echo '<span class="fct_summary_label">Processing Fee</span>';
862
+ echo '<span class="fct_summary_value">$2.50</span>';
863
+ echo '</li>';
864
+ }, 10, 1);
865
+ ```
866
+
867
+ ---
868
+
869
+ ## Cart Line Items Rendering
870
+ These hooks fire during the rendering of individual cart line items on the checkout page. They all receive the same parameter structure from `CartItemRenderer::getEventInfo()`, which includes Cart, Product, and ProductVariation model instances. Use `echo` to output custom HTML.
871
+
872
+ ### `line_meta`
873
+ `fluent_cart/cart/line_item/line_meta` — After line item content, for custom metadata
874
+
875
+ * **When it runs:** This action fires after the main item content (title, variant info, child variants) inside the item info area, but before the price section. Use it to display custom per-item metadata such as personalization details or custom options.
876
+ * **Source:** `app/Services/Renderer/CartItemRenderer.php`
877
+
878
+ #### Parameters:
879
+ `$data` *(array)*: Line item rendering context
880
+ * `item` *(array)* — The cart item data (`post_id`, `title`, `quantity`, `unit_price`, etc.)
881
+ * `cart` *(\FluentCart\App\Models\Cart|null)* — Cart instance or `null`
882
+ * `product` *(\FluentCart\App\Models\Product|null)* — Product model or `null`
883
+ * `variant` *(\FluentCart\App\Models\ProductVariation|null)* — ProductVariation model or `null`
884
+
885
+ #### Usage Example:
886
+ ```php
887
+ // Hook after cart line item content for custom metadata
888
+ add_action('fluent_cart/cart/line_item/line_meta', function ($data) {
889
+ // Extract item array from event data
890
+ $item = $data['item'];
891
+
892
+ // Display custom engraving text if present
893
+ $engraving = $item['custom_fields']['engraving'] ?? '';
894
+ if ($engraving) {
895
+ echo '<div class="my-engraving-preview">';
896
+ echo '<small>Engraving: ' . esc_html($engraving) . '</small>';
897
+ echo '</div>';
898
+ }
899
+ }, 10, 1);
900
+ ```
901
+
902
+ ---
903
+
904
+ ### `before_total`
905
+ `fluent_cart/cart/line_item/before_total` — Before the line item price/total
906
+
907
+ * **When it runs:** This action fires inside the price area of a cart line item, before the item total (and any promotional strikethrough price) is displayed.
908
+ * **Source:** `app/Services/Renderer/CartItemRenderer.php`
909
+
910
+ #### Parameters:
911
+ `$data` *(array)*: Line item rendering context (same structure as `line_meta`)
912
+
913
+ #### Usage Example:
914
+ ```php
915
+ // Hook before the cart line item price/total
916
+ add_action('fluent_cart/cart/line_item/before_total', function ($data) {
917
+ // Extract item array and calculate promotional savings amount
918
+ $item = $data['item'];
919
+ $savings = ($item['other_info']['original_price'] ?? 0) - ($item['unit_price'] ?? 0);
920
+ if ($savings > 0) {
921
+ echo '<span class="my-savings-badge">You save ' . esc_html(\FluentCart\App\Helpers\Helper::toDecimal($savings)) . '</span>';
922
+ }
923
+ }, 10, 1);
924
+ ```
925
+
926
+ ---
927
+
928
+ ### `after_total`
929
+ `fluent_cart/cart/line_item/after_total` — After the line item price/total
930
+
931
+ * **When it runs:** This action fires inside the price area of a cart line item, after the item total is displayed.
932
+ * **Source:** `app/Services/Renderer/CartItemRenderer.php`
933
+
934
+ #### Parameters:
935
+ `$data` *(array)*: Line item rendering context (same structure as `line_meta`)
936
+
937
+ #### Usage Example:
938
+ ```php
939
+ // Hook after the cart line item price/total
940
+ add_action('fluent_cart/cart/line_item/after_total', function ($data) {
941
+ // Extract item array from event data
942
+ $item = $data['item'];
943
+ $paymentType = $item['other_info']['payment_type'] ?? '';
944
+ if ($paymentType === 'subscription') {
945
+ echo '<span class="my-recurring-label"><small>Recurring</small></span>';
946
+ }
947
+ }, 10, 1);
948
+ ```
949
+
950
+ ---
951
+
952
+ ### `before_main_title`
953
+ `fluent_cart/cart/line_item/before_main_title` — Before the product title in a line item
954
+
955
+ * **When it runs:** This action fires at the very beginning of the item title area, before the quantity badge, product name, and variant title.
956
+ * **Source:** `app/Services/Renderer/CartItemRenderer.php`
957
+
958
+ #### Parameters:
959
+ `$data` *(array)*: Line item rendering context (same structure as `line_meta`)
960
+
961
+ #### Usage Example:
962
+ ```php
963
+ // Hook before the product title in a cart line item
964
+ add_action('fluent_cart/cart/line_item/before_main_title', function ($data) {
965
+ // Extract item array from event data
966
+ $item = $data['item'];
967
+ // Add a "Sale" badge before the product title if on sale
968
+ if (!empty($item['other_info']['is_on_sale'])) {
969
+ echo '<span class="my-sale-badge">Sale</span>';
970
+ }
971
+ }, 10, 1);
972
+ ```
973
+
974
+ ---
975
+
976
+ ### `after_main_title`
977
+ `fluent_cart/cart/line_item/after_main_title` — After the product title in a line item
978
+
979
+ * **When it runs:** This action fires at the end of the item title area, after the product name, variant title, and payment type information (subscription details / per-unit price).
980
+ * **Source:** `app/Services/Renderer/CartItemRenderer.php`
981
+
982
+ #### Parameters:
983
+ `$data` *(array)*: Line item rendering context (same structure as `line_meta`)
984
+
985
+ #### Usage Example:
986
+ ```php
987
+ // Hook after the product title in a cart line item
988
+ add_action('fluent_cart/cart/line_item/after_main_title', function ($data) {
989
+ // Extract item array from event data
990
+ $item = $data['item'];
991
+ // Show estimated delivery date per line item
992
+ $deliveryDays = $item['other_info']['delivery_days'] ?? null;
993
+ if ($deliveryDays) {
994
+ $date = date('M j', strtotime("+{$deliveryDays} days"));
995
+ echo '<div class="my-delivery-estimate"><small>Est. delivery: ' . esc_html($date) . '</small></div>';
996
+ }
997
+ }, 10, 1);
998
+ ```
999
+
1000
+ ---
1001
+
1002
+ ## Receipt / Thank You Page
1003
+ These hooks fire during the rendering of the thank-you / receipt page shown after a successful checkout. The `$config` parameter passed to most hooks contains the Order model instance along with view context. All rendering hooks use output buffering — use `echo` to inject custom HTML.
1004
+
1005
+ ### `before_header`
1006
+ `fluent_cart/receipt/thank_you/before_header` — Before the thank-you page header
1007
+
1008
+ * **When it runs:** This action fires at the very beginning of the thank-you page content, before the header section (which contains the success/pending icon and title).
1009
+ * **Source:** `app/Services/Renderer/Receipt/ThankYouRender.php`
1010
+
1011
+ #### Parameters:
1012
+ `$config` *(array)*: Thank-you page configuration
1013
+ ```php
1014
+ $config = [
1015
+ 'order' => $order, // \FluentCart\App\Models\Order instance
1016
+ 'is_first_time' => true|false, // bool — whether this is the first view of this receipt
1017
+ 'order_operation' => $orderOperation, // mixed — order operation context or null
1018
+ ];
1019
+ ```
1020
+
1021
+ #### Usage Example:
1022
+ ```php
1023
+ // Hook before the thank-you page header
1024
+ add_action('fluent_cart/receipt/thank_you/before_header', function ($config) {
1025
+ // Extract order model from thank-you config array
1026
+ $order = $config['order'];
1027
+ echo '<div class="my-confetti-wrapper" data-order-id="' . intval($order->id) . '"></div>';
1028
+ }, 10, 1);
1029
+ ```
1030
+
1031
+ ---
1032
+
1033
+ ### `after_header`
1034
+ `fluent_cart/receipt/thank_you/after_header` — After the thank-you page header
1035
+
1036
+ * **When it runs:** This action fires after the header section (the success/pending icon and title) is fully rendered, before the body section begins.
1037
+ * **Source:** `app/Services/Renderer/Receipt/ThankYouRender.php`
1038
+
1039
+ #### Parameters:
1040
+ `$config` *(array)*: Thank-you page configuration (same structure as `before_header`)
1041
+
1042
+ #### Usage Example:
1043
+ ```php
1044
+ // Hook after the thank-you page header
1045
+ add_action('fluent_cart/receipt/thank_you/after_header', function ($config) {
1046
+ // Extract order model from thank-you config array
1047
+ $order = $config['order'];
1048
+ if ($order->payment_status === 'paid') {
1049
+ echo '<div class="my-share-prompt">';
1050
+ echo '<p>Love your purchase? Share it with friends!</p>';
1051
+ echo '</div>';
1052
+ }
1053
+ }, 10, 1);
1054
+ ```
1055
+
1056
+ ---
1057
+
1058
+ ### `after_header_title`
1059
+ `fluent_cart/receipt/thank_you/after_header_title` — After the header title text
1060
+
1061
+ * **When it runs:** This action fires inside the header section, after the "Purchase Successful!" or "Payment Pending!" heading, but still within the header wrapper div. Use it to add a subtitle or additional context below the main title.
1062
+ * **Source:** `app/Services/Renderer/Receipt/ThankYouRender.php`
1063
+
1064
+ #### Parameters:
1065
+ `$config` *(array)*: Thank-you page configuration (same structure as `before_header`)
1066
+
1067
+ #### Usage Example:
1068
+ ```php
1069
+ // Hook after the header title text on thank-you page
1070
+ add_action('fluent_cart/receipt/thank_you/after_header_title', function ($config) {
1071
+ // Extract order model from thank-you config array
1072
+ $order = $config['order'];
1073
+ echo '<p class="my-order-ref">Order Reference: #' . esc_html($order->invoice_no) . '</p>';
1074
+ }, 10, 1);
1075
+ ```
1076
+
1077
+ ---
1078
+
1079
+ ### `before_body`
1080
+ `fluent_cart/receipt/thank_you/before_body` — Before the thank-you page body
1081
+
1082
+ * **When it runs:** This action fires after the header section and before the body section, which contains the order details, items, subscriptions, downloads, licenses, and addresses.
1083
+ * **Source:** `app/Services/Renderer/Receipt/ThankYouRender.php`
1084
+
1085
+ #### Parameters:
1086
+ `$config` *(array)*: Thank-you page configuration (same structure as `before_header`)
1087
+
1088
+ #### Usage Example:
1089
+ ```php
1090
+ // Hook before the thank-you page body section
1091
+ add_action('fluent_cart/receipt/thank_you/before_body', function ($config) {
1092
+ // Render confirmation email sent message
1093
+ echo '<div class="my-receipt-notice">';
1094
+ echo '<p>A confirmation email has been sent to your email address.</p>';
1095
+ echo '</div>';
1096
+ }, 10, 1);
1097
+ ```
1098
+
1099
+ ---
1100
+
1101
+ ### `after_body`
1102
+ `fluent_cart/receipt/thank_you/after_body` — After the thank-you page body
1103
+
1104
+ * **When it runs:** This action fires after the body section (order details, items, addresses) is fully rendered, before the page wrapper closes.
1105
+ * **Source:** `app/Services/Renderer/Receipt/ThankYouRender.php`
1106
+
1107
+ #### Parameters:
1108
+ `$config` *(array)*: Thank-you page configuration (same structure as `before_header`)
1109
+
1110
+ #### Usage Example:
1111
+ ```php
1112
+ // Hook after the thank-you page body section
1113
+ add_action('fluent_cart/receipt/thank_you/after_body', function ($config) {
1114
+ // Render recommended upsell products block
1115
+ echo '<div class="my-upsell-section">';
1116
+ echo '<h3>You might also like</h3>';
1117
+ echo '</div>';
1118
+ }, 10, 1);
1119
+ ```
1120
+
1121
+ ---
1122
+
1123
+ ### `before_order_header`
1124
+ `fluent_cart/receipt/thank_you/before_order_header` — Before the order header in the receipt body
1125
+
1126
+ * **When it runs:** This action fires inside the receipt body, before the order header area (which shows the customer greeting and order number).
1127
+ * **Source:** `app/Services/Renderer/Receipt/ThankYouRender.php`
1128
+
1129
+ #### Parameters:
1130
+ `$config` *(array)*: Thank-you page configuration (same structure as `before_header`)
1131
+
1132
+ #### Usage Example:
1133
+ ```php
1134
+ // Hook before the order header in the receipt body
1135
+ add_action('fluent_cart/receipt/thank_you/before_order_header', function ($config) {
1136
+ // Render order placement date heading
1137
+ echo '<div class="my-receipt-date">';
1138
+ echo '<p>Order placed on: ' . esc_html(date('F j, Y')) . '</p>';
1139
+ echo '</div>';
1140
+ }, 10, 1);
1141
+ ```
1142
+
1143
+ ---
1144
+
1145
+ ### `after_order_header`
1146
+ `fluent_cart/receipt/thank_you/after_order_header` — After the order header in the receipt body
1147
+
1148
+ * **When it runs:** This action fires after the order header (customer greeting, order number, and payment status message), before the tax information and order items.
1149
+ * **Source:** `app/Services/Renderer/Receipt/ThankYouRender.php`
1150
+
1151
+ #### Parameters:
1152
+ `$config` *(array)*: Thank-you page configuration (same structure as `before_header`)
1153
+
1154
+ #### Usage Example:
1155
+ ```php
1156
+ // Hook after the order header in the receipt body
1157
+ add_action('fluent_cart/receipt/thank_you/after_order_header', function ($config) {
1158
+ // Extract order model from thank-you config array
1159
+ $order = $config['order'];
1160
+ if ($order->note) {
1161
+ echo '<div class="my-order-note">';
1162
+ echo '<strong>Your note:</strong> ' . esc_html($order->note);
1163
+ echo '</div>';
1164
+ }
1165
+ }, 10, 1);
1166
+ ```
1167
+
1168
+ ---
1169
+
1170
+ ### `before_order_items`
1171
+ `fluent_cart/receipt/thank_you/before_order_items` — Before the order items list in the receipt
1172
+
1173
+ * **When it runs:** This action fires after the store tax information and before the order items table is rendered.
1174
+ * **Source:** `app/Services/Renderer/Receipt/ThankYouRender.php`
1175
+
1176
+ #### Parameters:
1177
+ `$config` *(array)*: Thank-you page configuration (same structure as `before_header`)
1178
+
1179
+ #### Usage Example:
1180
+ ```php
1181
+ // Hook before the order items list in the receipt
1182
+ add_action('fluent_cart/receipt/thank_you/before_order_items', function ($config) {
1183
+ // Render items section title
1184
+ echo '<div class="my-items-intro"><h4>Here is what you ordered:</h4></div>';
1185
+ }, 10, 1);
1186
+ ```
1187
+
1188
+ ---
1189
+
1190
+ ### `after_order_items`
1191
+ `fluent_cart/receipt/thank_you/after_order_items` — After the order items list in the receipt
1192
+
1193
+ * **When it runs:** This action fires after the order items table (including the totals breakdown), before the subscription items, downloads, licenses, and address sections.
1194
+ * **Source:** `app/Services/Renderer/Receipt/ThankYouRender.php`
1195
+
1196
+ #### Parameters:
1197
+ `$config` *(array)*: Thank-you page configuration (same structure as `before_header`)
1198
+
1199
+ #### Usage Example:
1200
+ ```php
1201
+ // Hook after the order items list in the receipt
1202
+ add_action('fluent_cart/receipt/thank_you/after_order_items', function ($config) {
1203
+ // Extract order model from thank-you config array
1204
+ $order = $config['order'];
1205
+ // Show a customer referral code block after items list
1206
+ echo '<div class="my-referral-block">';
1207
+ echo '<p>Share your referral code <strong>REF-' . intval($order->customer_id) . '</strong> and earn 10% credit!</p>';
1208
+ echo '</div>';
1209
+ }, 10, 1);
1210
+ ```
1211
+
1212
+ ---
1213
+
1214
+ ### `before_footer_buttons`
1215
+ `fluent_cart/receipt/thank_you/before_footer_buttons` — Before the footer buttons
1216
+
1217
+ * **When it runs:** This action fires in the receipt footer area, before the "View Order" and "Download Receipt" buttons are rendered.
1218
+ * **Source:** `app/Services/Renderer/Receipt/ThankYouRender.php`
1219
+
1220
+ #### Parameters:
1221
+ `$config` *(array)*: Thank-you page configuration (same structure as `before_header`)
1222
+
1223
+ #### Usage Example:
1224
+ ```php
1225
+ // Hook before the thank-you page footer buttons
1226
+ add_action('fluent_cart/receipt/thank_you/before_footer_buttons', function ($config) {
1227
+ // Render thank you footer message
1228
+ echo '<div class="my-footer-message">';
1229
+ echo '<p>Thank you for shopping with us!</p>';
1230
+ echo '</div>';
1231
+ }, 10, 1);
1232
+ ```
1233
+
1234
+ ---
1235
+
1236
+ ### `after_footer_buttons`
1237
+ `fluent_cart/receipt/thank_you/after_footer_buttons` — After the footer buttons
1238
+
1239
+ * **When it runs:** This action fires in the receipt footer area, after the "View Order" and "Download Receipt" buttons have been rendered.
1240
+ * **Source:** `app/Services/Renderer/Receipt/ThankYouRender.php`
1241
+
1242
+ #### Parameters:
1243
+ `$config` *(array)*: Thank-you page configuration (same structure as `before_header`)
1244
+
1245
+ #### Usage Example:
1246
+ ```php
1247
+ // Hook after the thank-you page footer buttons
1248
+ add_action('fluent_cart/receipt/thank_you/after_footer_buttons', function ($config) {
1249
+ // Render social share buttons
1250
+ echo '<div class="my-social-share">';
1251
+ echo '<p>Follow us on social media for updates and exclusive offers.</p>';
1252
+ echo '</div>';
1253
+ }, 10, 1);
1254
+ ```
1255
+
1256
+ ---
1257
+
1258
+ ### `after_receipt`
1259
+ `fluent_cart/after_receipt` — After the entire receipt/thank-you page
1260
+
1261
+ * **When it runs:** This action fires after the complete thank-you page has been rendered, including the footer. It fires on every receipt view (both first-time and returning visits). This hook is also present in the legacy `thank_you.php` view template.
1262
+ * **Source:** `app/Services/Renderer/Receipt/ThankYouRender.php`, `app/Views/invoice/thank_you.php`
1263
+
1264
+ #### Parameters:
1265
+ `$data` *(array)*: Order and view context
1266
+ ```php
1267
+ $data = [
1268
+ 'order' => $order, // \FluentCart\App\Models\Order instance
1269
+ 'is_first_time' => true|false, // bool — whether this is the first view of this receipt
1270
+ 'order_operation' => $orderOperation, // mixed — order operation context or null
1271
+ ];
1272
+ ```
1273
+
1274
+ #### Usage Example:
1275
+ ```php
1276
+ // Hook after the entire receipt/thank-you page renders
1277
+ add_action('fluent_cart/after_receipt', function ($data) {
1278
+ // Extract order model instance
1279
+ $order = $data['order'];
1280
+
1281
+ // Render a customer satisfaction survey link
1282
+ echo '<div class="my-survey-widget">';
1283
+ echo '<h4>How was your experience?</h4>';
1284
+ echo '<a href="/survey?order=' . intval($order->id) . '">Take a quick survey</a>';
1285
+ echo '</div>';
1286
+ }, 10, 1);
1287
+ ```
1288
+
1289
+ ---
1290
+
1291
+ ### `after_receipt_first_time`
1292
+ `fluent_cart/after_receipt_first_time` — Only on the first receipt view (for conversion tracking)
1293
+
1294
+ * **When it runs:** This action fires only on the first time a customer views the receipt page after a purchase. It does not fire on subsequent visits to the same receipt URL. This is the ideal hook for firing conversion tracking pixels, analytics events, or affiliate postback URLs.
1295
+ * **Source:** `app/Services/Renderer/Receipt/ThankYouRender.php`, `app/Views/invoice/thank_you.php`
1296
+
1297
+ #### Parameters:
1298
+ `$data` *(array)*: Order and operation context
1299
+ ```php
1300
+ $data = [
1301
+ 'order' => $order, // \FluentCart\App\Models\Order instance
1302
+ 'order_operation' => $orderOperation, // mixed — order operation context or null
1303
+ ];
1304
+ ```
1305
+
1306
+ #### Usage Example:
1307
+ ```php
1308
+ // Hook on the first receipt view (ideal for conversion tracking)
1309
+ add_action('fluent_cart/after_receipt_first_time', function ($data) {
1310
+ // Extract order model and formatted decimal total
1311
+ $order = $data['order'];
1312
+ $total = \FluentCart\App\Helpers\Helper::toDecimal($order->total_amount);
1313
+
1314
+ // Fire Meta Facebook conversion tracking pixel
1315
+ echo '<script>';
1316
+ echo 'fbq("track", "Purchase", { value: ' . esc_js($total) . ', currency: "' . esc_js($order->currency) . '" });';
1317
+ echo '</script>';
1318
+
1319
+ // Fire Google Ads conversion tracking script
1320
+ echo '<script>';
1321
+ echo 'gtag("event", "conversion", { send_to: "AW-XXXXX/YYYYY", value: ' . esc_js($total) . ', currency: "' . esc_js($order->currency) . '", transaction_id: "' . esc_js($order->invoice_no) . '" });';
1322
+ echo '</script>';
1323
+ }, 10, 1);
1324
+ ```
1325
+
1326
+ ---
1327
+
1328
+ ### `before_render_redirect_page`
1329
+ `fluent_cart/before_render_redirect_page` — Before the payment redirect/receipt page renders
1330
+
1331
+ * **When it runs:** This action fires at the very beginning of the receipt shortcode handler, before any receipt or redirect page content is rendered. It provides the raw URL parameters used to identify the order and transaction. Use it for early validation, logging, or to set up resources needed by the receipt page.
1332
+ * **Source:** `app/Hooks/Handlers/ShortCodes/ReceiptHandler.php`
1333
+
1334
+ #### Parameters:
1335
+ `$data` *(array)*: URL parameters for the receipt/redirect
1336
+ ```php
1337
+ $data = [
1338
+ 'order_hash' => $orderHash, // string — the order UUID from the URL
1339
+ 'trx_hash' => $transactionHash, // string — the transaction hash from the URL
1340
+ 'method' => $method, // string — the payment method slug
1341
+ 'is_receipt' => $isReceipt, // bool — true if this is a receipt page, false if redirect
1342
+ ];
1343
+ ```
1344
+
1345
+ #### Usage Example:
1346
+ ```php
1347
+ // Hook before the payment redirect or receipt page renders
1348
+ add_action('fluent_cart/before_render_redirect_page', function ($data) {
1349
+ // Log receipt page visits for debugging payment callbacks
1350
+ if ($data['is_receipt'] && $data['order_hash']) {
1351
+ error_log('Receipt page visited for order: ' . $data['order_hash']
1352
+ . ' via method: ' . $data['method']);
1353
+ }
1354
+ }, 10, 1);
1355
+ ```