fluentcart-developer 1.1.0

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 (66) hide show
  1. package/.gitattributes +2 -0
  2. package/CLAUDE.md +22 -0
  3. package/CONTRIBUTING.md +73 -0
  4. package/LICENSE +21 -0
  5. package/README.md +127 -0
  6. package/SKILL.md +127 -0
  7. package/bin/index.js +281 -0
  8. package/copy-skills.js +43 -0
  9. package/package.json +38 -0
  10. package/skills/fluentcart-developer/SKILL.md +172 -0
  11. package/skills/fluentcart-developer/examples/README.md +25 -0
  12. package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/fluent-cart/checkout.php +32 -0
  13. package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/functions.php +40 -0
  14. package/skills/fluentcart-developer/examples/sample-custom-addon/fluentcart-custom-addon.php +114 -0
  15. package/skills/fluentcart-developer/examples/sample-custom-payment-gateway/fluentcart-custom-gateway-example.php +149 -0
  16. package/skills/fluentcart-developer/examples/sample-fee-surcharge-plugin/fluentcart-fee-surcharge.php +38 -0
  17. package/skills/fluentcart-developer/examples/sample-shipping-carrier/fluentcart-custom-shipping-carrier.php +62 -0
  18. package/skills/fluentcart-developer/references/action-hooks-admin-templates.md +787 -0
  19. package/skills/fluentcart-developer/references/action-hooks-cart-checkout.md +1355 -0
  20. package/skills/fluentcart-developer/references/action-hooks-customers-users.md +266 -0
  21. package/skills/fluentcart-developer/references/action-hooks-licenses.md +855 -0
  22. package/skills/fluentcart-developer/references/action-hooks-orders.md +631 -0
  23. package/skills/fluentcart-developer/references/action-hooks-payments-integrations.md +963 -0
  24. package/skills/fluentcart-developer/references/action-hooks-products-coupons.md +585 -0
  25. package/skills/fluentcart-developer/references/action-hooks-subscriptions.md +661 -0
  26. package/skills/fluentcart-developer/references/database-models-query-builder.md +194 -0
  27. package/skills/fluentcart-developer/references/database-models-reference.md +604 -0
  28. package/skills/fluentcart-developer/references/database-schema-reference.md +940 -0
  29. package/skills/fluentcart-developer/references/engineering-notes.md +154 -0
  30. package/skills/fluentcart-developer/references/fee-system-guide.md +449 -0
  31. package/skills/fluentcart-developer/references/filter-hooks-cart-checkout.md +1202 -0
  32. package/skills/fluentcart-developer/references/filter-hooks-customers-subscriptions.md +902 -0
  33. package/skills/fluentcart-developer/references/filter-hooks-integrations-advanced.md +1598 -0
  34. package/skills/fluentcart-developer/references/filter-hooks-orders-payments.md +1319 -0
  35. package/skills/fluentcart-developer/references/filter-hooks-products-pricing.md +628 -0
  36. package/skills/fluentcart-developer/references/filter-hooks-settings-configuration.md +1177 -0
  37. package/skills/fluentcart-developer/references/fluentcart-developer-guide.md +154 -0
  38. package/skills/fluentcart-developer/references/ghost-product-selling.md +458 -0
  39. package/skills/fluentcart-developer/references/modules-and-extensions-reference.md +224 -0
  40. package/skills/fluentcart-developer/references/paddle-gateway-case-study.md +1925 -0
  41. package/skills/fluentcart-developer/references/payment-gateway-integration.md +761 -0
  42. package/skills/fluentcart-developer/references/rest-api-checkout.md +286 -0
  43. package/skills/fluentcart-developer/references/rest-api-coupons.md +794 -0
  44. package/skills/fluentcart-developer/references/rest-api-customer-profile.md +190 -0
  45. package/skills/fluentcart-developer/references/rest-api-customers.md +1121 -0
  46. package/skills/fluentcart-developer/references/rest-api-dashboard-utilities.md +219 -0
  47. package/skills/fluentcart-developer/references/rest-api-email-notifications.md +619 -0
  48. package/skills/fluentcart-developer/references/rest-api-files.md +290 -0
  49. package/skills/fluentcart-developer/references/rest-api-integrations.md +324 -0
  50. package/skills/fluentcart-developer/references/rest-api-labels-attributes.md +321 -0
  51. package/skills/fluentcart-developer/references/rest-api-licensing.md +171 -0
  52. package/skills/fluentcart-developer/references/rest-api-order-bumps.md +200 -0
  53. package/skills/fluentcart-developer/references/rest-api-orders.md +1241 -0
  54. package/skills/fluentcart-developer/references/rest-api-overview.md +131 -0
  55. package/skills/fluentcart-developer/references/rest-api-products.md +2563 -0
  56. package/skills/fluentcart-developer/references/rest-api-public-shop.md +172 -0
  57. package/skills/fluentcart-developer/references/rest-api-reference.md +552 -0
  58. package/skills/fluentcart-developer/references/rest-api-reports.md +377 -0
  59. package/skills/fluentcart-developer/references/rest-api-roles-permissions.md +147 -0
  60. package/skills/fluentcart-developer/references/rest-api-settings.md +528 -0
  61. package/skills/fluentcart-developer/references/rest-api-shipping.md +800 -0
  62. package/skills/fluentcart-developer/references/rest-api-subscriptions.md +606 -0
  63. package/skills/fluentcart-developer/references/rest-api-tax.md +356 -0
  64. package/skills/fluentcart-developer/references/subscription-customization.md +197 -0
  65. package/skills/fluentcart-developer/scripts/cli.js +1 -0
  66. package/skills.sh.json +13 -0
