fluentcart-developer 2.0.2 → 2.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) 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 +184 -18
  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
  50. package/dist/skills/fluentcart-developer/references/client-integration-contract.md +0 -299
  51. package/dist/skills/fluentcart-developer/references/device-licensing-and-hardware-tracking.md +0 -241
  52. package/dist/skills/fluentcart-developer/references/trial-abuse-prevention.md +0 -304
@@ -1,1202 +1,1202 @@
1
- # Filter Hooks: Cart & Checkout
2
-
3
- All filters related to the shopping flow from Cart to checkout.
4
-
5
- ---
6
-
7
- ## Cart Items & Validation
8
-
9
- ### `cart/item_modify`
10
- `fluent_cart/cart/item_modify` — Modify cart item variation before adding
11
-
12
- * **When it runs:** Applied when a product variation is being added to the cart or when an existing cart item is updated. Allows you to modify the variation object before processing, or return `null` to block the item.
13
- * **Source:** `api/Resource/FrontendResource/CartResource.php` (lines 44, 307)
14
-
15
- #### Parameters:
16
- * `$variation` *(\FluentCart\App\Models\ProductVariation|null)* — The product variation model instance
17
- * `$data` *(array)* — Context data (`['item_id' => 42, 'quantity' => 1]`)
18
- * **Returns:** *(\FluentCart\App\Models\ProductVariation|null)* — The modified variation, or `null` to prevent adding
19
-
20
- #### Usage Example:
21
- ```php
22
- // Filter product variation before adding to cart or updating quantity
23
- add_filter('fluent_cart/cart/item_modify', function ($variation, $data) {
24
- if (!$variation) {
25
- return $variation;
26
- }
27
-
28
- // Block a specific variation ID from being added to cart
29
- if ($variation->id === 99) {
30
- return null;
31
- }
32
-
33
- return $variation;
34
- }, 10, 2);
35
- ```
36
-
37
- ---
38
-
39
- ### `item_max_quantity`
40
- `fluent_cart/item_max_quantity` — Limit the maximum quantity for a cart item
41
-
42
- * **When it runs:** Applied immediately after the variation is resolved, before adding to cart. Allows capping or adjusting the requested quantity.
43
- * **Source:** `api/Resource/FrontendResource/CartResource.php` (line 54)
44
-
45
- #### Parameters:
46
- * `$quantity` *(int)* — The requested quantity
47
- * `$data` *(array)* — Context data (`['variation' => ProductVariation, 'product' => Product]`)
48
- * **Returns:** *(int)* — The (possibly capped) quantity
49
-
50
- #### Usage Example:
51
- ```php
52
- // Filter maximum allowed purchase quantity for a cart item
53
- add_filter('fluent_cart/item_max_quantity', function ($quantity, $data) {
54
- // Extract variation model from context
55
- $variation = $data['variation'];
56
-
57
- // Limit subscription products to maximum quantity of 1
58
- if ($variation->payment_type === 'subscription') {
59
- return 1;
60
- }
61
-
62
- // Cap all item quantities at maximum of 10
63
- return min($quantity, 10);
64
- }, 10, 2);
65
- ```
66
-
67
- ---
68
-
69
- ### `cart/custom_item_quantity_changed`
70
- `fluent_cart/cart/custom_item_quantity_changed` — Handle custom item quantity changes
71
-
72
- * **When it runs:** Fires when the quantity of a custom (externally-managed) item already in the cart is changed. Recalculates pricing or validates quantity.
73
- * **Source:** `api/Resource/FrontendResource/CartResource.php` (line 269)
74
-
75
- #### Parameters:
76
- * `$existingItem` *(object)* — The existing cart item object
77
- * `$data` *(array)* — Context data (`['old_quantity' => 2, 'new_quantity' => 3, 'is_custom' => true]`)
78
- * **Returns:** *(object)* — The modified item object with updated quantity and totals
79
-
80
- #### Usage Example:
81
- ```php
82
- // Filter quantity change for custom externally-managed cart item
83
- add_filter('fluent_cart/cart/custom_item_quantity_changed', function ($variation, $data) {
84
- if (empty($data['is_custom'])) {
85
- return $variation;
86
- }
87
-
88
- // Recalculate line total based on new quantity input
89
- $variation->quantity = $data['new_quantity'];
90
- $variation->line_total = $variation->price * $data['new_quantity'];
91
-
92
- return $variation;
93
- }, 10, 2);
94
- ```
95
-
96
- ---
97
-
98
- ### `cart/validate_custom_item`
99
- `fluent_cart/cart/validate_custom_item` — Validate a custom or externally-managed cart item
100
-
101
- * **When it runs:** Fires when a custom (non-FluentCart) item is being added to the cart. Used to validate and construct the item object stored in the cart.
102
- * **Source:** `api/Resource/FrontendResource/CartResource.php` (line 289), `app/Http/Routes/WebRoutes.php` (line 99)
103
-
104
- #### Parameters:
105
- * `$existingItem` *(object|null)* — The existing item object, or `null` for new items
106
- * `$data` *(array)* — Context data (`['item_id' => string, 'quantity' => int, 'is_custom' => true]`)
107
- * **Returns:** *(object)* — A variation-like object with required cart item properties
108
-
109
- #### Usage Example:
110
- ```php
111
- // Validate and construct custom item object for cart
112
- add_filter('fluent_cart/cart/validate_custom_item', function ($variation, $data) {
113
- if (!(bool) $data['is_custom']) {
114
- return $variation;
115
- }
116
-
117
- // Build custom item object with required cart item properties
118
- return (object) [
119
- 'item_id' => absint($data['item_id']),
120
- 'object_id' => absint($data['item_id']),
121
- 'title' => 'Custom Product',
122
- 'price' => 2500, // $25.00 in cents
123
- 'quantity' => (int) $data['quantity'],
124
- 'payment_type' => 'one_time',
125
- 'is_custom' => true,
126
- ];
127
- }, 10, 2);
128
- ```
129
-
130
- ---
131
-
132
- ### `cart_item_product_variation`
133
- `fluent_cart/cart_item_product_variation` — Provide a fallback product variation for a cart item
134
-
135
- * **When it runs:** Fires when a product variation cannot be found in the database during cart operations. Serves as fallback mechanism.
136
- * **Source:** `api/Resource/FrontendResource/CartResource.php` (line 631)
137
-
138
- #### Parameters:
139
- * `$productVariation` *(\FluentCart\App\Models\ProductVariation|null)* — Always `null` at this point
140
- * `$itemId` *(int)* — The variation/item ID being looked up
141
- * `$incrementBy` *(int)* — The quantity increment value
142
- * `$existingItemsArray` *(array)* — The current cart items array
143
- * **Returns:** *(\FluentCart\App\Models\ProductVariation|null)* — A variation model instance, or `null`
144
-
145
- #### Usage Example:
146
- ```php
147
- // Provide fallback product variation when variation is not found in DB
148
- add_filter('fluent_cart/cart_item_product_variation', function ($variation, $itemId, $incrementBy, $existingItems) {
149
- if (!$variation && $itemId > 10000) {
150
- // Resolve variation object from external service
151
- return MyExternalService::getVariation($itemId);
152
- }
153
- return $variation;
154
- }, 10, 4);
155
- ```
156
-
157
- ---
158
-
159
- ### `cart/can_purchase`
160
- `fluent_cart/cart/can_purchase` — Determine whether a variation can be added to the cart
161
-
162
- * **When it runs:** Fires after the built-in `canPurchase()` check on the variation model, inside `Cart::addItem()`.
163
- * **Source:** `app/Models/Cart.php` (line 333)
164
-
165
- #### Parameters:
166
- * `$canPurchase` *(true|\WP_Error)* — Result of built-in purchase validation
167
- * `$data` *(array)* — Context data (`['cart' => Cart, 'variation' => ProductVariation, 'quantity' => int]`)
168
- * **Returns:** *(true|\WP_Error)* — Return `true` to allow purchase, or `WP_Error` to block
169
-
170
- #### Usage Example:
171
- ```php
172
- // Filter whether product variation can be added to cart
173
- add_filter('fluent_cart/cart/can_purchase', function ($canPurchase, $data) {
174
- if (is_wp_error($canPurchase)) {
175
- return $canPurchase;
176
- }
177
-
178
- $cart = $data['cart'];
179
- $variation = $data['variation'];
180
-
181
- // Limit cart to maximum of 5 unique items
182
- $existingItems = $cart->getItems();
183
- if (count($existingItems) >= 5 && !isset($existingItems[$variation->id])) {
184
- return new \WP_Error(
185
- 'cart_limit',
186
- __('You can only have up to 5 different items in your cart.', 'fluent-cart')
187
- );
188
- }
189
-
190
- return true;
191
- }, 10, 2);
192
- ```
193
-
194
- ---
195
-
196
- ### `cart/estimated_total`
197
- `fluent_cart/cart/estimated_total` — Filter the cart estimated total
198
-
199
- * **When it runs:** Applied when calculating cart estimated total in `Cart::getEstimatedTotal()` and web checkout handler.
200
- * **Source:** `app/Models/Cart.php` (line 766), `app/Hooks/Cart/WebCheckoutHandler.php` (line 358)
201
-
202
- #### Parameters:
203
- * `$total` *(int)* — The cart total in cents
204
- * `$data` *(array)* — Context data (`['cart' => Cart]`)
205
- * **Returns:** *(int)* — The modified cart total in cents
206
-
207
- #### Usage Example:
208
- ```php
209
- // Filter cart estimated total calculation amount
210
- add_filter('fluent_cart/cart/estimated_total', function ($total, $data) {
211
- // Extract cart model instance from context
212
- $cart = $data['cart'];
213
-
214
- // Add flat processing fee of $2.00 in cents
215
- $processingFee = 200;
216
- return $total + $processingFee;
217
- }, 10, 2);
218
- ```
219
-
220
- ---
221
-
222
- ### `cart_cookie_minutes`
223
- `fluent_cart/cart_cookie_minutes` — Control cart cookie expiration time
224
-
225
- * **When it runs:** Fires when setting the cart hash cookie. The default value is a Unix timestamp (time() + 30 days).
226
- * **Source:** `api/Cookie/Cookie.php` (line 22)
227
-
228
- #### Parameters:
229
- * `$expireTime` *(int)* — Unix timestamp for cookie expiration
230
- * **Returns:** *(int)* — The Unix timestamp when cookie expires
231
-
232
- #### Usage Example:
233
- ```php
234
- // Filter cart cookie expiration Unix timestamp
235
- add_filter('fluent_cart/cart_cookie_minutes', function ($expireTime) {
236
- // Set cart cookie expiration to 7 days from now
237
- return time() + (7 * DAY_IN_SECONDS);
238
- });
239
- ```
240
-
241
- ---
242
-
243
- ### `variation/can_purchase_bundle`
244
- `fluent_cart/variation/can_purchase_bundle` — Validate whether a bundle product can be purchased
245
-
246
- * **When it runs:** Fires during `canPurchase()` on a `ProductVariation` when product is a bundle.
247
- * **Source:** `app/Models/ProductVariation.php` (line 265)
248
-
249
- #### Parameters:
250
- * `$result` *(null)* — Always `null` initially
251
- * `$data` *(array)* — Context data (`['variation' => ProductVariation, 'quantity' => int]`)
252
- * **Returns:** *(null|true|false|\WP_Error)* — `null`/`true` to allow, `false` for generic error, `WP_Error` to block with custom message
253
-
254
- #### Usage Example:
255
- ```php
256
- // Validate stock for bundled child items during bundle purchase
257
- add_filter('fluent_cart/variation/can_purchase_bundle', function ($result, $data) {
258
- $variation = $data['variation'];
259
- $quantity = (int) $data['quantity'];
260
-
261
- // Iterate through bundle children to verify sufficient stock
262
- $children = $variation->bundleChildren()->get();
263
- foreach ($children as $child) {
264
- if ($child->available < ($child->pivot->quantity * $quantity)) {
265
- return new \WP_Error(
266
- 'bundle_stock',
267
- sprintf(__('%s does not have enough stock.', 'fluent-cart'), $child->title)
268
- );
269
- }
270
- }
271
-
272
- return $result;
273
- }, 10, 2);
274
- ```
275
-
276
- ---
277
-
278
- ## Checkout Validation
279
-
280
- ### `checkout/validate_before_process`
281
- `fluent_cart/checkout/validate_before_process` — Pre-validate the checkout before processing
282
-
283
- * **When it runs:** Fires early in `placeOrder()` flow before field or product validation. First chance to reject checkout attempt.
284
- * **Source:** `api/Checkout/CheckoutApi.php` (line 83)
285
-
286
- #### Parameters:
287
- * `$validation` *(true)* — Always `true` initially
288
- * `$data` *(array)* — Full checkout submission data (billing address, payment method, form fields, etc.)
289
- * **Returns:** *(true|\WP_Error)* — `true` to continue, `WP_Error` to abort checkout
290
-
291
- #### Usage Example:
292
- ```php
293
- // Pre-validate checkout submission before processing order
294
- add_filter('fluent_cart/checkout/validate_before_process', function ($validation, $data) {
295
- // Query cart model instance using submitted cart hash
296
- $cart = \FluentCart\App\Models\Cart::query()
297
- ->where('cart_hash', $data['cart_hash'])
298
- ->first();
299
-
300
- // Enforce minimum order total requirement of $5.00
301
- if ($cart && $cart->getEstimatedTotal() < 500) {
302
- return new \WP_Error(
303
- 'min_order',
304
- __('Minimum order amount is $5.00.', 'fluent-cart')
305
- );
306
- }
307
-
308
- return $validation;
309
- }, 10, 2);
310
- ```
311
-
312
- ---
313
-
314
- ### `cart/tax_behavior`
315
- `fluent_cart/cart/tax_behavior` — Filter tax behavior amount for the cart
316
-
317
- * **When it runs:** Fires during order creation in `CheckoutApi::placeOrder()`. Determines tax behavior value for order total.
318
- * **Source:** `api/Checkout/CheckoutApi.php` (line 171)
319
-
320
- #### Parameters:
321
- * `$behavior` *(int)* — Default tax behavior value (`0`)
322
- * `$data` *(array)* — Context data (`['cart' => Cart]`)
323
- * **Returns:** *(int)* — Tax behavior value (`0` for exclusive, `1` for inclusive)
324
-
325
- #### Usage Example:
326
- ```php
327
- // Filter tax behavior value for cart order total calculation
328
- add_filter('fluent_cart/cart/tax_behavior', function ($behavior, $data) {
329
- $cart = $data['cart'];
330
-
331
- // Force tax-inclusive behavior for specific European countries
332
- $country = $cart->checkout_data['billing_address']['country'] ?? '';
333
- if (in_array($country, ['DE', 'FR', 'GB'])) {
334
- return 1; // Tax-inclusive
335
- }
336
-
337
- return $behavior;
338
- }, 10, 2);
339
- ```
340
-
341
- ---
342
-
343
- ### `checkout/validate_data`
344
- `fluent_cart/checkout/validate_data` — Add or modify checkout validation errors
345
-
346
- * **When it runs:** Fires after core field, shipping, and terms validation has run, before order creation.
347
- * **Source:** `api/Checkout/CheckoutApi.php` (line 890)
348
-
349
- #### Parameters:
350
- * `$errors` *(array)* — Associative array of validation errors keyed by field name
351
- * `$data` *(array)* — Context data (`['data' => submittedData, 'cart' => Cart]`)
352
- * **Returns:** *(array)* — Modified errors array (empty array means validation passes)
353
-
354
- #### Usage Example:
355
- ```php
356
- // Append custom field validation errors to checkout submission
357
- add_filter('fluent_cart/checkout/validate_data', function ($errors, $data) {
358
- $formData = $data['data'];
359
-
360
- // Require billing phone number for physical products requiring shipping
361
- $cart = $data['cart'];
362
- if ($cart->requireShipping() && empty($formData['billing_address']['phone'])) {
363
- $errors['billing_phone'] = [
364
- 'required' => __('Phone number is required for physical products.', 'fluent-cart'),
365
- ];
366
- }
367
-
368
- return $errors;
369
- }, 10, 2);
370
- ```
371
-
372
- ---
373
-
374
- ## Checkout Page Rendering
375
-
376
- ### `checkout_page_css_classes`
377
- `fluent_cart/checkout_page_css_classes` — Modify checkout page CSS classes
378
-
379
- * **When it runs:** Fires when rendering the checkout page container wrapper element.
380
- * **Source:** `app/Services/Renderer/CheckoutRenderer.php` (line 144)
381
-
382
- #### Parameters:
383
- * `$classNames` *(array)* — Array of CSS class strings
384
- * `$data` *(array)* — Context data (`['cart' => Cart]`)
385
- * **Returns:** *(array)* — Modified array of CSS class strings
386
-
387
- #### Usage Example:
388
- ```php
389
- // Filter checkout page wrapper container CSS classes
390
- add_filter('fluent_cart/checkout_page_css_classes', function ($classes, $data) {
391
- $cart = $data['cart'];
392
-
393
- // Add custom class when cart contains subscription items
394
- if ($cart->hasSubscription()) {
395
- $classes[] = 'has-subscription-items';
396
- }
397
-
398
- return $classes;
399
- }, 10, 2);
400
- ```
401
-
402
- ---
403
-
404
- ### `checkout_page_notices`
405
- `fluent_cart/checkout_page_notices` — Add custom notices to checkout page
406
-
407
- * **When it runs:** Fires during checkout page rendering to inject notices displayed at the top of checkout form.
408
- * **Source:** `app/Services/Renderer/CheckoutRenderer.php` (line 170)
409
-
410
- #### Parameters:
411
- * `$notices` *(array)* — Array of notice items (empty by default)
412
- * `$data` *(array)* — Context data (`['cart' => Cart]`)
413
- * **Returns:** *(array)* — Array of notice items to display
414
-
415
- #### Usage Example:
416
- ```php
417
- // Inject custom notice messages onto top of checkout page
418
- add_filter('fluent_cart/checkout_page_notices', function ($notices, $data) {
419
- $cart = $data['cart'];
420
-
421
- // Display free shipping qualification threshold notice
422
- $total = $cart->getEstimatedTotal();
423
- if ($total < 5000 && $cart->requireShipping()) {
424
- $notices[] = [
425
- 'type' => 'info',
426
- 'message' => sprintf(
427
- __('Add %s more to qualify for free shipping!', 'fluent-cart'),
428
- '$' . number_format((5000 - $total) / 100, 2)
429
- ),
430
- ];
431
- }
432
-
433
- return $notices;
434
- }, 10, 2);
435
- ```
436
-
437
- ---
438
-
439
- ### `checkout_renderer/billing_fields`
440
- `fluent_cart/checkout_renderer/billing_fields` — Modify rendered billing fields on checkout page
441
-
442
- * **When it runs:** Fires after billing address fields have been assembled and rearranged in checkout renderer.
443
- * **Source:** `app/Services/Renderer/CheckoutRenderer.php` (line 448)
444
-
445
- #### Parameters:
446
- * `$billingFields` *(array)* — Array of billing field definitions with rendered state
447
- * `$data` *(array)* — Context data (`['checkout_renderer' => renderer, 'cart' => Cart]`)
448
- * **Returns:** *(array)* — Modified billing fields array
449
-
450
- #### Usage Example:
451
- ```php
452
- // Filter rendered billing field schema definitions on checkout page
453
- add_filter('fluent_cart/checkout_renderer/billing_fields', function ($fields, $data) {
454
- // Remove company field from rendered billing fields schema
455
- foreach ($fields as $sectionKey => &$section) {
456
- if (isset($section['schema']) && is_array($section['schema'])) {
457
- unset($section['schema']['billing_company']);
458
- }
459
- }
460
-
461
- return $fields;
462
- }, 10, 2);
463
- ```
464
-
465
- ---
466
-
467
- ### `checkout_renderer/shipping_fields`
468
- `fluent_cart/checkout_renderer/shipping_fields` — Modify rendered shipping fields on checkout page
469
-
470
- * **When it runs:** Fires after shipping address fields have been assembled and validated in checkout renderer.
471
- * **Source:** `app/Services/Renderer/CheckoutRenderer.php` (line 521)
472
-
473
- #### Parameters:
474
- * `$shippingFields` *(array)* — Array of shipping field definitions
475
- * `$data` *(array)* — Context data (`['checkout_renderer' => renderer, 'cart' => Cart]`)
476
- * **Returns:** *(array)* — Modified shipping fields array
477
-
478
- #### Usage Example:
479
- ```php
480
- // Filter rendered shipping field schema definitions on checkout page
481
- add_filter('fluent_cart/checkout_renderer/shipping_fields', function ($fields, $data) {
482
- // Mark shipping address line 2 as a required field
483
- foreach ($fields as &$field) {
484
- if (isset($field['name']) && $field['name'] === 'shipping_address_2') {
485
- $field['required'] = 'yes';
486
- }
487
- }
488
-
489
- return $fields;
490
- }, 10, 2);
491
- ```
492
-
493
- ---
494
-
495
- ### `disable_order_notes_for_digital_products`
496
- `fluent_cart/disable_order_notes_for_digital_products` — Control order notes visibility for digital products
497
-
498
- * **When it runs:** Fires when checkout renderer decides whether to show order notes textarea.
499
- * **Source:** `app/Services/Renderer/CheckoutRenderer.php` (line 560)
500
-
501
- #### Parameters:
502
- * `$disable` *(bool)* — Whether to hide order notes for digital-only carts (default: `true`)
503
- * `$data` *(array)* — Context data (`['cart' => Cart]`)
504
- * **Returns:** *(bool)* — `true` to hide order notes for digital products, `false` to show
505
-
506
- #### Usage Example:
507
- ```php
508
- // Filter order notes textarea visibility for digital-only carts
509
- add_filter('fluent_cart/disable_order_notes_for_digital_products', function ($disable, $data) {
510
- // Always render order notes field even for digital products
511
- return false;
512
- }, 10, 2);
513
- ```
514
-
515
- ---
516
-
517
- ### `checkout_active_payment_methods`
518
- `fluent_cart/checkout_active_payment_methods` — Filter active payment methods on checkout page
519
-
520
- * **When it runs:** Fires when listing available payment methods on standard and modal checkout renderers.
521
- * **Source:** `app/Services/Renderer/CheckoutRenderer.php` (line 652), `app/Services/Renderer/ModalCheckoutRenderer.php` (line 450)
522
-
523
- #### Parameters:
524
- * `$activePaymentMethods` *(array)* — Array of payment method instances
525
- * `$data` *(array)* — Context data (`['cart' => Cart]`)
526
- * **Returns:** *(array)* — Modified array of payment method instances
527
-
528
- #### Usage Example:
529
- ```php
530
- // Filter active payment method gateway instances on checkout page
531
- add_filter('fluent_cart/checkout_active_payment_methods', function ($methods, $data) {
532
- $cart = $data['cart'];
533
-
534
- // Exclude Cash on Delivery payment option for orders over $500
535
- if ($cart->getEstimatedTotal() > 50000) {
536
- $methods = array_filter($methods, function ($method) {
537
- return $method->getMeta('route') !== 'cod';
538
- });
539
- }
540
-
541
- return array_values($methods);
542
- }, 10, 2);
543
- ```
544
-
545
- ---
546
-
547
- ### `checkout_page_order_button_text`
548
- `fluent_cart/checkout_page_order_button_text` — Customize place order button text
549
-
550
- * **When it runs:** Fires when checkout submit button is being rendered to change its label.
551
- * **Source:** `app/Services/Renderer/CheckoutRenderer.php` (line 705)
552
-
553
- #### Parameters:
554
- * `$text` *(string)* — Button text (default: `'Place order'`)
555
- * **Returns:** *(string)* — Modified button text
556
-
557
- #### Usage Example:
558
- ```php
559
- // Customize place order submit button text on checkout page
560
- add_filter('fluent_cart/checkout_page_order_button_text', function ($text) {
561
- // Change Place Order button label to Complete Purchase
562
- return __('Complete Purchase', 'fluent-cart');
563
- });
564
- ```
565
-
566
- ---
567
-
568
- ### `payment_method_list_class`
569
- `fluent_cart_payment_method_list_class` — Add CSS classes to a payment method wrapper
570
-
571
- * **When it runs:** Fires when rendering each payment method option in standard and modal checkout. Note legacy prefix (`fluent_cart_`).
572
- * **Source:** `app/Services/Renderer/CheckoutRenderer.php` (line 797), `app/Services/Renderer/ModalCheckoutRenderer.php` (line 569)
573
-
574
- #### Parameters:
575
- * `$class` *(string)* — CSS class string (default: `''`)
576
- * `$data` *(array)* — Context data (`['route' => string, 'method_title' => string, 'method_style' => string]`)
577
- * **Returns:** *(string)* — Modified CSS class string
578
-
579
- #### Usage Example:
580
- ```php
581
- // Filter CSS class string for payment method container wrapper (legacy prefix)
582
- add_filter('fluent_cart_payment_method_list_class', function ($class, $data) {
583
- // Add highlight class for Cash on Delivery payment option
584
- if ($data['route'] === 'cod') {
585
- return $class . ' payment-method-highlighted';
586
- }
587
- return $class;
588
- }, 10, 2);
589
- ```
590
-
591
- ---
592
-
593
- ### `modal_checkout/filter_active_payment_methods`
594
- `fluent_cart/modal_checkout/filter_active_payment_methods` — Restrict payment methods in modal checkout
595
-
596
- * **When it runs:** Fires during modal checkout rendering after active payment methods are resolved.
597
- * **Source:** `app/Services/Renderer/ModalCheckoutRenderer.php` (line 455)
598
-
599
- #### Parameters:
600
- * `$selectedMethods` *(array)* — Empty array by default
601
- * **Returns:** *(array)* — Array of payment method route slugs to show (`['stripe', 'paypal']`)
602
-
603
- #### Usage Example:
604
- ```php
605
- // Filter active payment method route slugs shown in modal checkout
606
- add_filter('fluent_cart/modal_checkout/filter_active_payment_methods', function ($methods) {
607
- // Restrict modal checkout to show only Stripe payment method
608
- return ['stripe'];
609
- });
610
- ```
611
-
612
- ---
613
-
614
- ### `enable_modal_checkout`
615
- `fluent_cart/enable_modal_checkout` — Enable or disable modal checkout
616
-
617
- * **When it runs:** Fires when checking whether modal popup checkout is enabled (default: `false`).
618
- * **Source:** `app/Helpers/Helper.php` (line 1710)
619
-
620
- #### Parameters:
621
- * `$enabled` *(bool)* — Whether modal checkout is enabled (default: `false`)
622
- * **Returns:** *(bool)* — `true` to enable modal checkout, `false` for standard page
623
-
624
- #### Usage Example:
625
- ```php
626
- // Filter whether modal popup checkout mode is enabled
627
- add_filter('fluent_cart/enable_modal_checkout', function ($enabled) {
628
- // Enable modal checkout feature
629
- return true;
630
- });
631
- ```
632
-
633
- ---
634
-
635
- ## Checkout Data & Session
636
-
637
- ### `checkout/checkout_data_changed`
638
- `fluent_cart/checkout/checkout_data_changed` — Modify checkout data after a change is detected
639
-
640
- * **When it runs:** Fires after checkout session data is saved to modify response data returned to browser.
641
- * **Source:** `app/Hooks/Cart/WebCheckoutHandler.php` (lines 495, 1115)
642
-
643
- #### Parameters:
644
- * `$checkoutData` *(array)* — Checkout change response data (`message`, `fragments`, `estimated_total`, etc.)
645
- * `$data` *(array)* — Context data (`['cart' => Cart]`)
646
- * **Returns:** *(array)* — Modified checkout response data
647
-
648
- #### Usage Example:
649
- ```php
650
- // Filter response data payload returned after checkout session data change
651
- add_filter('fluent_cart/checkout/checkout_data_changed', function ($checkoutData, $data) {
652
- // Append custom notice string to checkout change response payload
653
- $checkoutData['custom_notice'] = __('Your order qualifies for a bonus!', 'fluent-cart');
654
- return $checkoutData;
655
- }, 10, 2);
656
- ```
657
-
658
- ---
659
-
660
- ### `checkout/cart_updated`
661
- `fluent_cart/checkout/cart_updated` — Filter the cart update response data
662
-
663
- * **When it runs:** Fires when cart is updated during checkout session (e.g. items added or removed).
664
- * **Source:** `app/Hooks/Cart/WebCheckoutHandler.php` (line 683)
665
-
666
- #### Parameters:
667
- * `$data` *(array)* — Response data (`['cart' => Cart]`)
668
- * **Returns:** *(array)* — Modified response data array
669
-
670
- #### Usage Example:
671
- ```php
672
- // Filter cart update response payload during checkout session
673
- add_filter('fluent_cart/checkout/cart_updated', function ($data) {
674
- // Append item count and free shipping eligibility flags
675
- $cart = $data['cart'];
676
- $data['item_count'] = count($cart->getItems());
677
- $data['free_shipping_eligible'] = $cart->getEstimatedTotal() >= 5000;
678
- return $data;
679
- });
680
- ```
681
-
682
- ---
683
-
684
- ### `checkout/before_patch_checkout_data`
685
- `fluent_cart/checkout/before_patch_checkout_data` — Modify fill data before patching checkout session
686
-
687
- * **When it runs:** Fires before checkout session data is persisted to database.
688
- * **Source:** `app/Hooks/Cart/WebCheckoutHandler.php` (lines 791, 967)
689
-
690
- #### Parameters:
691
- * `$fillData` *(array)* — Data to merge into cart checkout session (`checkout_data`, `cart_data`, `hook_changes`)
692
- * `$data` *(array)* — Context data (`['cart' => Cart, 'prev_data' => array, 'changes' => array, 'all_data' => array]`)
693
- * **Returns:** *(array)* — Modified fill data
694
-
695
- #### Usage Example:
696
- ```php
697
- // Filter fill data merged into checkout session before persisting to DB
698
- add_filter('fluent_cart/checkout/before_patch_checkout_data', function ($fillData, $data) {
699
- $cart = $data['cart'];
700
- $changes = $data['changes'];
701
-
702
- // Recalculate custom surcharge when billing country changes
703
- if (isset($changes['billing_country'])) {
704
- $surcharge = MyModule::calculateSurcharge($changes['billing_country']);
705
- $fillData['checkout_data']['custom_surcharge'] = $surcharge;
706
- $fillData['hook_changes']['custom'] = true;
707
- }
708
-
709
- return $fillData;
710
- }, 10, 2);
711
- ```
712
-
713
- ---
714
-
715
- ### `checkout/after_patch_checkout_data_fragments`
716
- `fluent_cart/checkout/after_patch_checkout_data_fragments` — Modify HTML fragments returned after patching checkout data
717
-
718
- * **When it runs:** Fires after checkout session is patched and HTML fragments for AJAX response are generated.
719
- * **Source:** `app/Hooks/Cart/WebCheckoutHandler.php` (line 901)
720
-
721
- #### Parameters:
722
- * `$fragments` *(array)* — Associative array of HTML fragment selectors and content
723
- * `$data` *(array)* — Context data (`['cart' => Cart, 'changes' => array]`)
724
- * **Returns:** *(array)* — Modified fragments array
725
-
726
- #### Usage Example:
727
- ```php
728
- // Filter HTML response fragments swapped into checkout page via AJAX
729
- add_filter('fluent_cart/checkout/after_patch_checkout_data_fragments', function ($fragments, $data) {
730
- // Extract cart model instance
731
- $cart = $data['cart'];
732
-
733
- // Inject custom surcharge display HTML fragment selector
734
- $fragments['.custom-surcharge-display'] = [
735
- 'content' => '<span class="custom-surcharge">' . esc_html('$5.00') . '</span>',
736
- 'type' => 'replace',
737
- ];
738
-
739
- return $fragments;
740
- }, 10, 2);
741
- ```
742
-
743
- ---
744
-
745
- ### `apply_order_bump`
746
- `fluent_cart/apply_order_bump` — Handle order bump application on checkout page
747
-
748
- * **When it runs:** Fires when customer toggles order bump on checkout page.
749
- * **Source:** `app/Hooks/Cart/WebCheckoutHandler.php` (line 1144)
750
-
751
- #### Parameters:
752
- * `$response` *(\WP_Error)* — Default error response
753
- * `$data` *(array)* — Context data (`['bump_id' => int, 'cart' => Cart, 'request_data' => array]`)
754
- * **Returns:** *(array|\WP_Error)* — Return array with success data to apply bump, or `WP_Error` to reject
755
-
756
- #### Usage Example:
757
- ```php
758
- // Handle order bump application request on checkout page
759
- add_filter('fluent_cart/apply_order_bump', function ($response, $data) {
760
- $bumpId = $data['bump_id'];
761
- $cart = $data['cart'];
762
-
763
- // Look up order bump definition model
764
- $bump = MyOrderBumpModule::find($bumpId);
765
- if (!$bump) {
766
- return $response;
767
- }
768
-
769
- // Add bump variation item to cart
770
- $cart->addItem($bump->variation_id, 1);
771
-
772
- return [
773
- 'message' => __('Order bump applied!', 'fluent-cart'),
774
- 'cart' => $cart,
775
- ];
776
- }, 10, 2);
777
- ```
778
-
779
- ---
780
-
781
- ## Checkout Field Schema
782
-
783
- ### `checkout_address_fields`
784
- `fluent_cart/checkout_address_fields` — Modify address field definitions
785
-
786
- * **When it runs:** Fires when address field schema is built in `CartCheckoutHelper`. Controls fields in billing/shipping address sections.
787
- * **Source:** `app/Helpers/CartCheckoutHelper.php` (line 692)
788
-
789
- #### Parameters:
790
- * `$fields` *(array)* — Associative array of address field definitions
791
- * **Returns:** *(array)* — Modified fields array
792
-
793
- #### Usage Example:
794
- ```php
795
- // Modify address field definitions for both billing and shipping
796
- add_filter('fluent_cart/checkout_address_fields', function ($fields) {
797
- // Add custom company name address field definition
798
- $fields['company'] = [
799
- 'label' => __('Company Name', 'fluent-cart'),
800
- 'type' => 'text',
801
- 'required' => false,
802
- ];
803
-
804
- return $fields;
805
- });
806
- ```
807
-
808
- ---
809
-
810
- ### `checkout_billing_fields`
811
- `fluent_cart/checkout_billing_fields` — Modify billing address field schema
812
-
813
- * **When it runs:** Fires when billing fields are being assembled in `CartCheckoutHelper`.
814
- * **Source:** `app/Helpers/CartCheckoutHelper.php` (line 730)
815
-
816
- #### Parameters:
817
- * `$fields` *(array)* — Billing field definitions organized in sections
818
- * `$data` *(array)* — Context data (`['viewData' => array, 'customer' => Customer, 'labels' => array, 'has_subscription' => bool]`)
819
- * **Returns:** *(array)* — Modified billing fields array
820
-
821
- #### Usage Example:
822
- ```php
823
- // Modify billing address section field schema definitions
824
- add_filter('fluent_cart/checkout_billing_fields', function ($fields, $data) {
825
- // Enforce required phone field for subscription carts
826
- if ($data['has_subscription']) {
827
- if (isset($fields['address_section']['schema']['billing_phone'])) {
828
- $fields['address_section']['schema']['billing_phone']['required'] = 'yes';
829
- }
830
- }
831
-
832
- return $fields;
833
- }, 10, 2);
834
- ```
835
-
836
- ---
837
-
838
- ### `checkout_shipping_fields`
839
- `fluent_cart/checkout_shipping_fields` — Modify shipping address field schema
840
-
841
- * **When it runs:** Fires when shipping address fields are assembled in `CartCheckoutHelper`.
842
- * **Source:** `app/Helpers/CartCheckoutHelper.php` (line 771)
843
-
844
- #### Parameters:
845
- * `$fields` *(array)* — Shipping field definitions organized in sections
846
- * `$data` *(array)* — Context data (`['viewData' => array, 'labels' => array]`)
847
- * **Returns:** *(array)* — Modified shipping fields array
848
-
849
- #### Usage Example:
850
- ```php
851
- // Modify shipping address section field schema definitions
852
- add_filter('fluent_cart/checkout_shipping_fields', function ($fields, $data) {
853
- // Remove shipping address line 2 field from schema
854
- if (isset($fields['address_section']['schema']['shipping_address_2'])) {
855
- unset($fields['address_section']['schema']['shipping_address_2']);
856
- }
857
-
858
- return $fields;
859
- }, 10, 2);
860
- ```
861
-
862
- ---
863
-
864
- ### `checkout_signup_fields`
865
- `fluent_cart/checkout_signup_fields` — Modify account signup form fields
866
-
867
- * **When it runs:** Fires when guest checkout signup form fields (username, email, password) are assembled.
868
- * **Source:** `app/Helpers/CartCheckoutHelper.php` (line 846)
869
-
870
- #### Parameters:
871
- * `$fields` *(array)* — Associative array of signup field definitions (`user_login`, `user_pass`)
872
- * **Returns:** *(array)* — Modified signup fields array
873
-
874
- #### Usage Example:
875
- ```php
876
- // Modify guest checkout registration signup form field schema
877
- add_filter('fluent_cart/checkout_signup_fields', function ($fields) {
878
- // Enforce required password field during signup
879
- if (isset($fields['user_pass'])) {
880
- $fields['user_pass']['required'] = 'yes';
881
- }
882
-
883
- return $fields;
884
- });
885
- ```
886
-
887
- ---
888
-
889
- ### `checkout_login_fields`
890
- `fluent_cart/checkout_login_fields` — Modify checkout login form fields
891
-
892
- * **When it runs:** Fires when login form fields (username, password) are assembled for checkout page.
893
- * **Source:** `app/Helpers/CartCheckoutHelper.php` (line 872)
894
-
895
- #### Parameters:
896
- * `$fields` *(array)* — Associative array of login field definitions (`user_login`, `user_pass`)
897
- * **Returns:** *(array)* — Modified login fields array
898
-
899
- #### Usage Example:
900
- ```php
901
- // Modify returning customer login form field schema on checkout
902
- add_filter('fluent_cart/checkout_login_fields', function ($fields) {
903
- // Update username field label and placeholder text
904
- if (isset($fields['user_login'])) {
905
- $fields['user_login']['label'] = __('Email Address', 'fluent-cart');
906
- $fields['user_login']['placeholder'] = __('Enter your email', 'fluent-cart');
907
- }
908
-
909
- return $fields;
910
- });
911
- ```
912
-
913
- ---
914
-
915
- ### `checkout_coupon_fields`
916
- `fluent_cart/checkout_coupon_fields` — Modify coupon input fields
917
-
918
- * **When it runs:** Fires when coupon code input fields are assembled for checkout page.
919
- * **Source:** `app/Helpers/CartCheckoutHelper.php` (line 925)
920
-
921
- #### Parameters:
922
- * `$fields` *(array)* — Associative array of coupon field definitions
923
- * **Returns:** *(array)* — Modified coupon fields array
924
-
925
- #### Usage Example:
926
- ```php
927
- // Modify coupon input form fields schema on checkout page
928
- add_filter('fluent_cart/checkout_coupon_fields', function ($fields) {
929
- // Customize coupon code input field placeholder string
930
- if (isset($fields['coupon_code'])) {
931
- $fields['coupon_code']['placeholder'] = __('Got a discount code?', 'fluent-cart');
932
- }
933
-
934
- return $fields;
935
- });
936
- ```
937
-
938
- ---
939
-
940
- ### `checkout_page_name_fields_schema`
941
- `fluent_cart/checkout_page_name_fields_schema` — Modify name fields on checkout page
942
-
943
- * **When it runs:** Fires when checkout name fields schema (first name, last name, email, company) is being built.
944
- * **Source:** `app/Services/Renderer/CheckoutFieldsSchema.php` (line 86)
945
-
946
- #### Parameters:
947
- * `$nameFields` *(array)* — Associative array of name/email field definitions
948
- * `$data` *(array)* — Context data (`['cart' => Cart, 'scope' => 'billing'|'shipping']`)
949
- * **Returns:** *(array)* — Modified name fields array
950
-
951
- #### Usage Example:
952
- ```php
953
- // Modify checkout page name and email fields schema
954
- add_filter('fluent_cart/checkout_page_name_fields_schema', function ($fields, $data) {
955
- // Pre-fill email field for logged-in user
956
- if ($userId = get_current_user_id()) {
957
- $user = get_userdata($userId);
958
- if (!empty($fields['billing_email']) && empty($fields['billing_email']['value'])) {
959
- $fields['billing_email']['value'] = $user->user_email;
960
- }
961
- }
962
-
963
- return $fields;
964
- }, 10, 2);
965
- ```
966
-
967
- ---
968
-
969
- ### `fields/address_base_fields`
970
- `fluent_cart/fields/address_base_fields` — Modify base address field definitions
971
-
972
- * **When it runs:** Fires when low-level address field definitions are assembled in `CheckoutFieldsSchema`.
973
- * **Source:** `app/Services/Renderer/CheckoutFieldsSchema.php` (line 320)
974
-
975
- #### Parameters:
976
- * `$fields` *(array)* — Array of base address field definitions
977
- * `$data` *(array)* — Context data (`['config' => array, 'scope' => 'billing'|'shipping', 'requirements' => array]`)
978
- * **Returns:** *(array)* — Modified base address fields array
979
-
980
- #### Usage Example:
981
- ```php
982
- // Modify low-level base address field definitions
983
- add_filter('fluent_cart/fields/address_base_fields', function ($fields, $data) {
984
- // Make billing city field optional
985
- if ($data['scope'] === 'billing') {
986
- foreach ($fields as &$field) {
987
- if (isset($field['name']) && $field['name'] === 'billing_city') {
988
- unset($field['required']);
989
- }
990
- }
991
- }
992
-
993
- return $fields;
994
- }, 10, 2);
995
- ```
996
-
997
- ---
998
-
999
- ### `default_billing_country_for_checkout`
1000
- `fluent_cart/default_billing_country_for_checkout` — Set default billing country
1001
-
1002
- * **When it runs:** Fires when determining default billing country for checkout form. Default uses Cloudflare IP geo-detection.
1003
- * **Source:** `app/Helpers/AddressHelper.php` (line 639)
1004
-
1005
- #### Parameters:
1006
- * `$countryCode` *(string)* — Detected country code (ISO 3166-1 alpha-2)
1007
- * **Returns:** *(string)* — Valid ISO 3166-1 alpha-2 country code
1008
-
1009
- #### Usage Example:
1010
- ```php
1011
- // Filter default billing country code for checkout form
1012
- add_filter('fluent_cart/default_billing_country_for_checkout', function ($countryCode) {
1013
- // Default to US if geo-detection yields empty country code
1014
- if (empty($countryCode)) {
1015
- return 'US';
1016
- }
1017
-
1018
- return $countryCode;
1019
- });
1020
- ```
1021
-
1022
- ---
1023
-
1024
- ## Checkout Localization
1025
-
1026
- ### `checkout/localize_data`
1027
- `fluent_cart/checkout/localize_data` — Modify checkout JavaScript localized data
1028
-
1029
- * **When it runs:** Fires when checkout page assets are enqueued to pass data to JS via `wp_localize_script()`.
1030
- * **Source:** `app/Modules/Templating/AssetLoader.php` (line 497)
1031
-
1032
- #### Parameters:
1033
- * `$data` *(array)* — Localized data array (`fluentcart_checkout_vars`)
1034
- * `$cart` *(\FluentCart\App\Models\Cart)* — Cart model instance
1035
- * **Returns:** *(array)* — Modified localized data array
1036
-
1037
- #### Usage Example:
1038
- ```php
1039
- // Modify localized data passed to checkout JavaScript frontend
1040
- add_filter('fluent_cart/checkout/localize_data', function ($data, $cart) {
1041
- // Add custom module config payload to checkout JS variables
1042
- $data['fluentcart_checkout_vars']['my_module'] = [
1043
- 'enabled' => true,
1044
- 'endpoint' => rest_url('my-module/v1/validate'),
1045
- ];
1046
-
1047
- return $data;
1048
- }, 10, 2);
1049
- ```
1050
-
1051
- ---
1052
-
1053
- ### `payment_methods_with_custom_checkout_buttons`
1054
- `fluent_cart/payment_methods_with_custom_checkout_buttons` — Register payment methods with custom buttons
1055
-
1056
- * **When it runs:** Fires when building checkout localized data to identify gateways rendering custom submit buttons (e.g. PayPal smart buttons).
1057
- * **Source:** `app/Modules/Templating/AssetLoader.php` (line 465)
1058
-
1059
- #### Parameters:
1060
- * `$methods` *(array)* — Array of payment method route slugs with custom buttons (default: `[]`)
1061
- * **Returns:** *(array)* — Modified array of payment method route slugs
1062
-
1063
- #### Usage Example:
1064
- ```php
1065
- // Register payment gateway route slugs that render custom buttons
1066
- add_filter('fluent_cart/payment_methods_with_custom_checkout_buttons', function ($methods) {
1067
- // Append custom payment gateway route slug to list
1068
- $methods[] = 'my_custom_gateway';
1069
- return $methods;
1070
- });
1071
- ```
1072
-
1073
- ---
1074
-
1075
- ### `instant_checkout/allowed_redirect_hosts`
1076
- `fluent_cart/instant_checkout/allowed_redirect_hosts` — Control allowed redirect hosts for instant checkout
1077
-
1078
- * **When it runs:** Fires during instant URL checkout when `redirect_to` parameter is provided.
1079
- * **Source:** `app/Http/Routes/WebRoutes.php` (line 155)
1080
-
1081
- #### Parameters:
1082
- * `$allowedHosts` *(array)* — Array of allowed hostnames (default: current site host)
1083
- * `$data` *(array)* — Context data (`['allowed_hosts' => array]`)
1084
- * **Returns:** *(array)* — Array of allowed redirect hostnames
1085
-
1086
- #### Usage Example:
1087
- ```php
1088
- // Filter allowed redirect hostnames for instant URL checkout
1089
- add_filter('fluent_cart/instant_checkout/allowed_redirect_hosts', function ($hosts) {
1090
- // Allow instant checkout redirects to subdomains
1091
- $hosts[] = 'shop.example.com';
1092
- $hosts[] = 'members.example.com';
1093
- return $hosts;
1094
- });
1095
- ```
1096
-
1097
- ---
1098
-
1099
- ## Tax & VAT
1100
-
1101
- ### `checkout/is_business`
1102
- `fluent_cart/checkout/is_business` — Filter whether checkout is a business (B2B) purchase
1103
-
1104
- * **When it runs:** Applied in `TaxModule::storeBusinessInfoOnOrder()` right after order is placed to decide whether to persist business info.
1105
- * **Source:** `app/Modules/Tax/TaxModule.php` (line 1047)
1106
-
1107
- #### Parameters:
1108
- * `$isBusinessCheckout` *(bool)* — Whether checkout is treated as business purchase
1109
- * `$data` *(array)* — Context data (`['checkout_data' => array, 'order' => Order]`)
1110
- * **Returns:** *(bool)* — `true` to treat as business purchase
1111
-
1112
- #### Usage Example:
1113
- ```php
1114
- // Filter whether checkout is treated as a business (B2B) purchase
1115
- add_filter('fluent_cart/checkout/is_business', function ($isBusiness, $data) {
1116
- // Treat checkout as B2B if company name is provided
1117
- $company = $data['checkout_data']['form_data']['company_name'] ?? '';
1118
-
1119
- return $isBusiness || $company !== '';
1120
- }, 10, 2);
1121
- ```
1122
-
1123
- ---
1124
-
1125
- ### `tax/reverse_charge_line_adjustment`
1126
- `fluent_cart/tax/reverse_charge_line_adjustment` — Filter per-line price adjustment when reverse charge is applied
1127
-
1128
- * **When it runs:** Applied in `TaxModule::calculateCartTax()` while applying EU VAT reverse charge to tax-inclusive product lines.
1129
- * **Source:** `app/Modules/Tax/TaxModule.php` (line 689)
1130
-
1131
- #### Parameters:
1132
- * `$adjustment` *(int)* — Amount in cents to deduct from line unit price
1133
- * `$data` *(array)* — Context data (`['line' => array, 'rc_mode' => string]`)
1134
- * **Returns:** *(int)* — Adjustment amount in cents
1135
-
1136
- #### Usage Example:
1137
- ```php
1138
- // Filter price deduction amount when EU VAT reverse charge is applied
1139
- add_filter('fluent_cart/tax/reverse_charge_line_adjustment', function ($adjustment, $data) {
1140
- // Keep gross price without deduction for target product post ID 123
1141
- if (($data['line']['post_id'] ?? 0) === 123) {
1142
- return 0;
1143
- }
1144
-
1145
- return $adjustment;
1146
- }, 10, 2);
1147
- ```
1148
-
1149
- ---
1150
-
1151
- ### `tax/reverse_charge_notice_text`
1152
- `fluent_cart/tax/reverse_charge_notice_text` — Filter reverse charge notice on receipts and invoices
1153
-
1154
- * **When it runs:** Applied in `TaxModule::getReverseChargeNoticeText()` whenever reverse charge notice is rendered on receipts, emails, or PDFs.
1155
- * **Source:** `app/Modules/Tax/TaxModule.php` (line 1688)
1156
-
1157
- #### Parameters:
1158
- * `$text` *(string)* — Notice text (default: `'Reverse charge — Article 196, Council Directive 2006/112/EC. Customer is liable for VAT.'`)
1159
- * **Returns:** *(string)* — Notice text to display
1160
-
1161
- #### Usage Example:
1162
- ```php
1163
- // Filter reverse charge notice text shown on receipts and invoices
1164
- add_filter('fluent_cart/tax/reverse_charge_notice_text', function ($text) {
1165
- // Apply intra-EU supply of goods reverse charge notice wording
1166
- return __('Reverse charge — Article 138, Council Directive 2006/112/EC. Customer is liable for VAT.', 'my-plugin');
1167
- }, 10, 1);
1168
- ```
1169
-
1170
- ---
1171
-
1172
- ### `tax/validate_eu_vat_number`
1173
- `fluent_cart/tax/validate_eu_vat_number` — Short-circuit EU VAT number validation with custom validator
1174
-
1175
- * **When it runs:** Applied in `TaxModule::validateEuVatNumber()` before contacting EU VIES SOAP service. Returning non-null short-circuits remote call.
1176
- * **Source:** `app/Modules/Tax/TaxModule.php` (line 1430)
1177
-
1178
- #### Parameters:
1179
- * `$result` *(null)* — Always `null` by default
1180
- * `$data` *(array)* — Context data (`['country_code' => string, 'vat_number' => string]`)
1181
- * **Returns:** *(null|array|\WP_Error)* — `null` for default VIES call, `array` for successful result, `WP_Error` for error
1182
-
1183
- #### Usage Example:
1184
- ```php
1185
- // Short-circuit EU VAT number validation with custom API validator
1186
- add_filter('fluent_cart/tax/validate_eu_vat_number', function ($result, $data) {
1187
- // Perform remote lookup via custom VAT API validator
1188
- $response = my_vat_api_check($data['country_code'], $data['vat_number']);
1189
-
1190
- if (!$response['ok']) {
1191
- return new \WP_Error('invalid_vat', __('The VAT number could not be validated.', 'my-plugin'));
1192
- }
1193
-
1194
- return [
1195
- 'country' => $data['country_code'],
1196
- 'vat_number' => $data['vat_number'],
1197
- 'valid' => true,
1198
- 'name' => $response['company_name'],
1199
- 'address' => $response['address'],
1200
- ];
1201
- }, 10, 2);
1202
- ```
1
+ # Filter Hooks: Cart & Checkout
2
+
3
+ All filters related to the shopping flow from Cart to checkout.
4
+
5
+ ---
6
+
7
+ ## Cart Items & Validation
8
+
9
+ ### `cart/item_modify`
10
+ `fluent_cart/cart/item_modify` — Modify cart item variation before adding
11
+
12
+ * **When it runs:** Applied when a product variation is being added to the cart or when an existing cart item is updated. Allows you to modify the variation object before processing, or return `null` to block the item.
13
+ * **Source:** `api/Resource/FrontendResource/CartResource.php` (lines 44, 307)
14
+
15
+ #### Parameters:
16
+ * `$variation` *(\FluentCart\App\Models\ProductVariation|null)* — The product variation model instance
17
+ * `$data` *(array)* — Context data (`['item_id' => 42, 'quantity' => 1]`)
18
+ * **Returns:** *(\FluentCart\App\Models\ProductVariation|null)* — The modified variation, or `null` to prevent adding
19
+
20
+ #### Usage Example:
21
+ ```php
22
+ // Filter product variation before adding to cart or updating quantity
23
+ add_filter('fluent_cart/cart/item_modify', function ($variation, $data) {
24
+ if (!$variation) {
25
+ return $variation;
26
+ }
27
+
28
+ // Block a specific variation ID from being added to cart
29
+ if ($variation->id === 99) {
30
+ return null;
31
+ }
32
+
33
+ return $variation;
34
+ }, 10, 2);
35
+ ```
36
+
37
+ ---
38
+
39
+ ### `item_max_quantity`
40
+ `fluent_cart/item_max_quantity` — Limit the maximum quantity for a cart item
41
+
42
+ * **When it runs:** Applied immediately after the variation is resolved, before adding to cart. Allows capping or adjusting the requested quantity.
43
+ * **Source:** `api/Resource/FrontendResource/CartResource.php` (line 54)
44
+
45
+ #### Parameters:
46
+ * `$quantity` *(int)* — The requested quantity
47
+ * `$data` *(array)* — Context data (`['variation' => ProductVariation, 'product' => Product]`)
48
+ * **Returns:** *(int)* — The (possibly capped) quantity
49
+
50
+ #### Usage Example:
51
+ ```php
52
+ // Filter maximum allowed purchase quantity for a cart item
53
+ add_filter('fluent_cart/item_max_quantity', function ($quantity, $data) {
54
+ // Extract variation model from context
55
+ $variation = $data['variation'];
56
+
57
+ // Limit subscription products to maximum quantity of 1
58
+ if ($variation->payment_type === 'subscription') {
59
+ return 1;
60
+ }
61
+
62
+ // Cap all item quantities at maximum of 10
63
+ return min($quantity, 10);
64
+ }, 10, 2);
65
+ ```
66
+
67
+ ---
68
+
69
+ ### `cart/custom_item_quantity_changed`
70
+ `fluent_cart/cart/custom_item_quantity_changed` — Handle custom item quantity changes
71
+
72
+ * **When it runs:** Fires when the quantity of a custom (externally-managed) item already in the cart is changed. Recalculates pricing or validates quantity.
73
+ * **Source:** `api/Resource/FrontendResource/CartResource.php` (line 269)
74
+
75
+ #### Parameters:
76
+ * `$existingItem` *(object)* — The existing cart item object
77
+ * `$data` *(array)* — Context data (`['old_quantity' => 2, 'new_quantity' => 3, 'is_custom' => true]`)
78
+ * **Returns:** *(object)* — The modified item object with updated quantity and totals
79
+
80
+ #### Usage Example:
81
+ ```php
82
+ // Filter quantity change for custom externally-managed cart item
83
+ add_filter('fluent_cart/cart/custom_item_quantity_changed', function ($variation, $data) {
84
+ if (empty($data['is_custom'])) {
85
+ return $variation;
86
+ }
87
+
88
+ // Recalculate line total based on new quantity input
89
+ $variation->quantity = $data['new_quantity'];
90
+ $variation->line_total = $variation->price * $data['new_quantity'];
91
+
92
+ return $variation;
93
+ }, 10, 2);
94
+ ```
95
+
96
+ ---
97
+
98
+ ### `cart/validate_custom_item`
99
+ `fluent_cart/cart/validate_custom_item` — Validate a custom or externally-managed cart item
100
+
101
+ * **When it runs:** Fires when a custom (non-FluentCart) item is being added to the cart. Used to validate and construct the item object stored in the cart.
102
+ * **Source:** `api/Resource/FrontendResource/CartResource.php` (line 289), `app/Http/Routes/WebRoutes.php` (line 99)
103
+
104
+ #### Parameters:
105
+ * `$existingItem` *(object|null)* — The existing item object, or `null` for new items
106
+ * `$data` *(array)* — Context data (`['item_id' => string, 'quantity' => int, 'is_custom' => true]`)
107
+ * **Returns:** *(object)* — A variation-like object with required cart item properties
108
+
109
+ #### Usage Example:
110
+ ```php
111
+ // Validate and construct custom item object for cart
112
+ add_filter('fluent_cart/cart/validate_custom_item', function ($variation, $data) {
113
+ if (!(bool) $data['is_custom']) {
114
+ return $variation;
115
+ }
116
+
117
+ // Build custom item object with required cart item properties
118
+ return (object) [
119
+ 'item_id' => absint($data['item_id']),
120
+ 'object_id' => absint($data['item_id']),
121
+ 'title' => 'Custom Product',
122
+ 'price' => 2500, // $25.00 in cents
123
+ 'quantity' => (int) $data['quantity'],
124
+ 'payment_type' => 'one_time',
125
+ 'is_custom' => true,
126
+ ];
127
+ }, 10, 2);
128
+ ```
129
+
130
+ ---
131
+
132
+ ### `cart_item_product_variation`
133
+ `fluent_cart/cart_item_product_variation` — Provide a fallback product variation for a cart item
134
+
135
+ * **When it runs:** Fires when a product variation cannot be found in the database during cart operations. Serves as fallback mechanism.
136
+ * **Source:** `api/Resource/FrontendResource/CartResource.php` (line 631)
137
+
138
+ #### Parameters:
139
+ * `$productVariation` *(\FluentCart\App\Models\ProductVariation|null)* — Always `null` at this point
140
+ * `$itemId` *(int)* — The variation/item ID being looked up
141
+ * `$incrementBy` *(int)* — The quantity increment value
142
+ * `$existingItemsArray` *(array)* — The current cart items array
143
+ * **Returns:** *(\FluentCart\App\Models\ProductVariation|null)* — A variation model instance, or `null`
144
+
145
+ #### Usage Example:
146
+ ```php
147
+ // Provide fallback product variation when variation is not found in DB
148
+ add_filter('fluent_cart/cart_item_product_variation', function ($variation, $itemId, $incrementBy, $existingItems) {
149
+ if (!$variation && $itemId > 10000) {
150
+ // Resolve variation object from external service
151
+ return MyExternalService::getVariation($itemId);
152
+ }
153
+ return $variation;
154
+ }, 10, 4);
155
+ ```
156
+
157
+ ---
158
+
159
+ ### `cart/can_purchase`
160
+ `fluent_cart/cart/can_purchase` — Determine whether a variation can be added to the cart
161
+
162
+ * **When it runs:** Fires after the built-in `canPurchase()` check on the variation model, inside `Cart::addItem()`.
163
+ * **Source:** `app/Models/Cart.php` (line 333)
164
+
165
+ #### Parameters:
166
+ * `$canPurchase` *(true|\WP_Error)* — Result of built-in purchase validation
167
+ * `$data` *(array)* — Context data (`['cart' => Cart, 'variation' => ProductVariation, 'quantity' => int]`)
168
+ * **Returns:** *(true|\WP_Error)* — Return `true` to allow purchase, or `WP_Error` to block
169
+
170
+ #### Usage Example:
171
+ ```php
172
+ // Filter whether product variation can be added to cart
173
+ add_filter('fluent_cart/cart/can_purchase', function ($canPurchase, $data) {
174
+ if (is_wp_error($canPurchase)) {
175
+ return $canPurchase;
176
+ }
177
+
178
+ $cart = $data['cart'];
179
+ $variation = $data['variation'];
180
+
181
+ // Limit cart to maximum of 5 unique items
182
+ $existingItems = $cart->getItems();
183
+ if (count($existingItems) >= 5 && !isset($existingItems[$variation->id])) {
184
+ return new \WP_Error(
185
+ 'cart_limit',
186
+ __('You can only have up to 5 different items in your cart.', 'fluent-cart')
187
+ );
188
+ }
189
+
190
+ return true;
191
+ }, 10, 2);
192
+ ```
193
+
194
+ ---
195
+
196
+ ### `cart/estimated_total`
197
+ `fluent_cart/cart/estimated_total` — Filter the cart estimated total
198
+
199
+ * **When it runs:** Applied when calculating cart estimated total in `Cart::getEstimatedTotal()` and web checkout handler.
200
+ * **Source:** `app/Models/Cart.php` (line 766), `app/Hooks/Cart/WebCheckoutHandler.php` (line 358)
201
+
202
+ #### Parameters:
203
+ * `$total` *(int)* — The cart total in cents
204
+ * `$data` *(array)* — Context data (`['cart' => Cart]`)
205
+ * **Returns:** *(int)* — The modified cart total in cents
206
+
207
+ #### Usage Example:
208
+ ```php
209
+ // Filter cart estimated total calculation amount
210
+ add_filter('fluent_cart/cart/estimated_total', function ($total, $data) {
211
+ // Extract cart model instance from context
212
+ $cart = $data['cart'];
213
+
214
+ // Add flat processing fee of $2.00 in cents
215
+ $processingFee = 200;
216
+ return $total + $processingFee;
217
+ }, 10, 2);
218
+ ```
219
+
220
+ ---
221
+
222
+ ### `cart_cookie_minutes`
223
+ `fluent_cart/cart_cookie_minutes` — Control cart cookie expiration time
224
+
225
+ * **When it runs:** Fires when setting the cart hash cookie. The default value is a Unix timestamp (time() + 30 days).
226
+ * **Source:** `api/Cookie/Cookie.php` (line 22)
227
+
228
+ #### Parameters:
229
+ * `$expireTime` *(int)* — Unix timestamp for cookie expiration
230
+ * **Returns:** *(int)* — The Unix timestamp when cookie expires
231
+
232
+ #### Usage Example:
233
+ ```php
234
+ // Filter cart cookie expiration Unix timestamp
235
+ add_filter('fluent_cart/cart_cookie_minutes', function ($expireTime) {
236
+ // Set cart cookie expiration to 7 days from now
237
+ return time() + (7 * DAY_IN_SECONDS);
238
+ });
239
+ ```
240
+
241
+ ---
242
+
243
+ ### `variation/can_purchase_bundle`
244
+ `fluent_cart/variation/can_purchase_bundle` — Validate whether a bundle product can be purchased
245
+
246
+ * **When it runs:** Fires during `canPurchase()` on a `ProductVariation` when product is a bundle.
247
+ * **Source:** `app/Models/ProductVariation.php` (line 265)
248
+
249
+ #### Parameters:
250
+ * `$result` *(null)* — Always `null` initially
251
+ * `$data` *(array)* — Context data (`['variation' => ProductVariation, 'quantity' => int]`)
252
+ * **Returns:** *(null|true|false|\WP_Error)* — `null`/`true` to allow, `false` for generic error, `WP_Error` to block with custom message
253
+
254
+ #### Usage Example:
255
+ ```php
256
+ // Validate stock for bundled child items during bundle purchase
257
+ add_filter('fluent_cart/variation/can_purchase_bundle', function ($result, $data) {
258
+ $variation = $data['variation'];
259
+ $quantity = (int) $data['quantity'];
260
+
261
+ // Iterate through bundle children to verify sufficient stock
262
+ $children = $variation->bundleChildren()->get();
263
+ foreach ($children as $child) {
264
+ if ($child->available < ($child->pivot->quantity * $quantity)) {
265
+ return new \WP_Error(
266
+ 'bundle_stock',
267
+ sprintf(__('%s does not have enough stock.', 'fluent-cart'), $child->title)
268
+ );
269
+ }
270
+ }
271
+
272
+ return $result;
273
+ }, 10, 2);
274
+ ```
275
+
276
+ ---
277
+
278
+ ## Checkout Validation
279
+
280
+ ### `checkout/validate_before_process`
281
+ `fluent_cart/checkout/validate_before_process` — Pre-validate the checkout before processing
282
+
283
+ * **When it runs:** Fires early in `placeOrder()` flow before field or product validation. First chance to reject checkout attempt.
284
+ * **Source:** `api/Checkout/CheckoutApi.php` (line 83)
285
+
286
+ #### Parameters:
287
+ * `$validation` *(true)* — Always `true` initially
288
+ * `$data` *(array)* — Full checkout submission data (billing address, payment method, form fields, etc.)
289
+ * **Returns:** *(true|\WP_Error)* — `true` to continue, `WP_Error` to abort checkout
290
+
291
+ #### Usage Example:
292
+ ```php
293
+ // Pre-validate checkout submission before processing order
294
+ add_filter('fluent_cart/checkout/validate_before_process', function ($validation, $data) {
295
+ // Query cart model instance using submitted cart hash
296
+ $cart = \FluentCart\App\Models\Cart::query()
297
+ ->where('cart_hash', $data['cart_hash'])
298
+ ->first();
299
+
300
+ // Enforce minimum order total requirement of $5.00
301
+ if ($cart && $cart->getEstimatedTotal() < 500) {
302
+ return new \WP_Error(
303
+ 'min_order',
304
+ __('Minimum order amount is $5.00.', 'fluent-cart')
305
+ );
306
+ }
307
+
308
+ return $validation;
309
+ }, 10, 2);
310
+ ```
311
+
312
+ ---
313
+
314
+ ### `cart/tax_behavior`
315
+ `fluent_cart/cart/tax_behavior` — Filter tax behavior amount for the cart
316
+
317
+ * **When it runs:** Fires during order creation in `CheckoutApi::placeOrder()`. Determines tax behavior value for order total.
318
+ * **Source:** `api/Checkout/CheckoutApi.php` (line 171)
319
+
320
+ #### Parameters:
321
+ * `$behavior` *(int)* — Default tax behavior value (`0`)
322
+ * `$data` *(array)* — Context data (`['cart' => Cart]`)
323
+ * **Returns:** *(int)* — Tax behavior value (`0` for exclusive, `1` for inclusive)
324
+
325
+ #### Usage Example:
326
+ ```php
327
+ // Filter tax behavior value for cart order total calculation
328
+ add_filter('fluent_cart/cart/tax_behavior', function ($behavior, $data) {
329
+ $cart = $data['cart'];
330
+
331
+ // Force tax-inclusive behavior for specific European countries
332
+ $country = $cart->checkout_data['billing_address']['country'] ?? '';
333
+ if (in_array($country, ['DE', 'FR', 'GB'])) {
334
+ return 1; // Tax-inclusive
335
+ }
336
+
337
+ return $behavior;
338
+ }, 10, 2);
339
+ ```
340
+
341
+ ---
342
+
343
+ ### `checkout/validate_data`
344
+ `fluent_cart/checkout/validate_data` — Add or modify checkout validation errors
345
+
346
+ * **When it runs:** Fires after core field, shipping, and terms validation has run, before order creation.
347
+ * **Source:** `api/Checkout/CheckoutApi.php` (line 890)
348
+
349
+ #### Parameters:
350
+ * `$errors` *(array)* — Associative array of validation errors keyed by field name
351
+ * `$data` *(array)* — Context data (`['data' => submittedData, 'cart' => Cart]`)
352
+ * **Returns:** *(array)* — Modified errors array (empty array means validation passes)
353
+
354
+ #### Usage Example:
355
+ ```php
356
+ // Append custom field validation errors to checkout submission
357
+ add_filter('fluent_cart/checkout/validate_data', function ($errors, $data) {
358
+ $formData = $data['data'];
359
+
360
+ // Require billing phone number for physical products requiring shipping
361
+ $cart = $data['cart'];
362
+ if ($cart->requireShipping() && empty($formData['billing_address']['phone'])) {
363
+ $errors['billing_phone'] = [
364
+ 'required' => __('Phone number is required for physical products.', 'fluent-cart'),
365
+ ];
366
+ }
367
+
368
+ return $errors;
369
+ }, 10, 2);
370
+ ```
371
+
372
+ ---
373
+
374
+ ## Checkout Page Rendering
375
+
376
+ ### `checkout_page_css_classes`
377
+ `fluent_cart/checkout_page_css_classes` — Modify checkout page CSS classes
378
+
379
+ * **When it runs:** Fires when rendering the checkout page container wrapper element.
380
+ * **Source:** `app/Services/Renderer/CheckoutRenderer.php` (line 144)
381
+
382
+ #### Parameters:
383
+ * `$classNames` *(array)* — Array of CSS class strings
384
+ * `$data` *(array)* — Context data (`['cart' => Cart]`)
385
+ * **Returns:** *(array)* — Modified array of CSS class strings
386
+
387
+ #### Usage Example:
388
+ ```php
389
+ // Filter checkout page wrapper container CSS classes
390
+ add_filter('fluent_cart/checkout_page_css_classes', function ($classes, $data) {
391
+ $cart = $data['cart'];
392
+
393
+ // Add custom class when cart contains subscription items
394
+ if ($cart->hasSubscription()) {
395
+ $classes[] = 'has-subscription-items';
396
+ }
397
+
398
+ return $classes;
399
+ }, 10, 2);
400
+ ```
401
+
402
+ ---
403
+
404
+ ### `checkout_page_notices`
405
+ `fluent_cart/checkout_page_notices` — Add custom notices to checkout page
406
+
407
+ * **When it runs:** Fires during checkout page rendering to inject notices displayed at the top of checkout form.
408
+ * **Source:** `app/Services/Renderer/CheckoutRenderer.php` (line 170)
409
+
410
+ #### Parameters:
411
+ * `$notices` *(array)* — Array of notice items (empty by default)
412
+ * `$data` *(array)* — Context data (`['cart' => Cart]`)
413
+ * **Returns:** *(array)* — Array of notice items to display
414
+
415
+ #### Usage Example:
416
+ ```php
417
+ // Inject custom notice messages onto top of checkout page
418
+ add_filter('fluent_cart/checkout_page_notices', function ($notices, $data) {
419
+ $cart = $data['cart'];
420
+
421
+ // Display free shipping qualification threshold notice
422
+ $total = $cart->getEstimatedTotal();
423
+ if ($total < 5000 && $cart->requireShipping()) {
424
+ $notices[] = [
425
+ 'type' => 'info',
426
+ 'message' => sprintf(
427
+ __('Add %s more to qualify for free shipping!', 'fluent-cart'),
428
+ '$' . number_format((5000 - $total) / 100, 2)
429
+ ),
430
+ ];
431
+ }
432
+
433
+ return $notices;
434
+ }, 10, 2);
435
+ ```
436
+
437
+ ---
438
+
439
+ ### `checkout_renderer/billing_fields`
440
+ `fluent_cart/checkout_renderer/billing_fields` — Modify rendered billing fields on checkout page
441
+
442
+ * **When it runs:** Fires after billing address fields have been assembled and rearranged in checkout renderer.
443
+ * **Source:** `app/Services/Renderer/CheckoutRenderer.php` (line 448)
444
+
445
+ #### Parameters:
446
+ * `$billingFields` *(array)* — Array of billing field definitions with rendered state
447
+ * `$data` *(array)* — Context data (`['checkout_renderer' => renderer, 'cart' => Cart]`)
448
+ * **Returns:** *(array)* — Modified billing fields array
449
+
450
+ #### Usage Example:
451
+ ```php
452
+ // Filter rendered billing field schema definitions on checkout page
453
+ add_filter('fluent_cart/checkout_renderer/billing_fields', function ($fields, $data) {
454
+ // Remove company field from rendered billing fields schema
455
+ foreach ($fields as $sectionKey => &$section) {
456
+ if (isset($section['schema']) && is_array($section['schema'])) {
457
+ unset($section['schema']['billing_company']);
458
+ }
459
+ }
460
+
461
+ return $fields;
462
+ }, 10, 2);
463
+ ```
464
+
465
+ ---
466
+
467
+ ### `checkout_renderer/shipping_fields`
468
+ `fluent_cart/checkout_renderer/shipping_fields` — Modify rendered shipping fields on checkout page
469
+
470
+ * **When it runs:** Fires after shipping address fields have been assembled and validated in checkout renderer.
471
+ * **Source:** `app/Services/Renderer/CheckoutRenderer.php` (line 521)
472
+
473
+ #### Parameters:
474
+ * `$shippingFields` *(array)* — Array of shipping field definitions
475
+ * `$data` *(array)* — Context data (`['checkout_renderer' => renderer, 'cart' => Cart]`)
476
+ * **Returns:** *(array)* — Modified shipping fields array
477
+
478
+ #### Usage Example:
479
+ ```php
480
+ // Filter rendered shipping field schema definitions on checkout page
481
+ add_filter('fluent_cart/checkout_renderer/shipping_fields', function ($fields, $data) {
482
+ // Mark shipping address line 2 as a required field
483
+ foreach ($fields as &$field) {
484
+ if (isset($field['name']) && $field['name'] === 'shipping_address_2') {
485
+ $field['required'] = 'yes';
486
+ }
487
+ }
488
+
489
+ return $fields;
490
+ }, 10, 2);
491
+ ```
492
+
493
+ ---
494
+
495
+ ### `disable_order_notes_for_digital_products`
496
+ `fluent_cart/disable_order_notes_for_digital_products` — Control order notes visibility for digital products
497
+
498
+ * **When it runs:** Fires when checkout renderer decides whether to show order notes textarea.
499
+ * **Source:** `app/Services/Renderer/CheckoutRenderer.php` (line 560)
500
+
501
+ #### Parameters:
502
+ * `$disable` *(bool)* — Whether to hide order notes for digital-only carts (default: `true`)
503
+ * `$data` *(array)* — Context data (`['cart' => Cart]`)
504
+ * **Returns:** *(bool)* — `true` to hide order notes for digital products, `false` to show
505
+
506
+ #### Usage Example:
507
+ ```php
508
+ // Filter order notes textarea visibility for digital-only carts
509
+ add_filter('fluent_cart/disable_order_notes_for_digital_products', function ($disable, $data) {
510
+ // Always render order notes field even for digital products
511
+ return false;
512
+ }, 10, 2);
513
+ ```
514
+
515
+ ---
516
+
517
+ ### `checkout_active_payment_methods`
518
+ `fluent_cart/checkout_active_payment_methods` — Filter active payment methods on checkout page
519
+
520
+ * **When it runs:** Fires when listing available payment methods on standard and modal checkout renderers.
521
+ * **Source:** `app/Services/Renderer/CheckoutRenderer.php` (line 652), `app/Services/Renderer/ModalCheckoutRenderer.php` (line 450)
522
+
523
+ #### Parameters:
524
+ * `$activePaymentMethods` *(array)* — Array of payment method instances
525
+ * `$data` *(array)* — Context data (`['cart' => Cart]`)
526
+ * **Returns:** *(array)* — Modified array of payment method instances
527
+
528
+ #### Usage Example:
529
+ ```php
530
+ // Filter active payment method gateway instances on checkout page
531
+ add_filter('fluent_cart/checkout_active_payment_methods', function ($methods, $data) {
532
+ $cart = $data['cart'];
533
+
534
+ // Exclude Cash on Delivery payment option for orders over $500
535
+ if ($cart->getEstimatedTotal() > 50000) {
536
+ $methods = array_filter($methods, function ($method) {
537
+ return $method->getMeta('route') !== 'cod';
538
+ });
539
+ }
540
+
541
+ return array_values($methods);
542
+ }, 10, 2);
543
+ ```
544
+
545
+ ---
546
+
547
+ ### `checkout_page_order_button_text`
548
+ `fluent_cart/checkout_page_order_button_text` — Customize place order button text
549
+
550
+ * **When it runs:** Fires when checkout submit button is being rendered to change its label.
551
+ * **Source:** `app/Services/Renderer/CheckoutRenderer.php` (line 705)
552
+
553
+ #### Parameters:
554
+ * `$text` *(string)* — Button text (default: `'Place order'`)
555
+ * **Returns:** *(string)* — Modified button text
556
+
557
+ #### Usage Example:
558
+ ```php
559
+ // Customize place order submit button text on checkout page
560
+ add_filter('fluent_cart/checkout_page_order_button_text', function ($text) {
561
+ // Change Place Order button label to Complete Purchase
562
+ return __('Complete Purchase', 'fluent-cart');
563
+ });
564
+ ```
565
+
566
+ ---
567
+
568
+ ### `payment_method_list_class`
569
+ `fluent_cart_payment_method_list_class` — Add CSS classes to a payment method wrapper
570
+
571
+ * **When it runs:** Fires when rendering each payment method option in standard and modal checkout. Note legacy prefix (`fluent_cart_`).
572
+ * **Source:** `app/Services/Renderer/CheckoutRenderer.php` (line 797), `app/Services/Renderer/ModalCheckoutRenderer.php` (line 569)
573
+
574
+ #### Parameters:
575
+ * `$class` *(string)* — CSS class string (default: `''`)
576
+ * `$data` *(array)* — Context data (`['route' => string, 'method_title' => string, 'method_style' => string]`)
577
+ * **Returns:** *(string)* — Modified CSS class string
578
+
579
+ #### Usage Example:
580
+ ```php
581
+ // Filter CSS class string for payment method container wrapper (legacy prefix)
582
+ add_filter('fluent_cart_payment_method_list_class', function ($class, $data) {
583
+ // Add highlight class for Cash on Delivery payment option
584
+ if ($data['route'] === 'cod') {
585
+ return $class . ' payment-method-highlighted';
586
+ }
587
+ return $class;
588
+ }, 10, 2);
589
+ ```
590
+
591
+ ---
592
+
593
+ ### `modal_checkout/filter_active_payment_methods`
594
+ `fluent_cart/modal_checkout/filter_active_payment_methods` — Restrict payment methods in modal checkout
595
+
596
+ * **When it runs:** Fires during modal checkout rendering after active payment methods are resolved.
597
+ * **Source:** `app/Services/Renderer/ModalCheckoutRenderer.php` (line 455)
598
+
599
+ #### Parameters:
600
+ * `$selectedMethods` *(array)* — Empty array by default
601
+ * **Returns:** *(array)* — Array of payment method route slugs to show (`['stripe', 'paypal']`)
602
+
603
+ #### Usage Example:
604
+ ```php
605
+ // Filter active payment method route slugs shown in modal checkout
606
+ add_filter('fluent_cart/modal_checkout/filter_active_payment_methods', function ($methods) {
607
+ // Restrict modal checkout to show only Stripe payment method
608
+ return ['stripe'];
609
+ });
610
+ ```
611
+
612
+ ---
613
+
614
+ ### `enable_modal_checkout`
615
+ `fluent_cart/enable_modal_checkout` — Enable or disable modal checkout
616
+
617
+ * **When it runs:** Fires when checking whether modal popup checkout is enabled (default: `false`).
618
+ * **Source:** `app/Helpers/Helper.php` (line 1710)
619
+
620
+ #### Parameters:
621
+ * `$enabled` *(bool)* — Whether modal checkout is enabled (default: `false`)
622
+ * **Returns:** *(bool)* — `true` to enable modal checkout, `false` for standard page
623
+
624
+ #### Usage Example:
625
+ ```php
626
+ // Filter whether modal popup checkout mode is enabled
627
+ add_filter('fluent_cart/enable_modal_checkout', function ($enabled) {
628
+ // Enable modal checkout feature
629
+ return true;
630
+ });
631
+ ```
632
+
633
+ ---
634
+
635
+ ## Checkout Data & Session
636
+
637
+ ### `checkout/checkout_data_changed`
638
+ `fluent_cart/checkout/checkout_data_changed` — Modify checkout data after a change is detected
639
+
640
+ * **When it runs:** Fires after checkout session data is saved to modify response data returned to browser.
641
+ * **Source:** `app/Hooks/Cart/WebCheckoutHandler.php` (lines 495, 1115)
642
+
643
+ #### Parameters:
644
+ * `$checkoutData` *(array)* — Checkout change response data (`message`, `fragments`, `estimated_total`, etc.)
645
+ * `$data` *(array)* — Context data (`['cart' => Cart]`)
646
+ * **Returns:** *(array)* — Modified checkout response data
647
+
648
+ #### Usage Example:
649
+ ```php
650
+ // Filter response data payload returned after checkout session data change
651
+ add_filter('fluent_cart/checkout/checkout_data_changed', function ($checkoutData, $data) {
652
+ // Append custom notice string to checkout change response payload
653
+ $checkoutData['custom_notice'] = __('Your order qualifies for a bonus!', 'fluent-cart');
654
+ return $checkoutData;
655
+ }, 10, 2);
656
+ ```
657
+
658
+ ---
659
+
660
+ ### `checkout/cart_updated`
661
+ `fluent_cart/checkout/cart_updated` — Filter the cart update response data
662
+
663
+ * **When it runs:** Fires when cart is updated during checkout session (e.g. items added or removed).
664
+ * **Source:** `app/Hooks/Cart/WebCheckoutHandler.php` (line 683)
665
+
666
+ #### Parameters:
667
+ * `$data` *(array)* — Response data (`['cart' => Cart]`)
668
+ * **Returns:** *(array)* — Modified response data array
669
+
670
+ #### Usage Example:
671
+ ```php
672
+ // Filter cart update response payload during checkout session
673
+ add_filter('fluent_cart/checkout/cart_updated', function ($data) {
674
+ // Append item count and free shipping eligibility flags
675
+ $cart = $data['cart'];
676
+ $data['item_count'] = count($cart->getItems());
677
+ $data['free_shipping_eligible'] = $cart->getEstimatedTotal() >= 5000;
678
+ return $data;
679
+ });
680
+ ```
681
+
682
+ ---
683
+
684
+ ### `checkout/before_patch_checkout_data`
685
+ `fluent_cart/checkout/before_patch_checkout_data` — Modify fill data before patching checkout session
686
+
687
+ * **When it runs:** Fires before checkout session data is persisted to database.
688
+ * **Source:** `app/Hooks/Cart/WebCheckoutHandler.php` (lines 791, 967)
689
+
690
+ #### Parameters:
691
+ * `$fillData` *(array)* — Data to merge into cart checkout session (`checkout_data`, `cart_data`, `hook_changes`)
692
+ * `$data` *(array)* — Context data (`['cart' => Cart, 'prev_data' => array, 'changes' => array, 'all_data' => array]`)
693
+ * **Returns:** *(array)* — Modified fill data
694
+
695
+ #### Usage Example:
696
+ ```php
697
+ // Filter fill data merged into checkout session before persisting to DB
698
+ add_filter('fluent_cart/checkout/before_patch_checkout_data', function ($fillData, $data) {
699
+ $cart = $data['cart'];
700
+ $changes = $data['changes'];
701
+
702
+ // Recalculate custom surcharge when billing country changes
703
+ if (isset($changes['billing_country'])) {
704
+ $surcharge = MyModule::calculateSurcharge($changes['billing_country']);
705
+ $fillData['checkout_data']['custom_surcharge'] = $surcharge;
706
+ $fillData['hook_changes']['custom'] = true;
707
+ }
708
+
709
+ return $fillData;
710
+ }, 10, 2);
711
+ ```
712
+
713
+ ---
714
+
715
+ ### `checkout/after_patch_checkout_data_fragments`
716
+ `fluent_cart/checkout/after_patch_checkout_data_fragments` — Modify HTML fragments returned after patching checkout data
717
+
718
+ * **When it runs:** Fires after checkout session is patched and HTML fragments for AJAX response are generated.
719
+ * **Source:** `app/Hooks/Cart/WebCheckoutHandler.php` (line 901)
720
+
721
+ #### Parameters:
722
+ * `$fragments` *(array)* — Associative array of HTML fragment selectors and content
723
+ * `$data` *(array)* — Context data (`['cart' => Cart, 'changes' => array]`)
724
+ * **Returns:** *(array)* — Modified fragments array
725
+
726
+ #### Usage Example:
727
+ ```php
728
+ // Filter HTML response fragments swapped into checkout page via AJAX
729
+ add_filter('fluent_cart/checkout/after_patch_checkout_data_fragments', function ($fragments, $data) {
730
+ // Extract cart model instance
731
+ $cart = $data['cart'];
732
+
733
+ // Inject custom surcharge display HTML fragment selector
734
+ $fragments['.custom-surcharge-display'] = [
735
+ 'content' => '<span class="custom-surcharge">' . esc_html('$5.00') . '</span>',
736
+ 'type' => 'replace',
737
+ ];
738
+
739
+ return $fragments;
740
+ }, 10, 2);
741
+ ```
742
+
743
+ ---
744
+
745
+ ### `apply_order_bump`
746
+ `fluent_cart/apply_order_bump` — Handle order bump application on checkout page
747
+
748
+ * **When it runs:** Fires when customer toggles order bump on checkout page.
749
+ * **Source:** `app/Hooks/Cart/WebCheckoutHandler.php` (line 1144)
750
+
751
+ #### Parameters:
752
+ * `$response` *(\WP_Error)* — Default error response
753
+ * `$data` *(array)* — Context data (`['bump_id' => int, 'cart' => Cart, 'request_data' => array]`)
754
+ * **Returns:** *(array|\WP_Error)* — Return array with success data to apply bump, or `WP_Error` to reject
755
+
756
+ #### Usage Example:
757
+ ```php
758
+ // Handle order bump application request on checkout page
759
+ add_filter('fluent_cart/apply_order_bump', function ($response, $data) {
760
+ $bumpId = $data['bump_id'];
761
+ $cart = $data['cart'];
762
+
763
+ // Look up order bump definition model
764
+ $bump = MyOrderBumpModule::find($bumpId);
765
+ if (!$bump) {
766
+ return $response;
767
+ }
768
+
769
+ // Add bump variation item to cart
770
+ $cart->addItem($bump->variation_id, 1);
771
+
772
+ return [
773
+ 'message' => __('Order bump applied!', 'fluent-cart'),
774
+ 'cart' => $cart,
775
+ ];
776
+ }, 10, 2);
777
+ ```
778
+
779
+ ---
780
+
781
+ ## Checkout Field Schema
782
+
783
+ ### `checkout_address_fields`
784
+ `fluent_cart/checkout_address_fields` — Modify address field definitions
785
+
786
+ * **When it runs:** Fires when address field schema is built in `CartCheckoutHelper`. Controls fields in billing/shipping address sections.
787
+ * **Source:** `app/Helpers/CartCheckoutHelper.php` (line 692)
788
+
789
+ #### Parameters:
790
+ * `$fields` *(array)* — Associative array of address field definitions
791
+ * **Returns:** *(array)* — Modified fields array
792
+
793
+ #### Usage Example:
794
+ ```php
795
+ // Modify address field definitions for both billing and shipping
796
+ add_filter('fluent_cart/checkout_address_fields', function ($fields) {
797
+ // Add custom company name address field definition
798
+ $fields['company'] = [
799
+ 'label' => __('Company Name', 'fluent-cart'),
800
+ 'type' => 'text',
801
+ 'required' => false,
802
+ ];
803
+
804
+ return $fields;
805
+ });
806
+ ```
807
+
808
+ ---
809
+
810
+ ### `checkout_billing_fields`
811
+ `fluent_cart/checkout_billing_fields` — Modify billing address field schema
812
+
813
+ * **When it runs:** Fires when billing fields are being assembled in `CartCheckoutHelper`.
814
+ * **Source:** `app/Helpers/CartCheckoutHelper.php` (line 730)
815
+
816
+ #### Parameters:
817
+ * `$fields` *(array)* — Billing field definitions organized in sections
818
+ * `$data` *(array)* — Context data (`['viewData' => array, 'customer' => Customer, 'labels' => array, 'has_subscription' => bool]`)
819
+ * **Returns:** *(array)* — Modified billing fields array
820
+
821
+ #### Usage Example:
822
+ ```php
823
+ // Modify billing address section field schema definitions
824
+ add_filter('fluent_cart/checkout_billing_fields', function ($fields, $data) {
825
+ // Enforce required phone field for subscription carts
826
+ if ($data['has_subscription']) {
827
+ if (isset($fields['address_section']['schema']['billing_phone'])) {
828
+ $fields['address_section']['schema']['billing_phone']['required'] = 'yes';
829
+ }
830
+ }
831
+
832
+ return $fields;
833
+ }, 10, 2);
834
+ ```
835
+
836
+ ---
837
+
838
+ ### `checkout_shipping_fields`
839
+ `fluent_cart/checkout_shipping_fields` — Modify shipping address field schema
840
+
841
+ * **When it runs:** Fires when shipping address fields are assembled in `CartCheckoutHelper`.
842
+ * **Source:** `app/Helpers/CartCheckoutHelper.php` (line 771)
843
+
844
+ #### Parameters:
845
+ * `$fields` *(array)* — Shipping field definitions organized in sections
846
+ * `$data` *(array)* — Context data (`['viewData' => array, 'labels' => array]`)
847
+ * **Returns:** *(array)* — Modified shipping fields array
848
+
849
+ #### Usage Example:
850
+ ```php
851
+ // Modify shipping address section field schema definitions
852
+ add_filter('fluent_cart/checkout_shipping_fields', function ($fields, $data) {
853
+ // Remove shipping address line 2 field from schema
854
+ if (isset($fields['address_section']['schema']['shipping_address_2'])) {
855
+ unset($fields['address_section']['schema']['shipping_address_2']);
856
+ }
857
+
858
+ return $fields;
859
+ }, 10, 2);
860
+ ```
861
+
862
+ ---
863
+
864
+ ### `checkout_signup_fields`
865
+ `fluent_cart/checkout_signup_fields` — Modify account signup form fields
866
+
867
+ * **When it runs:** Fires when guest checkout signup form fields (username, email, password) are assembled.
868
+ * **Source:** `app/Helpers/CartCheckoutHelper.php` (line 846)
869
+
870
+ #### Parameters:
871
+ * `$fields` *(array)* — Associative array of signup field definitions (`user_login`, `user_pass`)
872
+ * **Returns:** *(array)* — Modified signup fields array
873
+
874
+ #### Usage Example:
875
+ ```php
876
+ // Modify guest checkout registration signup form field schema
877
+ add_filter('fluent_cart/checkout_signup_fields', function ($fields) {
878
+ // Enforce required password field during signup
879
+ if (isset($fields['user_pass'])) {
880
+ $fields['user_pass']['required'] = 'yes';
881
+ }
882
+
883
+ return $fields;
884
+ });
885
+ ```
886
+
887
+ ---
888
+
889
+ ### `checkout_login_fields`
890
+ `fluent_cart/checkout_login_fields` — Modify checkout login form fields
891
+
892
+ * **When it runs:** Fires when login form fields (username, password) are assembled for checkout page.
893
+ * **Source:** `app/Helpers/CartCheckoutHelper.php` (line 872)
894
+
895
+ #### Parameters:
896
+ * `$fields` *(array)* — Associative array of login field definitions (`user_login`, `user_pass`)
897
+ * **Returns:** *(array)* — Modified login fields array
898
+
899
+ #### Usage Example:
900
+ ```php
901
+ // Modify returning customer login form field schema on checkout
902
+ add_filter('fluent_cart/checkout_login_fields', function ($fields) {
903
+ // Update username field label and placeholder text
904
+ if (isset($fields['user_login'])) {
905
+ $fields['user_login']['label'] = __('Email Address', 'fluent-cart');
906
+ $fields['user_login']['placeholder'] = __('Enter your email', 'fluent-cart');
907
+ }
908
+
909
+ return $fields;
910
+ });
911
+ ```
912
+
913
+ ---
914
+
915
+ ### `checkout_coupon_fields`
916
+ `fluent_cart/checkout_coupon_fields` — Modify coupon input fields
917
+
918
+ * **When it runs:** Fires when coupon code input fields are assembled for checkout page.
919
+ * **Source:** `app/Helpers/CartCheckoutHelper.php` (line 925)
920
+
921
+ #### Parameters:
922
+ * `$fields` *(array)* — Associative array of coupon field definitions
923
+ * **Returns:** *(array)* — Modified coupon fields array
924
+
925
+ #### Usage Example:
926
+ ```php
927
+ // Modify coupon input form fields schema on checkout page
928
+ add_filter('fluent_cart/checkout_coupon_fields', function ($fields) {
929
+ // Customize coupon code input field placeholder string
930
+ if (isset($fields['coupon_code'])) {
931
+ $fields['coupon_code']['placeholder'] = __('Got a discount code?', 'fluent-cart');
932
+ }
933
+
934
+ return $fields;
935
+ });
936
+ ```
937
+
938
+ ---
939
+
940
+ ### `checkout_page_name_fields_schema`
941
+ `fluent_cart/checkout_page_name_fields_schema` — Modify name fields on checkout page
942
+
943
+ * **When it runs:** Fires when checkout name fields schema (first name, last name, email, company) is being built.
944
+ * **Source:** `app/Services/Renderer/CheckoutFieldsSchema.php` (line 86)
945
+
946
+ #### Parameters:
947
+ * `$nameFields` *(array)* — Associative array of name/email field definitions
948
+ * `$data` *(array)* — Context data (`['cart' => Cart, 'scope' => 'billing'|'shipping']`)
949
+ * **Returns:** *(array)* — Modified name fields array
950
+
951
+ #### Usage Example:
952
+ ```php
953
+ // Modify checkout page name and email fields schema
954
+ add_filter('fluent_cart/checkout_page_name_fields_schema', function ($fields, $data) {
955
+ // Pre-fill email field for logged-in user
956
+ if ($userId = get_current_user_id()) {
957
+ $user = get_userdata($userId);
958
+ if (!empty($fields['billing_email']) && empty($fields['billing_email']['value'])) {
959
+ $fields['billing_email']['value'] = $user->user_email;
960
+ }
961
+ }
962
+
963
+ return $fields;
964
+ }, 10, 2);
965
+ ```
966
+
967
+ ---
968
+
969
+ ### `fields/address_base_fields`
970
+ `fluent_cart/fields/address_base_fields` — Modify base address field definitions
971
+
972
+ * **When it runs:** Fires when low-level address field definitions are assembled in `CheckoutFieldsSchema`.
973
+ * **Source:** `app/Services/Renderer/CheckoutFieldsSchema.php` (line 320)
974
+
975
+ #### Parameters:
976
+ * `$fields` *(array)* — Array of base address field definitions
977
+ * `$data` *(array)* — Context data (`['config' => array, 'scope' => 'billing'|'shipping', 'requirements' => array]`)
978
+ * **Returns:** *(array)* — Modified base address fields array
979
+
980
+ #### Usage Example:
981
+ ```php
982
+ // Modify low-level base address field definitions
983
+ add_filter('fluent_cart/fields/address_base_fields', function ($fields, $data) {
984
+ // Make billing city field optional
985
+ if ($data['scope'] === 'billing') {
986
+ foreach ($fields as &$field) {
987
+ if (isset($field['name']) && $field['name'] === 'billing_city') {
988
+ unset($field['required']);
989
+ }
990
+ }
991
+ }
992
+
993
+ return $fields;
994
+ }, 10, 2);
995
+ ```
996
+
997
+ ---
998
+
999
+ ### `default_billing_country_for_checkout`
1000
+ `fluent_cart/default_billing_country_for_checkout` — Set default billing country
1001
+
1002
+ * **When it runs:** Fires when determining default billing country for checkout form. Default uses Cloudflare IP geo-detection.
1003
+ * **Source:** `app/Helpers/AddressHelper.php` (line 639)
1004
+
1005
+ #### Parameters:
1006
+ * `$countryCode` *(string)* — Detected country code (ISO 3166-1 alpha-2)
1007
+ * **Returns:** *(string)* — Valid ISO 3166-1 alpha-2 country code
1008
+
1009
+ #### Usage Example:
1010
+ ```php
1011
+ // Filter default billing country code for checkout form
1012
+ add_filter('fluent_cart/default_billing_country_for_checkout', function ($countryCode) {
1013
+ // Default to US if geo-detection yields empty country code
1014
+ if (empty($countryCode)) {
1015
+ return 'US';
1016
+ }
1017
+
1018
+ return $countryCode;
1019
+ });
1020
+ ```
1021
+
1022
+ ---
1023
+
1024
+ ## Checkout Localization
1025
+
1026
+ ### `checkout/localize_data`
1027
+ `fluent_cart/checkout/localize_data` — Modify checkout JavaScript localized data
1028
+
1029
+ * **When it runs:** Fires when checkout page assets are enqueued to pass data to JS via `wp_localize_script()`.
1030
+ * **Source:** `app/Modules/Templating/AssetLoader.php` (line 497)
1031
+
1032
+ #### Parameters:
1033
+ * `$data` *(array)* — Localized data array (`fluentcart_checkout_vars`)
1034
+ * `$cart` *(\FluentCart\App\Models\Cart)* — Cart model instance
1035
+ * **Returns:** *(array)* — Modified localized data array
1036
+
1037
+ #### Usage Example:
1038
+ ```php
1039
+ // Modify localized data passed to checkout JavaScript frontend
1040
+ add_filter('fluent_cart/checkout/localize_data', function ($data, $cart) {
1041
+ // Add custom module config payload to checkout JS variables
1042
+ $data['fluentcart_checkout_vars']['my_module'] = [
1043
+ 'enabled' => true,
1044
+ 'endpoint' => rest_url('my-module/v1/validate'),
1045
+ ];
1046
+
1047
+ return $data;
1048
+ }, 10, 2);
1049
+ ```
1050
+
1051
+ ---
1052
+
1053
+ ### `payment_methods_with_custom_checkout_buttons`
1054
+ `fluent_cart/payment_methods_with_custom_checkout_buttons` — Register payment methods with custom buttons
1055
+
1056
+ * **When it runs:** Fires when building checkout localized data to identify gateways rendering custom submit buttons (e.g. PayPal smart buttons).
1057
+ * **Source:** `app/Modules/Templating/AssetLoader.php` (line 465)
1058
+
1059
+ #### Parameters:
1060
+ * `$methods` *(array)* — Array of payment method route slugs with custom buttons (default: `[]`)
1061
+ * **Returns:** *(array)* — Modified array of payment method route slugs
1062
+
1063
+ #### Usage Example:
1064
+ ```php
1065
+ // Register payment gateway route slugs that render custom buttons
1066
+ add_filter('fluent_cart/payment_methods_with_custom_checkout_buttons', function ($methods) {
1067
+ // Append custom payment gateway route slug to list
1068
+ $methods[] = 'my_custom_gateway';
1069
+ return $methods;
1070
+ });
1071
+ ```
1072
+
1073
+ ---
1074
+
1075
+ ### `instant_checkout/allowed_redirect_hosts`
1076
+ `fluent_cart/instant_checkout/allowed_redirect_hosts` — Control allowed redirect hosts for instant checkout
1077
+
1078
+ * **When it runs:** Fires during instant URL checkout when `redirect_to` parameter is provided.
1079
+ * **Source:** `app/Http/Routes/WebRoutes.php` (line 155)
1080
+
1081
+ #### Parameters:
1082
+ * `$allowedHosts` *(array)* — Array of allowed hostnames (default: current site host)
1083
+ * `$data` *(array)* — Context data (`['allowed_hosts' => array]`)
1084
+ * **Returns:** *(array)* — Array of allowed redirect hostnames
1085
+
1086
+ #### Usage Example:
1087
+ ```php
1088
+ // Filter allowed redirect hostnames for instant URL checkout
1089
+ add_filter('fluent_cart/instant_checkout/allowed_redirect_hosts', function ($hosts) {
1090
+ // Allow instant checkout redirects to subdomains
1091
+ $hosts[] = 'shop.example.com';
1092
+ $hosts[] = 'members.example.com';
1093
+ return $hosts;
1094
+ });
1095
+ ```
1096
+
1097
+ ---
1098
+
1099
+ ## Tax & VAT
1100
+
1101
+ ### `checkout/is_business`
1102
+ `fluent_cart/checkout/is_business` — Filter whether checkout is a business (B2B) purchase
1103
+
1104
+ * **When it runs:** Applied in `TaxModule::storeBusinessInfoOnOrder()` right after order is placed to decide whether to persist business info.
1105
+ * **Source:** `app/Modules/Tax/TaxModule.php` (line 1047)
1106
+
1107
+ #### Parameters:
1108
+ * `$isBusinessCheckout` *(bool)* — Whether checkout is treated as business purchase
1109
+ * `$data` *(array)* — Context data (`['checkout_data' => array, 'order' => Order]`)
1110
+ * **Returns:** *(bool)* — `true` to treat as business purchase
1111
+
1112
+ #### Usage Example:
1113
+ ```php
1114
+ // Filter whether checkout is treated as a business (B2B) purchase
1115
+ add_filter('fluent_cart/checkout/is_business', function ($isBusiness, $data) {
1116
+ // Treat checkout as B2B if company name is provided
1117
+ $company = $data['checkout_data']['form_data']['company_name'] ?? '';
1118
+
1119
+ return $isBusiness || $company !== '';
1120
+ }, 10, 2);
1121
+ ```
1122
+
1123
+ ---
1124
+
1125
+ ### `tax/reverse_charge_line_adjustment`
1126
+ `fluent_cart/tax/reverse_charge_line_adjustment` — Filter per-line price adjustment when reverse charge is applied
1127
+
1128
+ * **When it runs:** Applied in `TaxModule::calculateCartTax()` while applying EU VAT reverse charge to tax-inclusive product lines.
1129
+ * **Source:** `app/Modules/Tax/TaxModule.php` (line 689)
1130
+
1131
+ #### Parameters:
1132
+ * `$adjustment` *(int)* — Amount in cents to deduct from line unit price
1133
+ * `$data` *(array)* — Context data (`['line' => array, 'rc_mode' => string]`)
1134
+ * **Returns:** *(int)* — Adjustment amount in cents
1135
+
1136
+ #### Usage Example:
1137
+ ```php
1138
+ // Filter price deduction amount when EU VAT reverse charge is applied
1139
+ add_filter('fluent_cart/tax/reverse_charge_line_adjustment', function ($adjustment, $data) {
1140
+ // Keep gross price without deduction for target product post ID 123
1141
+ if (($data['line']['post_id'] ?? 0) === 123) {
1142
+ return 0;
1143
+ }
1144
+
1145
+ return $adjustment;
1146
+ }, 10, 2);
1147
+ ```
1148
+
1149
+ ---
1150
+
1151
+ ### `tax/reverse_charge_notice_text`
1152
+ `fluent_cart/tax/reverse_charge_notice_text` — Filter reverse charge notice on receipts and invoices
1153
+
1154
+ * **When it runs:** Applied in `TaxModule::getReverseChargeNoticeText()` whenever reverse charge notice is rendered on receipts, emails, or PDFs.
1155
+ * **Source:** `app/Modules/Tax/TaxModule.php` (line 1688)
1156
+
1157
+ #### Parameters:
1158
+ * `$text` *(string)* — Notice text (default: `'Reverse charge — Article 196, Council Directive 2006/112/EC. Customer is liable for VAT.'`)
1159
+ * **Returns:** *(string)* — Notice text to display
1160
+
1161
+ #### Usage Example:
1162
+ ```php
1163
+ // Filter reverse charge notice text shown on receipts and invoices
1164
+ add_filter('fluent_cart/tax/reverse_charge_notice_text', function ($text) {
1165
+ // Apply intra-EU supply of goods reverse charge notice wording
1166
+ return __('Reverse charge — Article 138, Council Directive 2006/112/EC. Customer is liable for VAT.', 'my-plugin');
1167
+ }, 10, 1);
1168
+ ```
1169
+
1170
+ ---
1171
+
1172
+ ### `tax/validate_eu_vat_number`
1173
+ `fluent_cart/tax/validate_eu_vat_number` — Short-circuit EU VAT number validation with custom validator
1174
+
1175
+ * **When it runs:** Applied in `TaxModule::validateEuVatNumber()` before contacting EU VIES SOAP service. Returning non-null short-circuits remote call.
1176
+ * **Source:** `app/Modules/Tax/TaxModule.php` (line 1430)
1177
+
1178
+ #### Parameters:
1179
+ * `$result` *(null)* — Always `null` by default
1180
+ * `$data` *(array)* — Context data (`['country_code' => string, 'vat_number' => string]`)
1181
+ * **Returns:** *(null|array|\WP_Error)* — `null` for default VIES call, `array` for successful result, `WP_Error` for error
1182
+
1183
+ #### Usage Example:
1184
+ ```php
1185
+ // Short-circuit EU VAT number validation with custom API validator
1186
+ add_filter('fluent_cart/tax/validate_eu_vat_number', function ($result, $data) {
1187
+ // Perform remote lookup via custom VAT API validator
1188
+ $response = my_vat_api_check($data['country_code'], $data['vat_number']);
1189
+
1190
+ if (!$response['ok']) {
1191
+ return new \WP_Error('invalid_vat', __('The VAT number could not be validated.', 'my-plugin'));
1192
+ }
1193
+
1194
+ return [
1195
+ 'country' => $data['country_code'],
1196
+ 'vat_number' => $data['vat_number'],
1197
+ 'valid' => true,
1198
+ 'name' => $response['company_name'],
1199
+ 'address' => $response['address'],
1200
+ ];
1201
+ }, 10, 2);
1202
+ ```