@@ -0,0 +1,1319 @@
1
+ # Filter Hooks: Orders & Payments
2
+
3
+ All filters related to Order lifecycle, payment processing, gateway integrations, and taxes.
4
+
5
+ ---
6
+
7
+ ## Order Statuses
8
+
9
+ ### `order_statuses`
10
+ `fluent_cart/order_statuses` — Filter available order statuses
11
+
12
+ * **When it runs:** Applied when retrieving the list of available order statuses throughout the admin and storefront.
13
+ * **Source:** `app/Helpers/Status.php` (line 159)
14
+
15
+ #### Parameters:
16
+ * `$statuses` *(array)* — Associative array of order statuses (`'processing' => 'Processing'`, `'completed' => 'Completed'`, etc.)
17
+ * `$data` *(array)* — Additional context data (empty array)
18
+ * **Returns:** *(array)* — The modified order statuses array
19
+
20
+ #### Usage Example:
21
+ ```php
22
+ // Filter available order statuses array in FluentCart
23
+ add_filter('fluent_cart/order_statuses', function ($statuses, $data) {
24
+ // Add custom "Awaiting Pickup" order status
25
+ $statuses['awaiting_pickup'] = __('Awaiting Pickup', 'my-plugin');
26
+ return $statuses;
27
+ }, 10, 2);
28
+ ```
29
+
30
+ ---
31
+
32
+ ### `order_statuses` (legacy)
33
+ `fluent-cart/order_statuses` — Filter order statuses (legacy hook name)
34
+
35
+ * **When it runs:** Legacy location of the order statuses filter. Applied in the older Helper class. Prefer `fluent_cart/order_statuses` for new code.
36
+ * **Source:** `app/Helpers/Helper.php` (line 140)
37
+
38
+ #### Parameters:
39
+ * `$statuses` *(array)* — Associative array of order statuses
40
+ * `$data` *(array)* — Additional context data (empty array)
41
+ * **Returns:** *(array)* — The modified order statuses array
42
+
43
+ #### Usage Example:
44
+ ```php
45
+ // Filter order statuses using legacy hyphenated hook name
46
+ add_filter('fluent-cart/order_statuses', function ($statuses, $data) {
47
+ // Add custom status to legacy order statuses array
48
+ $statuses['custom'] = __('Custom Status', 'my-plugin');
49
+ return $statuses;
50
+ }, 10, 2);
51
+ ```
52
+
53
+ ---
54
+
55
+ ### `editable_order_statuses`
56
+ `fluent-cart/editable_order_statuses` — Filter manually settable order statuses
57
+
58
+ * **When it runs:** Applied when building the list of order statuses an admin can manually set on an order. This controls the dropdown options in the order edit screen. Note the hyphenated prefix (`fluent-cart/`).
59
+ * **Source:** `app/Helpers/Helper.php` (line 151), `app/Helpers/Status.php` (lines 170, 242)
60
+
61
+ #### Parameters:
62
+ * `$statuses` *(array)* — Associative array of editable statuses (`on-hold`, `processing`, `completed`, `canceled`)
63
+ * `$data` *(array)* — Additional context data (empty array)
64
+ * **Returns:** *(array)* — The modified editable order statuses array
65
+
66
+ #### Usage Example:
67
+ ```php
68
+ // Filter manually editable order statuses for admin dropdown
69
+ add_filter('fluent-cart/editable_order_statuses', function ($statuses, $data) {
70
+ // Remove "canceled" status from manually selectable options
71
+ unset($statuses['canceled']);
72
+ return $statuses;
73
+ }, 10, 2);
74
+ ```
75
+
76
+ ---
77
+
78
+ ### `payment_statuses`
79
+ `fluent_cart/payment_statuses` — Filter payment statuses
80
+
81
+ * **When it runs:** Applied when retrieving the list of available payment statuses used across the order and transaction system.
82
+ * **Source:** `app/Helpers/Status.php` (line 183)
83
+
84
+ #### Parameters:
85
+ * `$statuses` *(array)* — Associative array of payment statuses (`pending`, `paid`, `partially_paid`, `failed`, `refunded`, `partially_refunded`, `authorized`)
86
+ * `$data` *(array)* — Additional context data (empty array)
87
+ * **Returns:** *(array)* — The modified payment statuses array
88
+
89
+ #### Usage Example:
90
+ ```php
91
+ // Filter available payment statuses across order and transaction systems
92
+ add_filter('fluent_cart/payment_statuses', function ($statuses, $data) {
93
+ // Add custom "On Hold" payment status
94
+ $statuses['on_hold'] = __('On Hold', 'my-plugin');
95
+ return $statuses;
96
+ }, 10, 2);
97
+ ```
98
+
99
+ ---
100
+
101
+ ### `transaction_statuses`
102
+ `fluent_cart/transaction_statuses` — Filter transaction statuses
103
+
104
+ * **When it runs:** Applied when retrieving available transaction statuses for the primary transaction system.
105
+ * **Source:** `app/Helpers/Status.php` (line 197)
106
+
107
+ #### Parameters:
108
+ * `$statuses` *(array)* — Associative array of transaction statuses (`pending`, `succeeded`, `authorized`, `failed`, `refunded`)
109
+ * `$data` *(array)* — Additional context data (empty array)
110
+ * **Returns:** *(array)* — The modified transaction statuses array
111
+
112
+ #### Usage Example:
113
+ ```php
114
+ // Filter primary transaction system statuses array
115
+ add_filter('fluent_cart/transaction_statuses', function ($statuses, $data) {
116
+ // Add custom "Disputed" transaction status
117
+ $statuses['disputed'] = __('Disputed', 'my-plugin');
118
+ return $statuses;
119
+ }, 10, 2);
120
+ ```
121
+
122
+ ---
123
+
124
+ ### `transaction_statuses` (legacy)
125
+ `fluent-cart/transaction_statuses` — Filter transaction statuses (legacy hook name)
126
+
127
+ * **When it runs:** Legacy location of the transaction statuses filter. Applied in the older Helper class. Prefer `fluent_cart/transaction_statuses` for new code.
128
+ * **Source:** `app/Helpers/Helper.php` (line 215)
129
+
130
+ #### Parameters:
131
+ * `$statuses` *(array)* — Associative array of transaction statuses
132
+ * `$data` *(array)* — Additional context data (empty array)
133
+ * **Returns:** *(array)* — The modified transaction statuses array
134
+
135
+ #### Usage Example:
136
+ ```php
137
+ // Filter transaction statuses using legacy hyphenated hook name
138
+ add_filter('fluent-cart/transaction_statuses', function ($statuses, $data) {
139
+ // Return modified transaction statuses array
140
+ return $statuses;
141
+ }, 10, 2);
142
+ ```
143
+
144
+ ---
145
+
146
+ ### `editable_transaction_statuses`
147
+ `fluent-cart/editable_transaction_statuses` — Filter manually editable transaction statuses
148
+
149
+ * **When it runs:** Applied when building the list of transaction statuses that an admin can manually set. Note the hyphenated prefix (`fluent-cart/`).
150
+ * **Source:** `app/Helpers/Helper.php` (line 233), `app/Helpers/Status.php` (line 214)
151
+
152
+ #### Parameters:
153
+ * `$statuses` *(array)* — Associative array of editable transaction statuses
154
+ * `$data` *(array)* — Additional context data (empty array)
155
+ * **Returns:** *(array)* — The modified editable transaction statuses array
156
+
157
+ #### Usage Example:
158
+ ```php
159
+ // Filter manually editable transaction statuses for admin dropdown
160
+ add_filter('fluent-cart/editable_transaction_statuses', function ($statuses, $data) {
161
+ // Remove "refunded" status from manually selectable transaction statuses
162
+ unset($statuses['refunded']);
163
+ return $statuses;
164
+ }, 10, 2);
165
+ ```
166
+
167
+ ---
168
+
169
+ ### `transaction_success_statuses`
170
+ `fluent_cart/transaction_success_statuses` — Filter which statuses count as successful transactions
171
+
172
+ * **When it runs:** Applied when determining which transaction statuses should be considered "successful" for reporting and order completion logic.
173
+ * **Source:** `app/Helpers/Status.php` (line 331)
174
+
175
+ #### Parameters:
176
+ * `$statuses` *(array)* — Indexed array of status strings (default: `['succeeded', 'authorized']`)
177
+ * `$data` *(array)* — Additional context data (empty array)
178
+ * **Returns:** *(array)* — The modified success statuses array
179
+
180
+ #### Usage Example:
181
+ ```php
182
+ // Filter which transaction statuses count as successful for reports
183
+ add_filter('fluent_cart/transaction_success_statuses', function ($statuses, $data) {
184
+ // Add "captured" to list of successful transaction statuses
185
+ $statuses[] = 'captured';
186
+ return $statuses;
187
+ }, 10, 2);
188
+ ```
189
+
190
+ ---
191
+
192
+ ### `shipping_statuses` (legacy)
193
+ `fluent-cart/shipping_statuses` — Filter shipping statuses (legacy hook name)
194
+
195
+ * **When it runs:** Legacy location of the shipping statuses filter. Prefer `fluent_cart/shipping_statuses` for new code.
196
+ * **Source:** `app/Helpers/Helper.php` (line 170)
197
+
198
+ #### Parameters:
199
+ * `$statuses` *(array)* — Associative array of shipping statuses
200
+ * `$data` *(array)* — Additional context data (empty array)
201
+ * **Returns:** *(array)* — The modified shipping statuses array
202
+
203
+ #### Usage Example:
204
+ ```php
205
+ // Filter shipping statuses using legacy hyphenated hook name
206
+ add_filter('fluent-cart/shipping_statuses', function ($statuses, $data) {
207
+ // Return shipping statuses array
208
+ return $statuses;
209
+ }, 10, 2);
210
+ ```
211
+
212
+ ---
213
+
214
+ ### `shipping_statuses`
215
+ `fluent_cart/shipping_statuses` — Filter shipping statuses
216
+
217
+ * **When it runs:** Applied when retrieving the list of available shipping statuses used for order fulfillment.
218
+ * **Source:** `app/Helpers/Status.php` (line 232)
219
+
220
+ #### Parameters:
221
+ * `$statuses` *(array)* — Associative array of shipping statuses (`unshipped`, `shipped`, `delivered`, `unshippable`)
222
+ * `$data` *(array)* — Additional context data (empty array)
223
+ * **Returns:** *(array)* — The modified shipping statuses array
224
+
225
+ #### Usage Example:
226
+ ```php
227
+ // Filter available shipping statuses for order fulfillment
228
+ add_filter('fluent_cart/shipping_statuses', function ($statuses, $data) {
229
+ // Add custom "In Transit" shipping status
230
+ $statuses['in_transit'] = __('In Transit', 'my-plugin');
231
+ return $statuses;
232
+ }, 10, 2);
233
+ ```
234
+
235
+ ---
236
+
237
+ ## Order Data & Lifecycle
238
+
239
+ ### `orders_list`
240
+ `fluent_cart/orders_list` — Filter the admin orders list
241
+
242
+ * **When it runs:** Applied after retrieving the paginated orders collection for the admin orders list view.
243
+ * **Source:** `app/Http/Controllers/OrderController.php` (line 58)
244
+
245
+ #### Parameters:
246
+ * `$orders` *(\FluentCart\Framework\Database\Orm\LengthAwarePaginator)* — Paginated collection of orders
247
+ * **Returns:** *(\FluentCart\Framework\Database\Orm\LengthAwarePaginator)* — The modified paginated orders collection
248
+
249
+ #### Usage Example:
250
+ ```php
251
+ // Filter paginated orders collection for admin list view
252
+ add_filter('fluent_cart/orders_list', function ($orders) {
253
+ // Loop through orders and inject custom badge post meta
254
+ foreach ($orders as $order) {
255
+ $order->custom_badge = get_post_meta($order->id, '_custom_badge', true);
256
+ }
257
+ return $orders;
258
+ }, 10, 1);
259
+ ```
260
+
261
+ ---
262
+
263
+ ### `order/view`
264
+ `fluent_cart/order/view` — Filter single order view data
265
+
266
+ * **When it runs:** Applied when preparing the data for a single order view in the admin panel.
267
+ * **Source:** `app/Http/Controllers/OrderController.php` (line 580)
268
+
269
+ #### Parameters:
270
+ * `$order` *(array)* — The order data array containing all order details
271
+ * `$data` *(array)* — Additional context data (empty array)
272
+ * **Returns:** *(array)* — The modified order data
273
+
274
+ #### Usage Example:
275
+ ```php
276
+ // Filter single order view data structure in admin panel
277
+ add_filter('fluent_cart/order/view', function ($order, $data) {
278
+ // Inject custom field key into order view data payload
279
+ $order['custom_field'] = 'Custom Value';
280
+ return $order;
281
+ }, 10, 2);
282
+ ```
283
+
284
+ ---
285
+
286
+ ### `widgets/single_order`
287
+ `fluent_cart/widgets/single_order` — Filter single order admin widgets
288
+
289
+ * **When it runs:** Applied when loading the stats/widgets section on the single order admin view.
290
+ * **Source:** `app/Http/Controllers/OrderController.php` (line 1009)
291
+
292
+ #### Parameters:
293
+ * `$widgets` *(array)* — Array of widget data (default empty)
294
+ * `$order` *(\FluentCart\App\Models\Order)* — The Order model instance
295
+ * **Returns:** *(array)* — Array of widget definitions to display
296
+
297
+ #### Usage Example:
298
+ ```php
299
+ // Filter admin widgets loaded on single order view page
300
+ add_filter('fluent_cart/widgets/single_order', function ($widgets, $order) {
301
+ // Append custom widget array definition for single order
302
+ $widgets[] = [
303
+ 'title' => __('Custom Widget', 'my-plugin'),
304
+ 'value' => 'Some data for order #' . $order->id,
305
+ ];
306
+ return $widgets;
307
+ }, 10, 2);
308
+ ```
309
+
310
+ ---
311
+
312
+ ### `order/is_subscription_allowed_in_manual_order`
313
+ `fluent_cart/order/is_subscription_allowed_in_manual_order` — Allow subscriptions in manual orders
314
+
315
+ * **When it runs:** Applied when creating a manual order that contains subscription items. By default, subscriptions in manual orders are not supported.
316
+ * **Source:** `app/Http/Controllers/OrderController.php` (line 78)
317
+
318
+ #### Parameters:
319
+ * `$allowed` *(bool)* — Whether subscriptions are allowed (default: `false`)
320
+ * `$context` *(array)* — Context data (`['order_items' => [...]]`)
321
+ * **Returns:** *(bool)* — Whether to allow subscription items in manual orders
322
+
323
+ #### Usage Example:
324
+ ```php
325
+ // Filter whether subscriptions are allowed in manual order creation
326
+ add_filter('fluent_cart/order/is_subscription_allowed_in_manual_order', function ($allowed, $context) {
327
+ // Enable subscription items in manual orders
328
+ return true;
329
+ }, 10, 2);
330
+ ```
331
+
332
+ ---
333
+
334
+ ### `order/type`
335
+ `fluent_cart/order/type` — Filter order type during manual creation
336
+
337
+ * **When it runs:** Applied when determining the order type during manual order creation. Automatically set to `'subscription'` if subscription items are detected, otherwise `'payment'`.
338
+ * **Source:** `app/Http/Controllers/OrderController.php` (line 91)
339
+
340
+ #### Parameters:
341
+ * `$type` *(string)* — The order type (`'payment'` or `'subscription'`)
342
+ * `$data` *(array)* — Additional context data (empty array)
343
+ * **Returns:** *(string)* — The order type string
344
+
345
+ #### Usage Example:
346
+ ```php
347
+ // Filter order type classification during manual order creation
348
+ add_filter('fluent_cart/order/type', function ($type, $data) {
349
+ // Return order type string ('payment' or 'subscription')
350
+ return $type;
351
+ }, 10, 2);
352
+ ```
353
+
354
+ ---
355
+
356
+ ### `order/expected_license_count`
357
+ `fluent_cart/order/expected_license_count` — Filter expected license count for an order
358
+
359
+ * **When it runs:** Applied when checking how many licenses should exist for an order. Used to detect missing licenses that need to be regenerated.
360
+ * **Source:** `app/Http/Controllers/OrderController.php` (lines 215, 585)
361
+
362
+ #### Parameters:
363
+ * `$count` *(int)* — Expected number of licenses (default: `0`)
364
+ * `$context` *(array)* — Context data (`['order_items' => [...]]`)
365
+ * **Returns:** *(int)* — The expected number of licenses
366
+
367
+ #### Usage Example:
368
+ ```php
369
+ // Filter expected license count to detect missing licenses for order
370
+ add_filter('fluent_cart/order/expected_license_count', function ($count, $context) {
371
+ // Calculate expected license count based on order item requirements
372
+ foreach ($context['order_items'] as $item) {
373
+ if ($item->requires_license) {
374
+ $count += $item->quantity;
375
+ }
376
+ }
377
+ return $count;
378
+ }, 10, 2);
379
+ ```
380
+
381
+ ---
382
+
383
+ ### `create_receipt_number_on_order_create`
384
+ `fluent_cart/create_receipt_number_on_order_create` — Force receipt number generation on order creation
385
+
386
+ * **When it runs:** Applied during the order creating model event. By default, receipt numbers are only generated when the payment status is `'paid'`. Return true to always generate a receipt number.
387
+ * **Source:** `app/Models/Order.php` (line 52)
388
+
389
+ #### Parameters:
390
+ * `$force` *(bool)* — Whether to force receipt number creation (default: `false`)
391
+ * **Returns:** *(bool)* — Whether to generate a receipt number regardless of payment status
392
+
393
+ #### Usage Example:
394
+ ```php
395
+ // Filter whether to force receipt number creation when order is created
396
+ add_filter('fluent_cart/create_receipt_number_on_order_create', function ($force) {
397
+ // Always generate receipt number upon order creation regardless of payment status
398
+ return true;
399
+ }, 10, 1);
400
+ ```
401
+
402
+ ---
403
+
404
+ ### `single_order_downloads`
405
+ `fluent_cart/single_order_downloads` — Filter order downloads data
406
+
407
+ * **When it runs:** Applied when preparing the downloadable files for a specific order, allowing you to add, remove, or modify download data.
408
+ * **Source:** `app/Models/Order.php` (line 657)
409
+
410
+ #### Parameters:
411
+ * `$downloadData` *(array)* — Array of download groups (`title`, `product_id`, `downloads`, etc.)
412
+ * `$context` *(array)* — Context data (`['order' => Order, 'scope' => 'admin'|'customer']`)
413
+ * **Returns:** *(array)* — The modified download data array
414
+
415
+ #### Usage Example:
416
+ ```php
417
+ // Filter downloadable files data array for a specific order
418
+ add_filter('fluent_cart/single_order_downloads', function ($downloadData, $context) {
419
+ // Add bonus download file for completed orders
420
+ if ($context['order']->status === 'completed') {
421
+ $downloadData[] = [
422
+ 'title' => 'Bonus Content',
423
+ 'downloads' => [
424
+ ['name' => 'Bonus File', 'url' => 'https://example.com/bonus.pdf']
425
+ ]
426
+ ];
427
+ }
428
+ return $downloadData;
429
+ }, 10, 2);
430
+ ```
431
+
432
+ ---
433
+
434
+ ### `order_can_be_deleted`
435
+ `fluent_cart/order_can_be_deleted` — Filter whether an order can be deleted
436
+
437
+ * **When it runs:** Applied when checking if an order is eligible for deletion. By default, orders with active subscriptions cannot be deleted.
438
+ * **Source:** `app/Models/Order.php` (line 812)
439
+
440
+ #### Parameters:
441
+ * `$canBeDeleted` *(true|\WP_Error)* — `true` if deletable, or a `WP_Error` with the reason
442
+ * `$context` *(array)* — Context data (`['order' => Order]`)
443
+ * **Returns:** *(true|\WP_Error)* — `true` to allow deletion, or `WP_Error` to block it
444
+
445
+ #### Usage Example:
446
+ ```php
447
+ // Filter whether an order is eligible for deletion
448
+ add_filter('fluent_cart/order_can_be_deleted', function ($canBeDeleted, $context) {
449
+ // Extract order model from context
450
+ $order = $context['order'];
451
+ // Prevent deletion of orders created within the last 30 days
452
+ if (strtotime($order->created_at) > strtotime('-30 days')) {
453
+ return new \WP_Error('too_recent', __('Orders less than 30 days old cannot be deleted.', 'my-plugin'));
454
+ }
455
+ return $canBeDeleted;
456
+ }, 10, 2);
457
+ ```
458
+
459
+ ---
460
+
461
+ ### `min_receipt_number`
462
+ `fluent_cart/min_receipt_number` — Filter the minimum receipt number
463
+
464
+ * **When it runs:** Applied when calculating the next receipt number. If the computed next number is below this minimum, it will be bumped up.
465
+ * **Source:** `app/Services/OrderService.php` (line 572)
466
+
467
+ #### Parameters:
468
+ * `$min` *(int)* — The minimum receipt number from store settings (default: `1`)
469
+ * **Returns:** *(int)* — The minimum receipt number to enforce
470
+
471
+ #### Usage Example:
472
+ ```php
473
+ // Filter minimum receipt number value
474
+ add_filter('fluent_cart/min_receipt_number', function ($min) {
475
+ // Enforce starting receipt number of 1000
476
+ return 1000;
477
+ }, 10, 1);
478
+ ```
479
+
480
+ ---
481
+
482
+ ### `invoice_prefix`
483
+ `fluent_cart/invoice_prefix` — Filter the invoice number prefix
484
+
485
+ * **When it runs:** Applied when generating the invoice number string for new orders. Formed as `prefix + receipt_number`.
486
+ * **Source:** `app/Services/OrderService.php` (line 584)
487
+
488
+ #### Parameters:
489
+ * `$prefix` *(string)* — The invoice prefix from store settings (default: `'INV-'`)
490
+ * **Returns:** *(string)* — The modified invoice prefix
491
+
492
+ #### Usage Example:
493
+ ```php
494
+ // Filter invoice number prefix string
495
+ add_filter('fluent_cart/invoice_prefix', function ($prefix) {
496
+ // Use dynamic year-based invoice prefix string
497
+ return 'INV-' . date('Y') . '-';
498
+ }, 10, 1);
499
+ ```
500
+
501
+ ---
502
+
503
+ ### `order_refund_manually`
504
+ `fluent_cart/order_refund_manually` — Intercept manual refund processing
505
+
506
+ * **When it runs:** Applied during the refund process before the payment gateway refund method is called. Allows you to handle refunds through a custom mechanism instead of the gateway.
507
+ * **Source:** `app/Services/Payments/Refund.php` (line 65)
508
+
509
+ #### Parameters:
510
+ * `$manualRefund` *(array)* — Manual refund status (`['status' => 'no', 'source' => '']`)
511
+ * `$context` *(array)* — Refund context (`['refund_amount' => 5000, 'transaction' => Transaction, 'order' => Order, 'args' => [...]]`)
512
+ * **Returns:** *(array)* — Array with `'status'` key set to `'yes'` to skip the gateway refund
513
+
514
+ #### Usage Example:
515
+ ```php
516
+ // Intercept manual refund processing before payment gateway invocation
517
+ add_filter('fluent_cart/order_refund_manually', function ($manualRefund, $context) {
518
+ // Process refund via custom refund service logic
519
+ $result = my_custom_refund($context['transaction'], $context['refund_amount']);
520
+ if ($result) {
521
+ return ['status' => 'yes', 'source' => 'my_custom_service'];
522
+ }
523
+ return $manualRefund;
524
+ }, 10, 2);
525
+ ```
526
+
527
+ ---
528
+
529
+ ### `order_status/auto_complete_digital_order`
530
+ `fluent_cart/order_status/auto_complete_digital_order` — Control auto-completion of digital orders
531
+
532
+ * **When it runs:** Applied during payment status reconciliation. When a digital (non-physical) order is paid, it is automatically marked as completed. Return false to prevent this behavior.
533
+ * **Source:** `app/Helpers/StatusHelper.php` (line 193)
534
+
535
+ #### Parameters:
536
+ * `$autoComplete` *(bool)* — Whether to auto-complete the order (default: `true`)
537
+ * `$context` *(array)* — Context data (`['order' => Order]`)
538
+ * **Returns:** *(bool)* — Whether to automatically complete the digital order
539
+
540
+ #### Usage Example:
541
+ ```php
542
+ // Control auto-completion behavior for digital product orders
543
+ add_filter('fluent_cart/order_status/auto_complete_digital_order', function ($autoComplete, $context) {
544
+ // Require manual review for high-value digital orders over $500
545
+ if ($context['order']->total > 50000) {
546
+ return false;
547
+ }
548
+ return $autoComplete;
549
+ }, 10, 2);
550
+ ```
551
+
552
+ ---
553
+
554
+ ### `customer/order_data`
555
+ `fluent_cart/customer/order_data` — Filter customer portal order data
556
+
557
+ * **When it runs:** Applied when preparing order data for display in the customer-facing order details page.
558
+ * **Source:** `app/Http/Controllers/FrontendControllers/CustomerOrderController.php` (line 285)
559
+
560
+ #### Parameters:
561
+ * `$formattedOrderData` *(array)* — The formatted order data array
562
+ * `$context` *(array)* — Context data (`['order' => Order, 'customer' => Customer]`)
563
+ * **Returns:** *(array)* — The modified formatted order data
564
+
565
+ #### Usage Example:
566
+ ```php
567
+ // Filter formatted order data array in customer portal order details view
568
+ add_filter('fluent_cart/customer/order_data', function ($formattedOrderData, $context) {
569
+ // Inject estimated delivery date meta into customer order details
570
+ $formattedOrderData['estimated_delivery'] = get_post_meta(
571
+ $context['order']->id, '_estimated_delivery', true
572
+ );
573
+ return $formattedOrderData;
574
+ }, 10, 2);
575
+ ```
576
+
577
+ ---
578
+
579
+ ### `customer/order_details_section_parts`
580
+ `fluent_cart/customer/order_details_section_parts` — Filter customer order detail sections
581
+
582
+ * **When it runs:** Applied when building the customer-facing order details page. Allows you to inject custom HTML content into predefined section slots.
583
+ * **Source:** `app/Http/Controllers/FrontendControllers/CustomerOrderController.php` (line 292)
584
+
585
+ #### Parameters:
586
+ * `$sections` *(array)* — HTML content for section slots (`before_summary`, `after_summary`, `after_licenses`, `after_subscriptions`, `after_downloads`, `after_transactions`, `end_of_order`)
587
+ * `$context` *(array)* — Context data (`['order' => Order, 'formattedData' => [...]]`)
588
+ * **Returns:** *(array)* — The modified sections array with HTML content
589
+
590
+ #### Usage Example:
591
+ ```php
592
+ // Filter customer order detail section HTML parts
593
+ add_filter('fluent_cart/customer/order_details_section_parts', function ($sections, $context) {
594
+ // Inject custom HTML notice after order summary section
595
+ $sections['after_summary'] = '<div class="custom-notice">Thank you for your order!</div>';
596
+ return $sections;
597
+ }, 10, 2);
598
+ ```
599
+
600
+ ---
601
+
602
+ ## Payment Processing
603
+
604
+ ### `ipn_url_{$slug}`
605
+ `fluent_cart_ipn_url_{$slug}` — Filter IPN/webhook listener URL for a payment gateway
606
+
607
+ * **When it runs:** Applied when generating the IPN or webhook listener URL for a specific payment method. The `{$slug}` is the gateway slug (e.g. `stripe`, `paypal`).
608
+ * **Source:** `app/Services/Payments/PaymentHelper.php` (line 24)
609
+
610
+ #### Parameters:
611
+ * `$urlData` *(array)* — Array containing the listener URL (`['listener_url' => '...']`)
612
+ * **Returns:** *(array)* — The modified URL data array
613
+
614
+ #### Usage Example:
615
+ ```php
616
+ // Filter IPN / webhook listener URL for Stripe gateway
617
+ add_action('fluent_cart_ipn_url_stripe', function ($urlData) {
618
+ // Set custom endpoint URL for Stripe webhooks
619
+ $urlData['listener_url'] = home_url('/custom-stripe-webhook/');
620
+ return $urlData;
621
+ }, 10, 1);
622
+ ```
623
+
624
+ ---
625
+
626
+ ### `payment/success_url`
627
+ `fluentcart/payment/success_url` — Filter the payment success redirect URL
628
+
629
+ * **When it runs:** Applied when generating the URL the customer is redirected to after a successful payment. Note the legacy prefix (`fluentcart/`).
630
+ * **Source:** `app/Services/Payments/PaymentHelper.php` (line 46)
631
+
632
+ #### Parameters:
633
+ * `$url` *(string)* — The success redirect URL (receipt page with query args)
634
+ * `$context` *(array)* — Context data (`['transaction_hash' => '...', 'args' => [], 'payment_method' => 'stripe']`)
635
+ * **Returns:** *(string)* — The modified success URL
636
+
637
+ #### Usage Example:
638
+ ```php
639
+ // Filter payment success redirect URL (legacy hook prefix)
640
+ add_filter('fluentcart/payment/success_url', function ($url, $context) {
641
+ // Redirect customer to custom thank-you page with transaction hash
642
+ return add_query_arg('trx_hash', $context['transaction_hash'], home_url('/thank-you/'));
643
+ }, 10, 2);
644
+ ```
645
+
646
+ ---
647
+
648
+ ### `default_payment_method_for_zero_payment`
649
+ `fluent_cart/default_payment_method_for_zero_payment` — Filter default payment method for zero-total orders
650
+
651
+ * **When it runs:** Applied during checkout validation when the order total (including recurring) is zero. Determines which payment method handles the $0 transaction.
652
+ * **Source:** `app/Services/Payments/PaymentHelper.php` (line 70)
653
+
654
+ #### Parameters:
655
+ * `$method` *(string)* — Payment method slug (default: `'offline_payment'`)
656
+ * `$data` *(array)* — Additional context data (empty array)
657
+ * **Returns:** *(string)* — The payment method slug to use for zero-total orders
658
+
659
+ #### Usage Example:
660
+ ```php
661
+ // Filter default payment method slug for zero-total orders
662
+ add_filter('fluent_cart/default_payment_method_for_zero_payment', function ($method, $data) {
663
+ // Use Stripe for zero-total orders with recurring subscriptions
664
+ return 'stripe';
665
+ }, 10, 2);
666
+ ```
667
+
668
+ ---
669
+
670
+ ### `get_payment_connect_info_{$method}`
671
+ `fluent_cart/get_payment_connect_info_{$method}` — Filter payment method connection info
672
+
673
+ * **When it runs:** Applied when retrieving connection/setup information for a specific payment method. The `{$method}` is the sanitized gateway slug. Used by gateways that require an OAuth connection flow.
674
+ * **Source:** `api/PaymentMethods.php` (line 105)
675
+
676
+ #### Parameters:
677
+ * `$info` *(array)* — Connection info array (default: `[]`)
678
+ * `$data` *(array)* — Additional context data (empty array)
679
+ * **Returns:** *(array)* — The payment method connection information
680
+
681
+ #### Usage Example:
682
+ ```php
683
+ // Filter payment method OAuth connect information for Stripe
684
+ add_filter('fluent_cart/get_payment_connect_info_stripe', function ($info, $data) {
685
+ // Set connected status and Stripe account ID
686
+ $info['connected'] = true;
687
+ $info['account_id'] = 'acct_xxx';
688
+ return $info;
689
+ }, 10, 2);
690
+ ```
691
+
692
+ ---
693
+
694
+ ### `transaction/url_{$payment_method}`
695
+ `fluent_cart/transaction/url_{$payment_method}` — Filter vendor dashboard URL for a transaction
696
+
697
+ * **When it runs:** Applied when generating the URL attribute of an `OrderTransaction` model. The `{$payment_method}` is the gateway slug. Links to the transaction in the provider dashboard.
698
+ * **Source:** `app/Models/OrderTransaction.php` (line 111)
699
+
700
+ #### Parameters:
701
+ * `$url` *(string)* — The vendor URL (default: `''`)
702
+ * `$context` *(array)* — Context data (`['transaction' => Transaction, 'payment_mode' => 'live'|'test', 'vendor_charge_id' => 'ch_xxx', 'transaction_type' => 'charge']`)
703
+ * **Returns:** *(string)* — The URL to the transaction in the payment provider dashboard
704
+
705
+ #### Usage Example:
706
+ ```php
707
+ // Filter vendor dashboard URL attribute for Stripe transactions
708
+ add_filter('fluent_cart/transaction/url_stripe', function ($url, $context) {
709
+ // Extract vendor charge ID and mode
710
+ $chargeId = $context['vendor_charge_id'];
711
+ $mode = $context['payment_mode'] === 'test' ? 'test/' : '';
712
+
713
+ // Construct Stripe dashboard transaction URL
714
+ return "https://dashboard.stripe.com/{$mode}payments/{$chargeId}";
715
+ }, 10, 2);
716
+ ```
717
+
718
+ ---
719
+
720
+ ### `transaction/receipt_page_url`
721
+ `fluentcart/transaction/receipt_page_url` — Filter the transaction receipt page URL
722
+
723
+ * **When it runs:** Applied when generating the public-facing receipt page URL for a transaction. Note legacy prefix (`fluentcart/`).
724
+ * **Source:** `app/Models/OrderTransaction.php` (line 183)
725
+
726
+ #### Parameters:
727
+ * `$url` *(string)* — The receipt page URL with `trx_hash` query parameter
728
+ * `$context` *(array)* — Context data (`['transaction' => Transaction, 'order' => Order]`)
729
+ * **Returns:** *(string)* — The modified receipt page URL
730
+
731
+ #### Usage Example:
732
+ ```php
733
+ // Filter public receipt page URL for transaction (legacy hook prefix)
734
+ add_filter('fluentcart/transaction/receipt_page_url', function ($url, $context) {
735
+ // Use custom public receipt page URL with transaction hash
736
+ return add_query_arg('trx_hash', $context['transaction']->uuid, home_url('/my-receipt/'));
737
+ }, 10, 2);
738
+ ```
739
+
740
+ ---
741
+
742
+ ## Stripe
743
+
744
+ ### `stripe_settings`
745
+ `fluent_cart/stripe_settings` — Filter Stripe gateway settings
746
+
747
+ * **When it runs:** Applied when loading Stripe gateway settings during initialization.
748
+ * **Source:** `app/Modules/PaymentMethods/StripeGateway/StripeSettingsBase.php` (line 38)
749
+
750
+ #### Parameters:
751
+ * `$settings` *(array)* — The Stripe settings array including keys, modes, and configuration options
752
+ * **Returns:** *(array)* — The modified Stripe settings
753
+
754
+ #### Usage Example:
755
+ ```php
756
+ // Filter Stripe gateway settings array during initialization
757
+ add_filter('fluent_cart/stripe_settings', function ($settings) {
758
+ // Force test mode in staging environment
759
+ if (wp_get_environment_type() === 'staging') {
760
+ $settings['payment_mode'] = 'test';
761
+ }
762
+ return $settings;
763
+ }, 10, 1);
764
+ ```
765
+
766
+ ---
767
+
768
+ ### `payments/stripe_metadata_subscription`
769
+ `fluent_cart/payments/stripe_metadata_subscription` — Filter Stripe subscription metadata
770
+
771
+ * **When it runs:** Applied when creating a Stripe subscription, allowing you to add or modify metadata sent to Stripe's subscription object. Max 50 keys per Stripe API limits.
772
+ * **Source:** `app/Modules/PaymentMethods/StripeGateway/Processor.php` (line 90)
773
+
774
+ #### Parameters:
775
+ * `$metadata` *(array)* — Metadata array for Stripe subscription (`fct_ref_id`, `email`, `name`, `subscription_item`, `order_reference`)
776
+ * `$context` *(array)* — Context data (`['order' => Order, 'transaction' => Transaction, 'subscription' => Subscription]`)
777
+ * **Returns:** *(array)* — The modified metadata array
778
+
779
+ #### Usage Example:
780
+ ```php
781
+ // Filter Stripe subscription metadata array
782
+ add_filter('fluent_cart/payments/stripe_metadata_subscription', function ($metadata, $context) {
783
+ // Inject custom affiliate ID into Stripe subscription metadata
784
+ $metadata['affiliate_id'] = get_user_meta($context['order']->customer->user_id, 'affiliate_id', true);
785
+ return $metadata;
786
+ }, 10, 2);
787
+ ```
788
+
789
+ ---
790
+
791
+ ### `payments/stripe_metadata_onetime`
792
+ `fluent_cart/payments/stripe_metadata_onetime` — Filter Stripe one-time payment metadata
793
+
794
+ * **When it runs:** Applied when creating a Stripe payment intent for a one-time payment. Max 50 keys per Stripe API limits.
795
+ * **Source:** `app/Modules/PaymentMethods/StripeGateway/Processor.php` (line 221)
796
+
797
+ #### Parameters:
798
+ * `$metadata` *(array)* — Metadata array for Stripe payment intent (`fct_ref_id`, `Name`, `Email`, `order_reference`)
799
+ * `$context` *(array)* — Context data (`['order' => Order, 'transaction' => Transaction]`)
800
+ * **Returns:** *(array)* — The modified metadata array
801
+
802
+ #### Usage Example:
803
+ ```php
804
+ // Filter Stripe one-time payment intent metadata array
805
+ add_filter('fluent_cart/payments/stripe_metadata_onetime', function ($metadata, $context) {
806
+ // Inject campaign tag and customer ID into metadata
807
+ $metadata['campaign'] = 'spring_sale_2025';
808
+ if (isset($context['order'])) {
809
+ $metadata['customer_id'] = $context['order']->customer_id;
810
+ }
811
+ return $metadata;
812
+ }, 10, 2);
813
+ ```
814
+
815
+ ---
816
+
817
+ ### `payments/stripe_onetime_intent_args`
818
+ `fluent_cart/payments/stripe_onetime_intent_args` — Filter Stripe payment intent arguments
819
+
820
+ * **When it runs:** Applied after building the full payment intent data array, just before creating the intent via the Stripe API.
821
+ * **Source:** `app/Modules/PaymentMethods/StripeGateway/Processor.php` (line 257)
822
+
823
+ #### Parameters:
824
+ * `$intentData` *(array)* — Payment intent arguments (`amount`, `currency`, `automatic_payment_methods`, `metadata`, `customer`)
825
+ * `$context` *(array)* — Context data (`['order' => Order, 'transaction' => Transaction]`)
826
+ * **Returns:** *(array)* — The modified payment intent arguments
827
+
828
+ #### Usage Example:
829
+ ```php
830
+ // Filter Stripe payment intent arguments for one-time payments
831
+ add_filter('fluent_cart/payments/stripe_onetime_intent_args', function ($intentData, $context) {
832
+ // Add custom statement descriptor suffix for order
833
+ $intentData['statement_descriptor_suffix'] = 'Order ' . $context['order']->id;
834
+ return $intentData;
835
+ }, 10, 2);
836
+ ```
837
+
838
+ ---
839
+
840
+ ### `payments/stripe_checkout_session_args`
841
+ `fluent_cart/payments/stripe_checkout_session_args` — Filter Stripe Checkout session arguments (one-time)
842
+
843
+ * **When it runs:** Applied when creating a Stripe Checkout session for one-time hosted payments.
844
+ * **Source:** `app/Modules/PaymentMethods/StripeGateway/Processor.php` (line 356)
845
+
846
+ #### Parameters:
847
+ * `$sessionData` *(array)* — Checkout session arguments (`customer`, `client_reference_id`, `line_items`, `mode`, `success_url`, `cancel_url`, `metadata`)
848
+ * `$context` *(array)* — Context data (`['order' => Order, 'transaction' => Transaction]`)
849
+ * **Returns:** *(array)* — The modified Checkout session arguments
850
+
851
+ #### Usage Example:
852
+ ```php
853
+ // Filter Stripe Checkout session arguments for one-time payments
854
+ add_filter('fluent_cart/payments/stripe_checkout_session_args', function ($sessionData, $context) {
855
+ // Enable promotion codes on hosted Stripe Checkout page
856
+ $sessionData['allow_promotion_codes'] = true;
857
+ return $sessionData;
858
+ }, 10, 2);
859
+ ```
860
+
861
+ ---
862
+
863
+ ### `payments/stripe_subscription_checkout_session_args`
864
+ `fluent_cart/payments/stripe_subscription_checkout_session_args` — Filter Stripe Checkout session arguments (subscription)
865
+
866
+ * **When it runs:** Applied when creating a Stripe Checkout session for subscription-based hosted payments.
867
+ * **Source:** `app/Modules/PaymentMethods/StripeGateway/Processor.php` (line 509)
868
+
869
+ #### Parameters:
870
+ * `$sessionData` *(array)* — Checkout session arguments (`customer`, `client_reference_id`, `line_items`, `mode`, `subscription_data`, `metadata`)
871
+ * `$context` *(array)* — Context data (`['order' => Order, 'transaction' => Transaction, 'subscription' => Subscription]`)
872
+ * **Returns:** *(array)* — The modified Checkout session arguments
873
+
874
+ #### Usage Example:
875
+ ```php
876
+ // Filter Stripe Checkout session arguments for subscriptions
877
+ add_filter('fluent_cart/payments/stripe_subscription_checkout_session_args', function ($sessionData, $context) {
878
+ // Enable tax ID collection on hosted subscription Checkout page
879
+ $sessionData['tax_id_collection'] = ['enabled' => true];
880
+ return $sessionData;
881
+ }, 10, 2);
882
+ ```
883
+
884
+ ---
885
+
886
+ ### `stripe_idempotency_key`
887
+ `fluent_cart_stripe_idempotency_key` — Filter the Stripe idempotency key
888
+
889
+ * **When it runs:** Applied when sending charge requests to the Stripe API to prevent duplicate charges.
890
+ * **Source:** `app/Modules/PaymentMethods/StripeGateway/API/ApiRequest.php` (line 115)
891
+
892
+ #### Parameters:
893
+ * `$key` *(string)* — Generated idempotency key string
894
+ * `$context` *(array)* — Context data (`['request' => [...]]`)
895
+ * **Returns:** *(string)* — The modified idempotency key
896
+
897
+ #### Usage Example:
898
+ ```php
899
+ // Filter Stripe API request idempotency key string
900
+ add_filter('fluent_cart_stripe_idempotency_key', function ($key, $context) {
901
+ // Generate custom hashed idempotency key
902
+ return 'fct_' . md5($key . time());
903
+ }, 10, 2);
904
+ ```
905
+
906
+ ---
907
+
908
+ ### `stripe_request_body`
909
+ `fluent_cart_stripe_request_body` — Filter the Stripe API request body
910
+
911
+ * **When it runs:** Applied just before every request is sent to the Stripe API. Low-level filter affecting all Stripe calls.
912
+ * **Source:** `app/Modules/PaymentMethods/StripeGateway/API/ApiRequest.php` (line 126)
913
+
914
+ #### Parameters:
915
+ * `$request` *(array)* — The request body data array
916
+ * `$context` *(array)* — Context data (`['api' => 'charges']`)
917
+ * **Returns:** *(array)* — The modified request body
918
+
919
+ #### Usage Example:
920
+ ```php
921
+ // Filter Stripe API request body data array
922
+ add_filter('fluent_cart_stripe_request_body', function ($request, $context) {
923
+ // Log low-level Stripe API call endpoint
924
+ error_log('Stripe API call to: ' . $context['api']);
925
+ return $request;
926
+ }, 10, 2);
927
+ ```
928
+
929
+ ---
930
+
931
+ ### `form_disable_stripe_connect`
932
+ `fluent_cart_form_disable_stripe_connect` — Disable Stripe Connect provider option
933
+
934
+ * **When it runs:** Applied when rendering the Stripe settings form. Return true to force manual API keys.
935
+ * **Source:** `app/Modules/PaymentMethods/StripeGateway/Stripe.php` (line 288)
936
+
937
+ #### Parameters:
938
+ * `$disable` *(bool)* — Whether to disable Stripe Connect (default: `false`)
939
+ * `$data` *(array)* — Additional context data (empty array)
940
+ * **Returns:** *(bool)* — `true` to disable Stripe Connect and force manual API keys mode
941
+
942
+ #### Usage Example:
943
+ ```php
944
+ // Filter whether to disable Stripe Connect option in admin form
945
+ add_filter('fluent_cart_form_disable_stripe_connect', function ($disable, $data) {
946
+ // Force manual API keys mode for Stripe
947
+ return true;
948
+ }, 10, 2);
949
+ ```
950
+
951
+ ---
952
+
953
+ ### `stripe_appearance`
954
+ `fluent_cart_stripe_appearance` — Filter Stripe Elements appearance configuration
955
+
956
+ * **When it runs:** Applied when initializing Stripe Elements on the checkout page. Controls visual theme and styling.
957
+ * **Source:** `app/Modules/PaymentMethods/StripeGateway/Stripe.php` (line 427)
958
+
959
+ #### Parameters:
960
+ * `$appearance` *(array)* — Stripe Elements appearance configuration array (`['theme' => 'stripe']`)
961
+ * **Returns:** *(array)* — The modified appearance configuration (follows Stripe Appearance API)
962
+
963
+ #### Usage Example:
964
+ ```php
965
+ // Filter Stripe Elements appearance configuration array
966
+ add_filter('fluent_cart_stripe_appearance', function ($appearance) {
967
+ // Apply custom dark theme styling to embedded Stripe form
968
+ return [
969
+ 'theme' => 'night',
970
+ 'variables' => [
971
+ 'colorPrimary' => '#0570de',
972
+ 'borderRadius' => '8px',
973
+ 'fontFamily' => 'Inter, system-ui, sans-serif',
974
+ ],
975
+ ];
976
+ }, 10, 1);
977
+ ```
978
+
979
+ ---
980
+
981
+ ### `stripe/setup_intent_rate_limit_customer_daily`
982
+ `fluent_cart/stripe/setup_intent_rate_limit_customer_daily` — Filter daily SetupIntent rate limit per customer
983
+
984
+ * **When it runs:** Applied when enforcing rate limit for Stripe SetupIntent creation (used for subscription card updates).
985
+ * **Source:** `app/Modules/PaymentMethods/StripeGateway/SubscriptionsManager.php` (lines 85, 101)
986
+
987
+ #### Parameters:
988
+ * `$limit` *(int)* — Maximum SetupIntent attempts per customer per day (default: `3`)
989
+ * `$customerId` *(string)* — The Stripe customer ID
990
+ * **Returns:** *(int)* — The modified daily rate limit
991
+
992
+ #### Usage Example:
993
+ ```php
994
+ // Filter daily SetupIntent rate limit count per customer
995
+ add_filter('fluent_cart/stripe/setup_intent_rate_limit_customer_daily', function ($limit, $customerId) {
996
+ // Increase daily rate limit to 5 attempts for card updates
997
+ return 5;
998
+ }, 10, 2);
999
+ ```
1000
+
1001
+ ---
1002
+
1003
+ ### `stripe/fallback_order_transaction`
1004
+ `fluent_cart/stripe/fallback_order_transaction` — Fallback transaction for Stripe webhooks
1005
+
1006
+ * **When it runs:** Applied during Stripe webhook processing when no matching `OrderTransaction` can be found by `vendor_charge_id`.
1007
+ * **Source:** `app/Modules/PaymentMethods/StripeGateway/Webhook/Webhook.php` (line 121)
1008
+
1009
+ #### Parameters:
1010
+ * `$transaction` *(\FluentCart\App\Models\OrderTransaction|null)* — The fallback transaction (default: `null`)
1011
+ * `$vendorDataObject` *(object)* — Stripe event data object containing charge details
1012
+ * **Returns:** *(\FluentCart\App\Models\OrderTransaction|null)* — OrderTransaction instance or null
1013
+
1014
+ #### Usage Example:
1015
+ ```php
1016
+ // Provide fallback OrderTransaction when vendor_charge_id lookup fails
1017
+ add_filter('fluent_cart/stripe/fallback_order_transaction', function ($transaction, $vendorDataObject) {
1018
+ // Look up transaction by reference metadata in event payload
1019
+ if (isset($vendorDataObject->metadata->fct_ref_id)) {
1020
+ $order = \FluentCart\App\Models\Order::where('uuid', $vendorDataObject->metadata->fct_ref_id)->first();
1021
+ if ($order) {
1022
+ return \FluentCart\App\Models\OrderTransaction::where('order_id', $order->id)
1023
+ ->where('transaction_type', 'charge')
1024
+ ->first();
1025
+ }
1026
+ }
1027
+ return $transaction;
1028
+ }, 10, 2);
1029
+ ```
1030
+
1031
+ ---
1032
+
1033
+ ## PayPal
1034
+
1035
+ ### `paypal_plan_id`
1036
+ `fluent_cart/paypal_plan_id` — Filter PayPal plan ID for subscriptions
1037
+
1038
+ * **When it runs:** Applied when generating or resolving the PayPal billing plan ID for a subscription product variation.
1039
+ * **Source:** `app/Modules/PaymentMethods/PayPalGateway/PayPalHelper.php` (line 54)
1040
+
1041
+ #### Parameters:
1042
+ * `$planId` *(string)* — The generated plan ID string
1043
+ * `$context` *(array)* — Context data (`['plan_data' => [...], 'variation' => Variation, 'product' => Product]`)
1044
+ * **Returns:** *(string)* — The modified PayPal plan ID
1045
+
1046
+ #### Usage Example:
1047
+ ```php
1048
+ // Filter PayPal billing plan ID for subscription product variations
1049
+ add_filter('fluent_cart/paypal_plan_id', function ($planId, $context) {
1050
+ // Construct custom formatted PayPal plan ID string
1051
+ return 'custom_plan_' . $context['variation']->id;
1052
+ }, 10, 2);
1053
+ ```
1054
+
1055
+ ---
1056
+
1057
+ ### `payments/paypal_sdk_src`
1058
+ `fluent_cart/payments/paypal_sdk_src` — Filter PayPal SDK JavaScript source URL
1059
+
1060
+ * **When it runs:** Applied when generating the PayPal JavaScript SDK script URL for the checkout page.
1061
+ * **Source:** `app/Modules/PaymentMethods/PayPalGateway/PayPal.php` (line 518)
1062
+
1063
+ #### Parameters:
1064
+ * `$sdkSrc` *(string)* — The PayPal SDK URL with query parameters
1065
+ * `$data` *(array)* — Additional context data (empty array)
1066
+ * **Returns:** *(string)* — The modified PayPal SDK URL
1067
+
1068
+ #### Usage Example:
1069
+ ```php
1070
+ // Filter PayPal SDK JavaScript script URL for checkout
1071
+ add_filter('fluent_cart/payments/paypal_sdk_src', function ($sdkSrc, $data) {
1072
+ // Append locale parameter to PayPal SDK URL
1073
+ return add_query_arg('locale', 'en_US', $sdkSrc);
1074
+ }, 10, 2);
1075
+ ```
1076
+
1077
+ ---
1078
+
1079
+ ### `payments/paypal/disable_webhook_verification`
1080
+ `fluent_cart/payments/paypal/disable_webhook_verification` — Disable PayPal webhook signature verification
1081
+
1082
+ * **When it runs:** Applied at the start of PayPal webhook verification. Return `'yes'` to skip signature verification.
1083
+ * **Source:** `app/Modules/PaymentMethods/PayPalGateway/IPN.php` (line 179)
1084
+
1085
+ #### Parameters:
1086
+ * `$disable` *(string)* — Whether to disable verification (default: `'no'`)
1087
+ * `$data` *(array)* — Additional context data (empty array)
1088
+ * **Returns:** *(string)* — `'yes'` to skip verification, `'no'` to verify normally
1089
+
1090
+ #### Usage Example:
1091
+ ```php
1092
+ // Filter whether to disable PayPal webhook signature verification
1093
+ add_filter('fluent_cart/payments/paypal/disable_webhook_verification', function ($disable, $data) {
1094
+ // Disable signature verification in local development environment
1095
+ if (wp_get_environment_type() === 'local') {
1096
+ return 'yes';
1097
+ }
1098
+ return $disable;
1099
+ }, 10, 2);
1100
+ ```
1101
+
1102
+ ---
1103
+
1104
+ ### `payments/paypal/verify_webhook`
1105
+ `fluent_cart/payments/paypal/verify_webhook` — Control PayPal webhook verification
1106
+
1107
+ * **When it runs:** Applied before the actual PayPal webhook signature verification step in the main processing flow.
1108
+ * **Source:** `app/Modules/PaymentMethods/PayPalGateway/IPN.php` (line 302)
1109
+
1110
+ #### Parameters:
1111
+ * `$verify` *(bool)* — Whether to verify the webhook (default: `true`)
1112
+ * `$context` *(array)* — Context data (`['data' => [...], 'mode' => 'live'|'test', 'type' => 'PAYMENT.SALE.COMPLETED']`)
1113
+ * **Returns:** *(bool)* — Whether to proceed with webhook verification
1114
+
1115
+ #### Usage Example:
1116
+ ```php
1117
+ // Filter whether to proceed with PayPal webhook verification
1118
+ add_filter('fluent_cart/payments/paypal/verify_webhook', function ($verify, $context) {
1119
+ // Skip verification for test mode webhooks
1120
+ if ($context['mode'] === 'test') {
1121
+ return false;
1122
+ }
1123
+ return $verify;
1124
+ }, 10, 2);
1125
+ ```
1126
+
1127
+ ---
1128
+
1129
+ ## Tax
1130
+
1131
+ ### `tax/country_tax_titles`
1132
+ `fluent_cart/tax/country_tax_titles` — Filter tax title labels per country
1133
+
1134
+ * **When it runs:** Applied when retrieving the mapping of country codes to their tax identification field labels (e.g. VAT, GST, ABN).
1135
+ * **Source:** `app/Modules/Tax/TaxModule.php` (line 1730)
1136
+
1137
+ #### Parameters:
1138
+ * `$taxTitles` *(array)* — Associative array of country code => tax label (`AU => ABN`, `GB => VAT`, `US => EIN / Sales Tax`)
1139
+ * **Returns:** *(array)* — The modified country tax titles array
1140
+
1141
+ #### Usage Example:
1142
+ ```php
1143
+ // Filter country tax identification field labels mapping array
1144
+ add_filter('fluent_cart/tax/country_tax_titles', function ($taxTitles) {
1145
+ // Override tax field labels for South Korea and US
1146
+ $taxTitles['KR'] = __('BRN / VAT', 'my-plugin');
1147
+ $taxTitles['US'] = __('Tax ID', 'my-plugin');
1148
+ return $taxTitles;
1149
+ }, 10, 1);
1150
+ ```
1151
+
1152
+ ---
1153
+
1154
+ ### `tax_summary_should_render`
1155
+ `fluent_cart/tax_summary_should_render` — Filter whether tax summary is rendered on order receipt
1156
+
1157
+ * **When it runs:** Applied in `TaxSummaryHelper::computeTaxSummary()` while building tax summary for order receipt surfaces (thank-you page, emails, PDFs).
1158
+ * **Source:** `app/Services/Renderer/Receipt/TaxSummaryHelper.php` (line 172)
1159
+
1160
+ #### Parameters:
1161
+ * `$shouldRender` *(bool)* — Whether tax summary should render (default: `true`)
1162
+ * `$order` *(\FluentCart\App\Models\Order)* — The order being rendered
1163
+ * **Returns:** *(bool)* — `false` to hide the tax summary block
1164
+
1165
+ #### Usage Example:
1166
+ ```php
1167
+ // Filter whether tax summary block is rendered on order receipt
1168
+ add_filter('fluent_cart/tax_summary_should_render', function ($shouldRender, $order) {
1169
+ // Hide tax summary block for test mode orders
1170
+ if ($order->mode === 'test') {
1171
+ return false;
1172
+ }
1173
+ return $shouldRender;
1174
+ }, 10, 2);
1175
+ ```
1176
+
1177
+ ---
1178
+
1179
+ ## Mollie (Pro)
1180
+
1181
+ ### `mollie_settings` (Pro)
1182
+ `fluent_cart/mollie_settings` — Filter Mollie gateway settings
1183
+
1184
+ * **When it runs:** Applied when loading Mollie gateway settings during initialization.
1185
+ * **Source:** `fluent-cart-pro/app/Modules/PaymentMethods/MollieGateway/MollieSettingsBase.php` (line 26)
1186
+
1187
+ #### Parameters:
1188
+ * `$settings` *(array)* — The Mollie settings array including API keys and configuration
1189
+ * **Returns:** *(array)* — The modified Mollie settings
1190
+
1191
+ #### Usage Example:
1192
+ ```php
1193
+ // Filter Mollie gateway settings array during initialization (Pro)
1194
+ add_filter('fluent_cart/mollie_settings', function ($settings) {
1195
+ // Override Mollie payment mode to test in staging
1196
+ if (wp_get_environment_type() === 'staging') {
1197
+ $settings['payment_mode'] = 'test';
1198
+ }
1199
+ return $settings;
1200
+ }, 10, 1);
1201
+ ```
1202
+
1203
+ ---
1204
+
1205
+ ### `payments/mollie_payment_args` (Pro)
1206
+ `fluent_cart/payments/mollie_payment_args` — Filter Mollie payment data
1207
+
1208
+ * **When it runs:** Applied when building the payment data array before sending to the Mollie API for payment creation.
1209
+ * **Source:** `fluent-cart-pro/app/Modules/PaymentMethods/MollieGateway/MollieProcessor.php` (line 142)
1210
+
1211
+ #### Parameters:
1212
+ * `$paymentData` *(array)* — Payment data array for Mollie API
1213
+ * `$context` *(array)* — Context data (`['order' => Order, 'transaction' => Transaction]`)
1214
+ * **Returns:** *(array)* — The modified payment data
1215
+
1216
+ #### Usage Example:
1217
+ ```php
1218
+ // Filter Mollie payment API creation payload data (Pro)
1219
+ add_filter('fluent_cart/payments/mollie_payment_args', function ($paymentData, $context) {
1220
+ // Inject custom description into Mollie payment creation payload
1221
+ $paymentData['description'] = 'Order #' . $context['order']->id . ' - My Store';
1222
+ return $paymentData;
1223
+ }, 10, 2);
1224
+ ```
1225
+
1226
+ ---
1227
+
1228
+ ### `mollie/pass_line_items_details` (Pro)
1229
+ `fluent_cart/mollie/pass_line_items_details` — Control passing line item details to Mollie
1230
+
1231
+ * **When it runs:** Applied before building the Mollie payment request. Return true to include line items (useful for Klarna, iDEAL).
1232
+ * **Source:** `fluent-cart-pro/app/Modules/PaymentMethods/MollieGateway/MollieProcessor.php` (line 128)
1233
+
1234
+ #### Parameters:
1235
+ * `$passLineItems` *(bool)* — Whether to include line items (default: `false`)
1236
+ * `$context` *(array)* — Array containing `[$order, $transaction]`
1237
+ * **Returns:** *(bool)* — Whether to pass line item details to Mollie
1238
+
1239
+ #### Usage Example:
1240
+ ```php
1241
+ // Control whether line item details are passed to Mollie API (Pro)
1242
+ add_filter('fluent_cart/mollie/pass_line_items_details', function ($passLineItems, $context) {
1243
+ // Enable line item details for Klarna payment support
1244
+ return true;
1245
+ }, 10, 2);
1246
+ ```
1247
+
1248
+ ---
1249
+
1250
+ ### `mollie/webhook_url` (Pro)
1251
+ `fluent_cart/mollie/webhook_url` — Filter the Mollie webhook URL
1252
+
1253
+ * **When it runs:** Applied when generating the webhook notification URL sent to Mollie during payment creation.
1254
+ * **Source:** `fluent-cart-pro/app/Modules/PaymentMethods/MollieGateway/MollieProcessor.php` (line 301)
1255
+
1256
+ #### Parameters:
1257
+ * `$webhookUrl` *(string)* — The IPN/webhook listener URL
1258
+ * **Returns:** *(string)* — The modified webhook URL
1259
+
1260
+ #### Usage Example:
1261
+ ```php
1262
+ // Filter Mollie IPN webhook notification URL (Pro)
1263
+ add_filter('fluent_cart/mollie/webhook_url', function ($webhookUrl) {
1264
+ // Use ngrok tunnel URL for local development webhook testing
1265
+ if (wp_get_environment_type() === 'local') {
1266
+ return 'https://my-tunnel.ngrok.io/?fct_payment_listener=1&method=mollie';
1267
+ }
1268
+ return $webhookUrl;
1269
+ }, 10, 1);
1270
+ ```
1271
+
1272
+ ---
1273
+
1274
+ ### `mollie/subscription_description` (Pro)
1275
+ `fluent_cart/mollie/subscription_description` — Filter Mollie subscription description
1276
+
1277
+ * **When it runs:** Applied when creating a Mollie subscription to customize statement description string.
1278
+ * **Source:** `fluent-cart-pro/app/Modules/PaymentMethods/MollieGateway/MollieHelper.php` (line 209)
1279
+
1280
+ #### Parameters:
1281
+ * `$description` *(string)* — The generated subscription description string
1282
+ * `$context` *(array)* — Context data (`['subscription_model' => Subscription, 'currency' => 'EUR']`)
1283
+ * **Returns:** *(string)* — The modified subscription description
1284
+
1285
+ #### Usage Example:
1286
+ ```php
1287
+ // Filter Mollie subscription description string (Pro)
1288
+ add_filter('fluent_cart/mollie/subscription_description', function ($description, $context) {
1289
+ // Customize Mollie subscription statement description string
1290
+ return 'MyStore - ' . $context['subscription_model']->item_name;
1291
+ }, 10, 2);
1292
+ ```
1293
+
1294
+ ---
1295
+
1296
+ ## Paddle (Pro)
1297
+
1298
+ ### `paddle_product_tax_category` (Pro)
1299
+ `fluent_cart/paddle_product_tax_category` — Filter Paddle product tax category
1300
+
1301
+ * **When it runs:** Applied when FluentCart creates the corresponding product on Paddle to determine the tax category (`standard`, `digital-goods`, `saas`).
1302
+ * **Source:** `fluent-cart-pro/app/Modules/PaymentMethods/PaddleGateway/Product.php` (line 44)
1303
+
1304
+ #### Parameters:
1305
+ * `$taxCategory` *(string)* — The tax category (default: `'standard'`)
1306
+ * `$data` *(array)* — Context data (`['product' => Product, 'variation_id' => int|null]`)
1307
+ * **Returns:** *(string)* — The Paddle tax category
1308
+
1309
+ #### Usage Example:
1310
+ ```php
1311
+ // Filter Paddle product tax category string (Pro)
1312
+ add_filter('fluent_cart/paddle_product_tax_category', function ($taxCategory, $data) {
1313
+ // Set tax category to saas for digital software products
1314
+ if ($data['product'] && $data['product']->type === 'digital') {
1315
+ return 'saas';
1316
+ }
1317
+ return $taxCategory;
1318
+ }, 10, 2);
1319
+ ```