fluentcart-developer 2.3.0 → 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 (49) hide show
  1. package/README.md +59 -59
  2. package/dist/cards/fluentcart/tools.d.ts.map +1 -1
  3. package/dist/cards/fluentcart/tools.js +2301 -2161
  4. package/dist/cards/fluentcart/tools.js.map +1 -1
  5. package/dist/skills/fluentcart-developer/.claude-plugin/plugin.json +12 -12
  6. package/dist/skills/fluentcart-developer/.mcp.json +11 -11
  7. package/dist/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/fluent-cart/checkout.php +32 -32
  8. package/dist/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/functions.php +40 -40
  9. package/dist/skills/fluentcart-developer/examples/sample-fee-surcharge-plugin/fluentcart-fee-surcharge.php +38 -38
  10. package/dist/skills/fluentcart-developer/references/action-hooks-cart-checkout.md +1355 -1355
  11. package/dist/skills/fluentcart-developer/references/action-hooks-customers-users.md +266 -266
  12. package/dist/skills/fluentcart-developer/references/action-hooks-licenses.md +855 -855
  13. package/dist/skills/fluentcart-developer/references/action-hooks-orders.md +631 -631
  14. package/dist/skills/fluentcart-developer/references/action-hooks-payments-integrations.md +963 -963
  15. package/dist/skills/fluentcart-developer/references/action-hooks-products-coupons.md +585 -585
  16. package/dist/skills/fluentcart-developer/references/action-hooks-subscriptions.md +661 -661
  17. package/dist/skills/fluentcart-developer/references/database-models-query-builder.md +194 -194
  18. package/dist/skills/fluentcart-developer/references/database-models-reference.md +604 -604
  19. package/dist/skills/fluentcart-developer/references/engineering-notes.md +154 -154
  20. package/dist/skills/fluentcart-developer/references/fee-system-guide.md +449 -449
  21. package/dist/skills/fluentcart-developer/references/filter-hooks-cart-checkout.md +1202 -1202
  22. package/dist/skills/fluentcart-developer/references/filter-hooks-integrations-advanced.md +1598 -1598
  23. package/dist/skills/fluentcart-developer/references/filter-hooks-products-pricing.md +628 -628
  24. package/dist/skills/fluentcart-developer/references/filter-hooks-settings-configuration.md +1177 -1177
  25. package/dist/skills/fluentcart-developer/references/fluentcart-developer-guide.md +154 -154
  26. package/dist/skills/fluentcart-developer/references/ghost-product-selling.md +458 -458
  27. package/dist/skills/fluentcart-developer/references/modules-and-extensions-reference.md +224 -224
  28. package/dist/skills/fluentcart-developer/references/payment-gateway-integration.md +761 -761
  29. package/dist/skills/fluentcart-developer/references/rest-api-customer-profile.md +190 -190
  30. package/dist/skills/fluentcart-developer/references/rest-api-customers.md +1121 -1121
  31. package/dist/skills/fluentcart-developer/references/rest-api-dashboard-utilities.md +219 -219
  32. package/dist/skills/fluentcart-developer/references/rest-api-email-notifications.md +619 -619
  33. package/dist/skills/fluentcart-developer/references/rest-api-files.md +290 -290
  34. package/dist/skills/fluentcart-developer/references/rest-api-integrations.md +324 -324
  35. package/dist/skills/fluentcart-developer/references/rest-api-labels-attributes.md +321 -321
  36. package/dist/skills/fluentcart-developer/references/rest-api-order-bumps.md +200 -200
  37. package/dist/skills/fluentcart-developer/references/rest-api-overview.md +131 -131
  38. package/dist/skills/fluentcart-developer/references/rest-api-public-shop.md +172 -172
  39. package/dist/skills/fluentcart-developer/references/rest-api-reference.md +552 -552
  40. package/dist/skills/fluentcart-developer/references/rest-api-reports.md +377 -377
  41. package/dist/skills/fluentcart-developer/references/rest-api-roles-permissions.md +147 -147
  42. package/dist/skills/fluentcart-developer/references/rest-api-settings.md +528 -528
  43. package/dist/skills/fluentcart-developer/references/rest-api-shipping.md +799 -799
  44. package/dist/skills/fluentcart-developer/references/rest-api-tax.md +356 -356
  45. package/dist/skills/fluentcart-developer/references/subscription-customization.md +197 -197
  46. package/dist/skills/fluentcart-developer/scripts/cli.js +1 -1
  47. package/dist/version.d.ts +1 -1
  48. package/dist/version.js +1 -1
  49. package/package.json +65 -65
@@ -1,585 +1,585 @@
1
- # Action Hooks: Products & Coupons
2
-
3
- Action hooks for Product lifecycle management, single product page rendering, product card display, and admin Coupon operations.
4
-
5
- ---
6
-
7
- ## Product Lifecycle
8
- Hooks that fire during product create/update/duplicate operations in the admin.
9
-
10
- ### `product_duplicated`
11
- `fluent_cart/product_duplicated` — Fired after a product is duplicated
12
-
13
- * **When it runs:** This action fires after a Product has been fully duplicated, including all variants, taxonomy terms, and post meta. The database transaction has already been committed when this hook runs.
14
- * **Source:** `app/Models/Product.php`
15
-
16
- #### Parameters:
17
- `$data` *(array)*: Duplication result data
18
- ```php
19
- $data = [
20
- 'original_product_id' => 123, // int — The source product's post ID
21
- 'new_product_id' => 456, // int — The newly created product's post ID
22
- 'options' => [
23
- 'import_stock_management' => true, // bool — Whether stock settings were copied
24
- 'import_license_settings' => true, // bool — Whether license settings were copied
25
- 'import_downloadable_files' => false, // bool — Whether downloadable files were copied
26
- ],
27
- ];
28
- ```
29
-
30
- #### Usage Example:
31
- ```php
32
- // Hook after a product is duplicated in admin
33
- add_action('fluent_cart/product_duplicated', function($data) {
34
- // Extract original and new product post IDs
35
- $originalId = $data['original_product_id'];
36
- $newId = $data['new_product_id'];
37
-
38
- // Copy custom post meta that core duplication doesn't handle
39
- $custom = get_post_meta($originalId, '_my_custom_field', true);
40
- if ($custom) {
41
- update_post_meta($newId, '_my_custom_field', $custom);
42
- }
43
- }, 10, 1);
44
- ```
45
-
46
- ---
47
-
48
- ### `product_updated`
49
- `fluent_cart/product_updated` — Fired when a product is updated via the admin API
50
-
51
- * **When it runs:** This action fires after a product has been successfully updated through the admin REST API (`ProductController`). It runs after `ProductResource::update()` has persisted all changes, including variants and product details.
52
- * **Source:** `app/Http/Controllers/ProductController.php`
53
-
54
- #### Parameters:
55
- `$data` *(array)*: Contains the raw request data and the updated Product model
56
- ```php
57
- $data = [
58
- 'data' => [ // array — Sanitized request payload
59
- 'title' => 'Product Name',
60
- 'detail' => [
61
- 'variation_type' => 'simple',
62
- // ... other product detail fields
63
- ],
64
- 'variants' => [
65
- // ... variant data
66
- ],
67
- ],
68
- 'product' => $product, // \FluentCart\App\Models\Product — The updated Product instance
69
- ];
70
- ```
71
-
72
- #### Usage Example:
73
- ```php
74
- // Hook when a product is updated via the admin API
75
- add_action('fluent_cart/product_updated', function($data) {
76
- // Extract updated Product model instance
77
- $product = $data['product'];
78
-
79
- // Sync product data to an external inventory system
80
- do_action('my_plugin/sync_inventory', [
81
- 'product_id' => $product->ID,
82
- 'title' => $product->post_title,
83
- ]);
84
-
85
- // Clear cached product data from object cache
86
- wp_cache_delete('fct_product_' . $product->ID, 'fluent_cart');
87
- }, 10, 1);
88
- ```
89
-
90
- ---
91
-
92
- ## Single Product Page Rendering
93
- Hooks that fire during the server-side rendering of a single product page. All rendering hooks use output buffering -- your callback should `echo` HTML directly rather than return a value.
94
-
95
- ### `render_product_header`
96
- `fluent_cart/product/render_product_header` — Before the single product page content
97
-
98
- * **When it runs:** This action fires at the very top of a single product page, before the main post content is rendered. Output is captured via `ob_start()` / `ob_get_clean()` and prepended to the product content.
99
- * **Source:** `app/Modules/Templating/TemplateActions.php`
100
-
101
- #### Parameters:
102
- * `$postId` *(int)*: The product's WordPress post ID
103
-
104
- #### Usage Example:
105
- ```php
106
- // Hook before single product page content is rendered
107
- add_action('fluent_cart/product/render_product_header', function($postId) {
108
- // Render custom promotional banner HTML above product content
109
- echo '<div class="my-promo-banner">Free shipping on this item!</div>';
110
- }, 10, 1);
111
- ```
112
-
113
- ---
114
-
115
- ### `after_product_content`
116
- `fluent_cart/product/after_product_content` — After the single product page content
117
-
118
- * **When it runs:** This action fires immediately after the main product content on a single product page. Output is captured via `ob_start()` / `ob_get_clean()` and appended to the product content.
119
- * **Source:** `app/Modules/Templating/TemplateActions.php`
120
-
121
- #### Parameters:
122
- * `$postId` *(int)*: The product's WordPress post ID
123
-
124
- #### Usage Example:
125
- ```php
126
- // Hook after single product page content is rendered
127
- add_action('fluent_cart/product/after_product_content', function($postId) {
128
- // Render trust badges section below product content
129
- echo '<div class="trust-badges">';
130
- echo '<span>30-day money back guarantee</span>';
131
- echo '</div>';
132
- }, 10, 1);
133
- ```
134
-
135
- ---
136
-
137
- ### `product_archive`
138
- `fluent_cart/template/product_archive` — Render the product archive/taxonomy page
139
-
140
- * **When it runs:** This action fires when a product taxonomy archive page (category, tag, etc.) is being rendered. It is triggered inside `renderMainContent()` when the current page is a taxonomy page for `fluent-products`.
141
- * **Parameters:** None.
142
- * **Source:** `app/Modules/Templating/TemplateActions.php`
143
-
144
- #### Usage Example:
145
- ```php
146
- // Hook to render custom product archive or taxonomy page
147
- add_action('fluent_cart/template/product_archive', function() {
148
- // Render custom product archive wrapper and layout
149
- echo '<div class="my-custom-archive">';
150
- echo '</div>';
151
- }, 10, 0);
152
- ```
153
-
154
- ---
155
-
156
- ### `before_price_block`
157
- `fluent_cart/product/single/before_price_block` — Before the price block on a single product page
158
-
159
- * **When it runs:** This action fires immediately before the price wrapper `<div>` is rendered on a single product page. It fires in two contexts: once for simple products showing a single price, and once for multi-variant products showing the selected variant's price.
160
- * **Source:** `app/Services/Renderer/ProductRenderer.php`
161
-
162
- #### Parameters:
163
- `$data` *(array)*: Price block context
164
- ```php
165
- $data = [
166
- 'product' => $product, // \FluentCart\App\Models\Product — The current product
167
- 'current_price' => 5000, // int — Price in cents
168
- 'scope' => 'price_range', // string — 'price_range' for simple products, 'product_variant_price' for variant pricing
169
- ];
170
- ```
171
-
172
- #### Usage Example:
173
- ```php
174
- // Hook before price block wrapper on single product page
175
- add_action('fluent_cart/product/single/before_price_block', function($data) {
176
- // Render price label if scope is price_range
177
- if ($data['scope'] === 'price_range') {
178
- echo '<div class="price-label">Our Price:</div>';
179
- }
180
- }, 10, 1);
181
- ```
182
-
183
- ---
184
-
185
- ### `after_price` (single & card)
186
- `fluent_cart/product/after_price` — Inline after the price is rendered
187
-
188
- * **When it runs:** This action fires inline immediately after a price value is echoed, while still inside the price `<span>` or `<div>`. It fires in multiple contexts: simple product prices, price ranges, individual variant prices, and product cards. Use the `scope` key to distinguish between contexts.
189
- * **Source:** `app/Services/Renderer/ProductRenderer.php`, `app/Services/Renderer/ProductCardRender.php`
190
-
191
- #### Parameters:
192
- `$data` *(array)*: Price context
193
- ```php
194
- $data = [
195
- 'product' => $product, // \FluentCart\App\Models\Product — The current product
196
- 'current_price' => 5000, // int — Price in cents
197
- 'scope' => 'price_range', // string — 'price_range', 'product_variant_price', or 'product_card'
198
- ];
199
- ```
200
-
201
- #### Usage Example:
202
- ```php
203
- // Hook inline after price value is rendered
204
- add_action('fluent_cart/product/after_price', function($data) {
205
- // Display per-unit label next to variant price
206
- if ($data['scope'] === 'product_variant_price') {
207
- echo '<span class="per-unit"> / unit</span>';
208
- }
209
-
210
- // Display sale badge on archive product cards
211
- if ($data['scope'] === 'product_card') {
212
- echo '<span class="sale-badge">Sale</span>';
213
- }
214
- }, 10, 1);
215
- ```
216
-
217
- ---
218
-
219
- ### `after_price_block`
220
- `fluent_cart/product/single/after_price_block` — After the price block wrapper closes on a single product page
221
-
222
- * **When it runs:** This action fires immediately after the closing `</div>` of the price block on a single product page. Like `before_price_block`, it fires in two contexts: simple product pricing and variant pricing.
223
- * **Source:** `app/Services/Renderer/ProductRenderer.php`
224
-
225
- #### Parameters:
226
- `$data` *(array)*: Price block context (same structure as `before_price_block`)
227
-
228
- #### Usage Example:
229
- ```php
230
- // Hook after price block wrapper closes on single product page
231
- add_action('fluent_cart/product/single/after_price_block', function($data) {
232
- // Calculate and display monthly installment pricing note
233
- $monthly = \FluentCart\App\Helpers\Helper::toDecimal(intval($data['current_price'] / 3));
234
- echo '<p class="installment-info">Or 3 payments of ' . esc_html($monthly) . '</p>';
235
- }, 10, 1);
236
- ```
237
-
238
- ---
239
-
240
- ### `before_price_range_block`
241
- `fluent_cart/product/single/before_price_range_block` — Before the price range block for multi-variant products
242
-
243
- * **When it runs:** This action fires before the min-max price range `<div>` is rendered on multi-variant products (products with more than one variant that show a "from X - Y" price range). It does not fire for simple products.
244
- * **Source:** `app/Services/Renderer/ProductRenderer.php`
245
-
246
- #### Parameters:
247
- `$data` *(array)*: Price range context
248
- ```php
249
- $data = [
250
- 'product' => $product, // \FluentCart\App\Models\Product — The current product
251
- 'current_price' => 2000, // int — Minimum price in cents
252
- 'scope' => 'price_range',
253
- ];
254
- ```
255
-
256
- #### Usage Example:
257
- ```php
258
- // Hook before price range block on multi-variant products
259
- add_action('fluent_cart/product/single/before_price_range_block', function($data) {
260
- // Render intro note above price range
261
- echo '<div class="pricing-note">Choose a plan below:</div>';
262
- }, 10, 1);
263
- ```
264
-
265
- ---
266
-
267
- ### `after_price_range_block`
268
- `fluent_cart/product/single/after_price_range_block` — After the price range block for multi-variant products
269
-
270
- * **When it runs:** This action fires after the closing `</div>` of the min-max price range block on multi-variant products. It does not fire for simple products.
271
- * **Source:** `app/Services/Renderer/ProductRenderer.php`
272
-
273
- #### Parameters:
274
- `$data` *(array)*: Price range context (same structure as `before_price_range_block`)
275
-
276
- #### Usage Example:
277
- ```php
278
- // Hook after price range block on multi-variant products
279
- add_action('fluent_cart/product/single/after_price_range_block', function($data) {
280
- // Render bulk discount notice below price range
281
- echo '<p class="bulk-discount">Bulk discounts available for 10+ licenses.</p>';
282
- }, 10, 1);
283
- ```
284
-
285
- ---
286
-
287
- ### `before_variant_item`
288
- `fluent_cart/product/single/before_variant_item` — Before each variant item in the variant list
289
-
290
- * **When it runs:** This action fires before each individual `ProductVariation` option is rendered in the variant selection list. It fires once per variant, inside the `foreach` loop that iterates over sorted variants. It fires in both the standard variant list and the tabbed (subscription/onetime) variant layout.
291
- * **Source:** `app/Services/Renderer/ProductRenderer.php`
292
-
293
- #### Parameters:
294
- `$data` *(array)*: Variant item context
295
- ```php
296
- $data = [
297
- 'product' => $product, // \FluentCart\App\Models\Product — The current product
298
- 'variant' => $variant, // \FluentCart\App\Models\ProductVariation — The current variant being rendered
299
- 'scope' => 'product_variant_item',
300
- ];
301
- ```
302
-
303
- #### Usage Example:
304
- ```php
305
- // Hook before each variant option in variant selection list
306
- add_action('fluent_cart/product/single/before_variant_item', function($data) {
307
- // Extract variant model instance from event data
308
- $variant = $data['variant'];
309
-
310
- // Render a "Most Popular" badge for target variant ID
311
- if ($variant->id === 42) {
312
- echo '<div class="popular-badge">Most Popular</div>';
313
- }
314
- }, 10, 1);
315
- ```
316
-
317
- ---
318
-
319
- ### `after_variant_item`
320
- `fluent_cart/product/single/after_variant_item` — After each variant item in the variant list
321
-
322
- * **When it runs:** This action fires after each individual variant option is rendered in the variant selection list. It fires once per variant, immediately after `renderVariationItem()` completes. It fires in both the standard variant list and the tabbed variant layout.
323
- * **Source:** `app/Services/Renderer/ProductRenderer.php`
324
-
325
- #### Parameters:
326
- `$data` *(array)*: Variant item context (same structure as `before_variant_item`)
327
-
328
- #### Usage Example:
329
- ```php
330
- // Hook after each variant option in variant selection list
331
- add_action('fluent_cart/product/single/after_variant_item', function($data) {
332
- // Extract variant model instance from event data
333
- $variant = $data['variant'];
334
-
335
- // Display low stock warning if quantity is low
336
- if ($variant->stock_quantity > 0 && $variant->stock_quantity < 10) {
337
- echo '<span class="low-stock">Only ' . esc_html($variant->stock_quantity) . ' left!</span>';
338
- }
339
- }, 10, 1);
340
- ```
341
-
342
- ---
343
-
344
- ### `before_quantity_block`
345
- `fluent_cart/product/single/before_quantity_block` — Before the quantity selector on a single product page
346
-
347
- * **When it runs:** This action fires immediately before the quantity input container is rendered on a single product page. It only fires if the product allows quantity selection (not hidden by sold-individually or other conditions).
348
- * **Source:** `app/Services/Renderer/ProductRenderer.php`
349
-
350
- #### Parameters:
351
- `$data` *(array)*: Quantity block context
352
- ```php
353
- $data = [
354
- 'product' => $product, // \FluentCart\App\Models\Product — The current product
355
- 'scope' => 'product_quantity_block',
356
- ];
357
- ```
358
-
359
- #### Usage Example:
360
- ```php
361
- // Hook before quantity selector container on single product page
362
- add_action('fluent_cart/product/single/before_quantity_block', function($data) {
363
- // Render quantity selection guidance note
364
- echo '<p class="quantity-hint">Select your desired quantity:</p>';
365
- }, 10, 1);
366
- ```
367
-
368
- ---
369
-
370
- ### `after_quantity_block`
371
- `fluent_cart/product/single/after_quantity_block` — After the quantity selector on a single product page
372
-
373
- * **When it runs:** This action fires immediately after the quantity input container is rendered on a single product page, after the closing `</div>` of the quantity wrapper.
374
- * **Source:** `app/Services/Renderer/ProductRenderer.php`
375
-
376
- #### Parameters:
377
- `$data` *(array)*: Quantity block context (same structure as `before_quantity_block`)
378
-
379
- #### Usage Example:
380
- ```php
381
- // Hook after quantity selector container on single product page
382
- add_action('fluent_cart/product/single/after_quantity_block', function($data) {
383
- // Display bulk pricing table after quantity input wrapper
384
- echo '<div class="bulk-pricing">';
385
- echo '<small>Buy 5+ and save 10% &bull; Buy 10+ and save 20%</small>';
386
- echo '</div>';
387
- }, 10, 1);
388
- ```
389
-
390
- ---
391
-
392
- ## Product Card Rendering (Archive / Group Pages)
393
- Hooks that fire during server-side rendering of product cards on archive pages, product group blocks, and shop listings. All rendering hooks use output buffering -- your callback should `echo` HTML directly.
394
-
395
- ### `group/before_image_block`
396
- `fluent_cart/product/group/before_image_block` — Before the product card image
397
-
398
- * **When it runs:** This action fires before the product card image link and `<img>` tag are rendered inside a product card on archive or group pages.
399
- * **Source:** `app/Services/Renderer/ProductCardRender.php`
400
-
401
- #### Parameters:
402
- `$data` *(array)*: Product card context
403
- ```php
404
- $data = [
405
- 'product' => $product, // \FluentCart\App\Models\Product — The current product
406
- 'scope' => 'product_card',
407
- ];
408
- ```
409
-
410
- #### Usage Example:
411
- ```php
412
- // Hook before product card image link on archive/group pages
413
- add_action('fluent_cart/product/group/before_image_block', function($data) {
414
- // Extract product model instance
415
- $product = $data['product'];
416
- $created = strtotime($product->post_date);
417
-
418
- // Render "New" ribbon badge if created within last 30 days
419
- if ($created > strtotime('-30 days')) {
420
- echo '<span class="new-ribbon">New</span>';
421
- }
422
- }, 10, 1);
423
- ```
424
-
425
- ---
426
-
427
- ### `group/after_image_block`
428
- `fluent_cart/product/group/after_image_block` — After the product card image
429
-
430
- * **When it runs:** This action fires immediately after the product card image link closes, before the rest of the card content (title, price, button) is rendered.
431
- * **Source:** `app/Services/Renderer/ProductCardRender.php`
432
-
433
- #### Parameters:
434
- `$data` *(array)*: Product card context (same structure as `group/before_image_block`)
435
-
436
- #### Usage Example:
437
- ```php
438
- // Hook after product card image link on archive/group pages
439
- add_action('fluent_cart/product/group/after_image_block', function($data) {
440
- // Render quick-view button overlay after image
441
- echo '<button class="quick-view-btn" data-product="' . esc_attr($data['product']->ID) . '">Quick View</button>';
442
- }, 10, 1);
443
- ```
444
-
445
- ---
446
-
447
- ### `group/before_price_block`
448
- `fluent_cart/product/group/before_price_block` — Before the price section in product cards
449
-
450
- * **When it runs:** This action fires before the price wrapper `<div class="fct-product-card-prices">` is rendered inside a product card on archive or group pages.
451
- * **Source:** `app/Services/Renderer/ProductCardRender.php`
452
-
453
- #### Parameters:
454
- `$data` *(array)*: Product card price context
455
- ```php
456
- $data = [
457
- 'product' => $product, // \FluentCart\App\Models\Product — The current product
458
- 'current_price' => 2000, // int — Minimum price in cents
459
- 'scope' => 'product_card',
460
- ];
461
- ```
462
-
463
- #### Usage Example:
464
- ```php
465
- // Hook before price section in product card
466
- add_action('fluent_cart/product/group/before_price_block', function($data) {
467
- // Render price prefix label on product card
468
- echo '<span class="price-prefix">Starting at</span>';
469
- }, 10, 1);
470
- ```
471
-
472
- ---
473
-
474
- ### `group/after_price_block`
475
- `fluent_cart/product/group/after_price_block` — After the price section in product cards
476
-
477
- * **When it runs:** This action fires immediately after the closing `</div>` of the product card price wrapper, after prices and the inline `fluent_cart/product/after_price` hook have been rendered.
478
- * **Source:** `app/Services/Renderer/ProductCardRender.php`
479
-
480
- #### Parameters:
481
- `$data` *(array)*: Product card price context (same structure as `group/before_price_block`)
482
-
483
- #### Usage Example:
484
- ```php
485
- // Hook after price section in product card
486
- add_action('fluent_cart/product/group/after_price_block', function($data) {
487
- // Display custom feature list meta below price on product card
488
- $features = get_post_meta($data['product']->ID, '_card_features', true);
489
- if ($features) {
490
- echo '<ul class="card-features">';
491
- foreach ((array) $features as $feature) {
492
- echo '<li>' . esc_html($feature) . '</li>';
493
- }
494
- echo '</ul>';
495
- }
496
- }, 10, 1);
497
- ```
498
-
499
- ---
500
-
501
- ## Coupons
502
- Hooks that fire during Coupon create and update operations in the admin.
503
-
504
- ### `coupon_created`
505
- `fluent_cart/coupon_created` — Fired after a new coupon is created via the admin
506
-
507
- * **When it runs:** This action fires after a Coupon has been successfully created through the admin REST API. It runs after `CouponResource::create()` has persisted the coupon and after the activity log entry has been recorded.
508
- * **Source:** `app/Http/Controllers/CouponsController.php`
509
-
510
- #### Parameters:
511
- `$data` *(array)*: Coupon creation data
512
- ```php
513
- $data = [
514
- 'data' => [ // array — Sanitized request payload
515
- 'title' => 'SAVE20',
516
- 'type' => 'percentage', // 'percentage' or 'fixed'
517
- 'amount' => 2000, // int — Discount amount in cents (or percentage value)
518
- 'start_date' => '2026-01-01 00:00:00', // string|null — GMT start date
519
- 'end_date' => '2026-12-31 23:59:59', // string|null — GMT end date
520
- 'conditions' => [
521
- 'is_recurring' => 'no',
522
- // ... other condition fields
523
- ],
524
- ],
525
- 'coupon' => $coupon, // \FluentCart\App\Models\Coupon — The newly created Coupon instance
526
- ];
527
- ```
528
-
529
- #### Usage Example:
530
- ```php
531
- // Hook after a new coupon is created via admin REST API
532
- add_action('fluent_cart/coupon_created', function($data) {
533
- // Extract newly created Coupon model instance
534
- $coupon = $data['coupon'];
535
-
536
- // Notify marketing team via email about new coupon
537
- wp_mail(
538
- 'marketing@example.com',
539
- 'New Coupon Created: ' . $coupon->title,
540
- 'A new coupon has been created with code: ' . $coupon->title
541
- );
542
- }, 10, 1);
543
- ```
544
-
545
- ---
546
-
547
- ### `coupon_updated`
548
- `fluent_cart/coupon_updated` — Fired after a coupon is updated via the admin
549
-
550
- * **When it runs:** This action fires after a Coupon has been successfully updated through the admin REST API. It runs after `CouponResource::update()` has persisted the changes, but before the activity log entry is recorded.
551
- * **Source:** `app/Http/Controllers/CouponsController.php`
552
-
553
- #### Parameters:
554
- `$data` *(array)*: Coupon update data
555
- ```php
556
- $data = [
557
- 'data' => [ // array — Sanitized request payload
558
- 'title' => 'SAVE20',
559
- 'type' => 'percentage',
560
- 'amount' => 2500,
561
- 'start_date' => '2026-01-01 00:00:00',
562
- 'end_date' => '2026-12-31 23:59:59',
563
- 'conditions' => [
564
- 'is_recurring' => 'no',
565
- // ... other condition fields
566
- ],
567
- ],
568
- 'coupon' => $coupon, // \FluentCart\App\Models\Coupon — The updated Coupon instance
569
- ];
570
- ```
571
-
572
- #### Usage Example:
573
- ```php
574
- // Hook after a coupon is updated via admin REST API
575
- add_action('fluent_cart/coupon_updated', function($data) {
576
- // Extract updated Coupon model instance
577
- $coupon = $data['coupon'];
578
-
579
- // Clear coupon validation cache when a coupon is modified
580
- wp_cache_delete('fct_coupon_' . $coupon->id, 'fluent_cart');
581
-
582
- // Sync updated coupon to external promotion platform
583
- do_action('my_plugin/sync_coupon', $coupon);
584
- }, 10, 1);
585
- ```
1
+ # Action Hooks: Products & Coupons
2
+
3
+ Action hooks for Product lifecycle management, single product page rendering, product card display, and admin Coupon operations.
4
+
5
+ ---
6
+
7
+ ## Product Lifecycle
8
+ Hooks that fire during product create/update/duplicate operations in the admin.
9
+
10
+ ### `product_duplicated`
11
+ `fluent_cart/product_duplicated` — Fired after a product is duplicated
12
+
13
+ * **When it runs:** This action fires after a Product has been fully duplicated, including all variants, taxonomy terms, and post meta. The database transaction has already been committed when this hook runs.
14
+ * **Source:** `app/Models/Product.php`
15
+
16
+ #### Parameters:
17
+ `$data` *(array)*: Duplication result data
18
+ ```php
19
+ $data = [
20
+ 'original_product_id' => 123, // int — The source product's post ID
21
+ 'new_product_id' => 456, // int — The newly created product's post ID
22
+ 'options' => [
23
+ 'import_stock_management' => true, // bool — Whether stock settings were copied
24
+ 'import_license_settings' => true, // bool — Whether license settings were copied
25
+ 'import_downloadable_files' => false, // bool — Whether downloadable files were copied
26
+ ],
27
+ ];
28
+ ```
29
+
30
+ #### Usage Example:
31
+ ```php
32
+ // Hook after a product is duplicated in admin
33
+ add_action('fluent_cart/product_duplicated', function($data) {
34
+ // Extract original and new product post IDs
35
+ $originalId = $data['original_product_id'];
36
+ $newId = $data['new_product_id'];
37
+
38
+ // Copy custom post meta that core duplication doesn't handle
39
+ $custom = get_post_meta($originalId, '_my_custom_field', true);
40
+ if ($custom) {
41
+ update_post_meta($newId, '_my_custom_field', $custom);
42
+ }
43
+ }, 10, 1);
44
+ ```
45
+
46
+ ---
47
+
48
+ ### `product_updated`
49
+ `fluent_cart/product_updated` — Fired when a product is updated via the admin API
50
+
51
+ * **When it runs:** This action fires after a product has been successfully updated through the admin REST API (`ProductController`). It runs after `ProductResource::update()` has persisted all changes, including variants and product details.
52
+ * **Source:** `app/Http/Controllers/ProductController.php`
53
+
54
+ #### Parameters:
55
+ `$data` *(array)*: Contains the raw request data and the updated Product model
56
+ ```php
57
+ $data = [
58
+ 'data' => [ // array — Sanitized request payload
59
+ 'title' => 'Product Name',
60
+ 'detail' => [
61
+ 'variation_type' => 'simple',
62
+ // ... other product detail fields
63
+ ],
64
+ 'variants' => [
65
+ // ... variant data
66
+ ],
67
+ ],
68
+ 'product' => $product, // \FluentCart\App\Models\Product — The updated Product instance
69
+ ];
70
+ ```
71
+
72
+ #### Usage Example:
73
+ ```php
74
+ // Hook when a product is updated via the admin API
75
+ add_action('fluent_cart/product_updated', function($data) {
76
+ // Extract updated Product model instance
77
+ $product = $data['product'];
78
+
79
+ // Sync product data to an external inventory system
80
+ do_action('my_plugin/sync_inventory', [
81
+ 'product_id' => $product->ID,
82
+ 'title' => $product->post_title,
83
+ ]);
84
+
85
+ // Clear cached product data from object cache
86
+ wp_cache_delete('fct_product_' . $product->ID, 'fluent_cart');
87
+ }, 10, 1);
88
+ ```
89
+
90
+ ---
91
+
92
+ ## Single Product Page Rendering
93
+ Hooks that fire during the server-side rendering of a single product page. All rendering hooks use output buffering -- your callback should `echo` HTML directly rather than return a value.
94
+
95
+ ### `render_product_header`
96
+ `fluent_cart/product/render_product_header` — Before the single product page content
97
+
98
+ * **When it runs:** This action fires at the very top of a single product page, before the main post content is rendered. Output is captured via `ob_start()` / `ob_get_clean()` and prepended to the product content.
99
+ * **Source:** `app/Modules/Templating/TemplateActions.php`
100
+
101
+ #### Parameters:
102
+ * `$postId` *(int)*: The product's WordPress post ID
103
+
104
+ #### Usage Example:
105
+ ```php
106
+ // Hook before single product page content is rendered
107
+ add_action('fluent_cart/product/render_product_header', function($postId) {
108
+ // Render custom promotional banner HTML above product content
109
+ echo '<div class="my-promo-banner">Free shipping on this item!</div>';
110
+ }, 10, 1);
111
+ ```
112
+
113
+ ---
114
+
115
+ ### `after_product_content`
116
+ `fluent_cart/product/after_product_content` — After the single product page content
117
+
118
+ * **When it runs:** This action fires immediately after the main product content on a single product page. Output is captured via `ob_start()` / `ob_get_clean()` and appended to the product content.
119
+ * **Source:** `app/Modules/Templating/TemplateActions.php`
120
+
121
+ #### Parameters:
122
+ * `$postId` *(int)*: The product's WordPress post ID
123
+
124
+ #### Usage Example:
125
+ ```php
126
+ // Hook after single product page content is rendered
127
+ add_action('fluent_cart/product/after_product_content', function($postId) {
128
+ // Render trust badges section below product content
129
+ echo '<div class="trust-badges">';
130
+ echo '<span>30-day money back guarantee</span>';
131
+ echo '</div>';
132
+ }, 10, 1);
133
+ ```
134
+
135
+ ---
136
+
137
+ ### `product_archive`
138
+ `fluent_cart/template/product_archive` — Render the product archive/taxonomy page
139
+
140
+ * **When it runs:** This action fires when a product taxonomy archive page (category, tag, etc.) is being rendered. It is triggered inside `renderMainContent()` when the current page is a taxonomy page for `fluent-products`.
141
+ * **Parameters:** None.
142
+ * **Source:** `app/Modules/Templating/TemplateActions.php`
143
+
144
+ #### Usage Example:
145
+ ```php
146
+ // Hook to render custom product archive or taxonomy page
147
+ add_action('fluent_cart/template/product_archive', function() {
148
+ // Render custom product archive wrapper and layout
149
+ echo '<div class="my-custom-archive">';
150
+ echo '</div>';
151
+ }, 10, 0);
152
+ ```
153
+
154
+ ---
155
+
156
+ ### `before_price_block`
157
+ `fluent_cart/product/single/before_price_block` — Before the price block on a single product page
158
+
159
+ * **When it runs:** This action fires immediately before the price wrapper `<div>` is rendered on a single product page. It fires in two contexts: once for simple products showing a single price, and once for multi-variant products showing the selected variant's price.
160
+ * **Source:** `app/Services/Renderer/ProductRenderer.php`
161
+
162
+ #### Parameters:
163
+ `$data` *(array)*: Price block context
164
+ ```php
165
+ $data = [
166
+ 'product' => $product, // \FluentCart\App\Models\Product — The current product
167
+ 'current_price' => 5000, // int — Price in cents
168
+ 'scope' => 'price_range', // string — 'price_range' for simple products, 'product_variant_price' for variant pricing
169
+ ];
170
+ ```
171
+
172
+ #### Usage Example:
173
+ ```php
174
+ // Hook before price block wrapper on single product page
175
+ add_action('fluent_cart/product/single/before_price_block', function($data) {
176
+ // Render price label if scope is price_range
177
+ if ($data['scope'] === 'price_range') {
178
+ echo '<div class="price-label">Our Price:</div>';
179
+ }
180
+ }, 10, 1);
181
+ ```
182
+
183
+ ---
184
+
185
+ ### `after_price` (single & card)
186
+ `fluent_cart/product/after_price` — Inline after the price is rendered
187
+
188
+ * **When it runs:** This action fires inline immediately after a price value is echoed, while still inside the price `<span>` or `<div>`. It fires in multiple contexts: simple product prices, price ranges, individual variant prices, and product cards. Use the `scope` key to distinguish between contexts.
189
+ * **Source:** `app/Services/Renderer/ProductRenderer.php`, `app/Services/Renderer/ProductCardRender.php`
190
+
191
+ #### Parameters:
192
+ `$data` *(array)*: Price context
193
+ ```php
194
+ $data = [
195
+ 'product' => $product, // \FluentCart\App\Models\Product — The current product
196
+ 'current_price' => 5000, // int — Price in cents
197
+ 'scope' => 'price_range', // string — 'price_range', 'product_variant_price', or 'product_card'
198
+ ];
199
+ ```
200
+
201
+ #### Usage Example:
202
+ ```php
203
+ // Hook inline after price value is rendered
204
+ add_action('fluent_cart/product/after_price', function($data) {
205
+ // Display per-unit label next to variant price
206
+ if ($data['scope'] === 'product_variant_price') {
207
+ echo '<span class="per-unit"> / unit</span>';
208
+ }
209
+
210
+ // Display sale badge on archive product cards
211
+ if ($data['scope'] === 'product_card') {
212
+ echo '<span class="sale-badge">Sale</span>';
213
+ }
214
+ }, 10, 1);
215
+ ```
216
+
217
+ ---
218
+
219
+ ### `after_price_block`
220
+ `fluent_cart/product/single/after_price_block` — After the price block wrapper closes on a single product page
221
+
222
+ * **When it runs:** This action fires immediately after the closing `</div>` of the price block on a single product page. Like `before_price_block`, it fires in two contexts: simple product pricing and variant pricing.
223
+ * **Source:** `app/Services/Renderer/ProductRenderer.php`
224
+
225
+ #### Parameters:
226
+ `$data` *(array)*: Price block context (same structure as `before_price_block`)
227
+
228
+ #### Usage Example:
229
+ ```php
230
+ // Hook after price block wrapper closes on single product page
231
+ add_action('fluent_cart/product/single/after_price_block', function($data) {
232
+ // Calculate and display monthly installment pricing note
233
+ $monthly = \FluentCart\App\Helpers\Helper::toDecimal(intval($data['current_price'] / 3));
234
+ echo '<p class="installment-info">Or 3 payments of ' . esc_html($monthly) . '</p>';
235
+ }, 10, 1);
236
+ ```
237
+
238
+ ---
239
+
240
+ ### `before_price_range_block`
241
+ `fluent_cart/product/single/before_price_range_block` — Before the price range block for multi-variant products
242
+
243
+ * **When it runs:** This action fires before the min-max price range `<div>` is rendered on multi-variant products (products with more than one variant that show a "from X - Y" price range). It does not fire for simple products.
244
+ * **Source:** `app/Services/Renderer/ProductRenderer.php`
245
+
246
+ #### Parameters:
247
+ `$data` *(array)*: Price range context
248
+ ```php
249
+ $data = [
250
+ 'product' => $product, // \FluentCart\App\Models\Product — The current product
251
+ 'current_price' => 2000, // int — Minimum price in cents
252
+ 'scope' => 'price_range',
253
+ ];
254
+ ```
255
+
256
+ #### Usage Example:
257
+ ```php
258
+ // Hook before price range block on multi-variant products
259
+ add_action('fluent_cart/product/single/before_price_range_block', function($data) {
260
+ // Render intro note above price range
261
+ echo '<div class="pricing-note">Choose a plan below:</div>';
262
+ }, 10, 1);
263
+ ```
264
+
265
+ ---
266
+
267
+ ### `after_price_range_block`
268
+ `fluent_cart/product/single/after_price_range_block` — After the price range block for multi-variant products
269
+
270
+ * **When it runs:** This action fires after the closing `</div>` of the min-max price range block on multi-variant products. It does not fire for simple products.
271
+ * **Source:** `app/Services/Renderer/ProductRenderer.php`
272
+
273
+ #### Parameters:
274
+ `$data` *(array)*: Price range context (same structure as `before_price_range_block`)
275
+
276
+ #### Usage Example:
277
+ ```php
278
+ // Hook after price range block on multi-variant products
279
+ add_action('fluent_cart/product/single/after_price_range_block', function($data) {
280
+ // Render bulk discount notice below price range
281
+ echo '<p class="bulk-discount">Bulk discounts available for 10+ licenses.</p>';
282
+ }, 10, 1);
283
+ ```
284
+
285
+ ---
286
+
287
+ ### `before_variant_item`
288
+ `fluent_cart/product/single/before_variant_item` — Before each variant item in the variant list
289
+
290
+ * **When it runs:** This action fires before each individual `ProductVariation` option is rendered in the variant selection list. It fires once per variant, inside the `foreach` loop that iterates over sorted variants. It fires in both the standard variant list and the tabbed (subscription/onetime) variant layout.
291
+ * **Source:** `app/Services/Renderer/ProductRenderer.php`
292
+
293
+ #### Parameters:
294
+ `$data` *(array)*: Variant item context
295
+ ```php
296
+ $data = [
297
+ 'product' => $product, // \FluentCart\App\Models\Product — The current product
298
+ 'variant' => $variant, // \FluentCart\App\Models\ProductVariation — The current variant being rendered
299
+ 'scope' => 'product_variant_item',
300
+ ];
301
+ ```
302
+
303
+ #### Usage Example:
304
+ ```php
305
+ // Hook before each variant option in variant selection list
306
+ add_action('fluent_cart/product/single/before_variant_item', function($data) {
307
+ // Extract variant model instance from event data
308
+ $variant = $data['variant'];
309
+
310
+ // Render a "Most Popular" badge for target variant ID
311
+ if ($variant->id === 42) {
312
+ echo '<div class="popular-badge">Most Popular</div>';
313
+ }
314
+ }, 10, 1);
315
+ ```
316
+
317
+ ---
318
+
319
+ ### `after_variant_item`
320
+ `fluent_cart/product/single/after_variant_item` — After each variant item in the variant list
321
+
322
+ * **When it runs:** This action fires after each individual variant option is rendered in the variant selection list. It fires once per variant, immediately after `renderVariationItem()` completes. It fires in both the standard variant list and the tabbed variant layout.
323
+ * **Source:** `app/Services/Renderer/ProductRenderer.php`
324
+
325
+ #### Parameters:
326
+ `$data` *(array)*: Variant item context (same structure as `before_variant_item`)
327
+
328
+ #### Usage Example:
329
+ ```php
330
+ // Hook after each variant option in variant selection list
331
+ add_action('fluent_cart/product/single/after_variant_item', function($data) {
332
+ // Extract variant model instance from event data
333
+ $variant = $data['variant'];
334
+
335
+ // Display low stock warning if quantity is low
336
+ if ($variant->stock_quantity > 0 && $variant->stock_quantity < 10) {
337
+ echo '<span class="low-stock">Only ' . esc_html($variant->stock_quantity) . ' left!</span>';
338
+ }
339
+ }, 10, 1);
340
+ ```
341
+
342
+ ---
343
+
344
+ ### `before_quantity_block`
345
+ `fluent_cart/product/single/before_quantity_block` — Before the quantity selector on a single product page
346
+
347
+ * **When it runs:** This action fires immediately before the quantity input container is rendered on a single product page. It only fires if the product allows quantity selection (not hidden by sold-individually or other conditions).
348
+ * **Source:** `app/Services/Renderer/ProductRenderer.php`
349
+
350
+ #### Parameters:
351
+ `$data` *(array)*: Quantity block context
352
+ ```php
353
+ $data = [
354
+ 'product' => $product, // \FluentCart\App\Models\Product — The current product
355
+ 'scope' => 'product_quantity_block',
356
+ ];
357
+ ```
358
+
359
+ #### Usage Example:
360
+ ```php
361
+ // Hook before quantity selector container on single product page
362
+ add_action('fluent_cart/product/single/before_quantity_block', function($data) {
363
+ // Render quantity selection guidance note
364
+ echo '<p class="quantity-hint">Select your desired quantity:</p>';
365
+ }, 10, 1);
366
+ ```
367
+
368
+ ---
369
+
370
+ ### `after_quantity_block`
371
+ `fluent_cart/product/single/after_quantity_block` — After the quantity selector on a single product page
372
+
373
+ * **When it runs:** This action fires immediately after the quantity input container is rendered on a single product page, after the closing `</div>` of the quantity wrapper.
374
+ * **Source:** `app/Services/Renderer/ProductRenderer.php`
375
+
376
+ #### Parameters:
377
+ `$data` *(array)*: Quantity block context (same structure as `before_quantity_block`)
378
+
379
+ #### Usage Example:
380
+ ```php
381
+ // Hook after quantity selector container on single product page
382
+ add_action('fluent_cart/product/single/after_quantity_block', function($data) {
383
+ // Display bulk pricing table after quantity input wrapper
384
+ echo '<div class="bulk-pricing">';
385
+ echo '<small>Buy 5+ and save 10% &bull; Buy 10+ and save 20%</small>';
386
+ echo '</div>';
387
+ }, 10, 1);
388
+ ```
389
+
390
+ ---
391
+
392
+ ## Product Card Rendering (Archive / Group Pages)
393
+ Hooks that fire during server-side rendering of product cards on archive pages, product group blocks, and shop listings. All rendering hooks use output buffering -- your callback should `echo` HTML directly.
394
+
395
+ ### `group/before_image_block`
396
+ `fluent_cart/product/group/before_image_block` — Before the product card image
397
+
398
+ * **When it runs:** This action fires before the product card image link and `<img>` tag are rendered inside a product card on archive or group pages.
399
+ * **Source:** `app/Services/Renderer/ProductCardRender.php`
400
+
401
+ #### Parameters:
402
+ `$data` *(array)*: Product card context
403
+ ```php
404
+ $data = [
405
+ 'product' => $product, // \FluentCart\App\Models\Product — The current product
406
+ 'scope' => 'product_card',
407
+ ];
408
+ ```
409
+
410
+ #### Usage Example:
411
+ ```php
412
+ // Hook before product card image link on archive/group pages
413
+ add_action('fluent_cart/product/group/before_image_block', function($data) {
414
+ // Extract product model instance
415
+ $product = $data['product'];
416
+ $created = strtotime($product->post_date);
417
+
418
+ // Render "New" ribbon badge if created within last 30 days
419
+ if ($created > strtotime('-30 days')) {
420
+ echo '<span class="new-ribbon">New</span>';
421
+ }
422
+ }, 10, 1);
423
+ ```
424
+
425
+ ---
426
+
427
+ ### `group/after_image_block`
428
+ `fluent_cart/product/group/after_image_block` — After the product card image
429
+
430
+ * **When it runs:** This action fires immediately after the product card image link closes, before the rest of the card content (title, price, button) is rendered.
431
+ * **Source:** `app/Services/Renderer/ProductCardRender.php`
432
+
433
+ #### Parameters:
434
+ `$data` *(array)*: Product card context (same structure as `group/before_image_block`)
435
+
436
+ #### Usage Example:
437
+ ```php
438
+ // Hook after product card image link on archive/group pages
439
+ add_action('fluent_cart/product/group/after_image_block', function($data) {
440
+ // Render quick-view button overlay after image
441
+ echo '<button class="quick-view-btn" data-product="' . esc_attr($data['product']->ID) . '">Quick View</button>';
442
+ }, 10, 1);
443
+ ```
444
+
445
+ ---
446
+
447
+ ### `group/before_price_block`
448
+ `fluent_cart/product/group/before_price_block` — Before the price section in product cards
449
+
450
+ * **When it runs:** This action fires before the price wrapper `<div class="fct-product-card-prices">` is rendered inside a product card on archive or group pages.
451
+ * **Source:** `app/Services/Renderer/ProductCardRender.php`
452
+
453
+ #### Parameters:
454
+ `$data` *(array)*: Product card price context
455
+ ```php
456
+ $data = [
457
+ 'product' => $product, // \FluentCart\App\Models\Product — The current product
458
+ 'current_price' => 2000, // int — Minimum price in cents
459
+ 'scope' => 'product_card',
460
+ ];
461
+ ```
462
+
463
+ #### Usage Example:
464
+ ```php
465
+ // Hook before price section in product card
466
+ add_action('fluent_cart/product/group/before_price_block', function($data) {
467
+ // Render price prefix label on product card
468
+ echo '<span class="price-prefix">Starting at</span>';
469
+ }, 10, 1);
470
+ ```
471
+
472
+ ---
473
+
474
+ ### `group/after_price_block`
475
+ `fluent_cart/product/group/after_price_block` — After the price section in product cards
476
+
477
+ * **When it runs:** This action fires immediately after the closing `</div>` of the product card price wrapper, after prices and the inline `fluent_cart/product/after_price` hook have been rendered.
478
+ * **Source:** `app/Services/Renderer/ProductCardRender.php`
479
+
480
+ #### Parameters:
481
+ `$data` *(array)*: Product card price context (same structure as `group/before_price_block`)
482
+
483
+ #### Usage Example:
484
+ ```php
485
+ // Hook after price section in product card
486
+ add_action('fluent_cart/product/group/after_price_block', function($data) {
487
+ // Display custom feature list meta below price on product card
488
+ $features = get_post_meta($data['product']->ID, '_card_features', true);
489
+ if ($features) {
490
+ echo '<ul class="card-features">';
491
+ foreach ((array) $features as $feature) {
492
+ echo '<li>' . esc_html($feature) . '</li>';
493
+ }
494
+ echo '</ul>';
495
+ }
496
+ }, 10, 1);
497
+ ```
498
+
499
+ ---
500
+
501
+ ## Coupons
502
+ Hooks that fire during Coupon create and update operations in the admin.
503
+
504
+ ### `coupon_created`
505
+ `fluent_cart/coupon_created` — Fired after a new coupon is created via the admin
506
+
507
+ * **When it runs:** This action fires after a Coupon has been successfully created through the admin REST API. It runs after `CouponResource::create()` has persisted the coupon and after the activity log entry has been recorded.
508
+ * **Source:** `app/Http/Controllers/CouponsController.php`
509
+
510
+ #### Parameters:
511
+ `$data` *(array)*: Coupon creation data
512
+ ```php
513
+ $data = [
514
+ 'data' => [ // array — Sanitized request payload
515
+ 'title' => 'SAVE20',
516
+ 'type' => 'percentage', // 'percentage' or 'fixed'
517
+ 'amount' => 2000, // int — Discount amount in cents (or percentage value)
518
+ 'start_date' => '2026-01-01 00:00:00', // string|null — GMT start date
519
+ 'end_date' => '2026-12-31 23:59:59', // string|null — GMT end date
520
+ 'conditions' => [
521
+ 'is_recurring' => 'no',
522
+ // ... other condition fields
523
+ ],
524
+ ],
525
+ 'coupon' => $coupon, // \FluentCart\App\Models\Coupon — The newly created Coupon instance
526
+ ];
527
+ ```
528
+
529
+ #### Usage Example:
530
+ ```php
531
+ // Hook after a new coupon is created via admin REST API
532
+ add_action('fluent_cart/coupon_created', function($data) {
533
+ // Extract newly created Coupon model instance
534
+ $coupon = $data['coupon'];
535
+
536
+ // Notify marketing team via email about new coupon
537
+ wp_mail(
538
+ 'marketing@example.com',
539
+ 'New Coupon Created: ' . $coupon->title,
540
+ 'A new coupon has been created with code: ' . $coupon->title
541
+ );
542
+ }, 10, 1);
543
+ ```
544
+
545
+ ---
546
+
547
+ ### `coupon_updated`
548
+ `fluent_cart/coupon_updated` — Fired after a coupon is updated via the admin
549
+
550
+ * **When it runs:** This action fires after a Coupon has been successfully updated through the admin REST API. It runs after `CouponResource::update()` has persisted the changes, but before the activity log entry is recorded.
551
+ * **Source:** `app/Http/Controllers/CouponsController.php`
552
+
553
+ #### Parameters:
554
+ `$data` *(array)*: Coupon update data
555
+ ```php
556
+ $data = [
557
+ 'data' => [ // array — Sanitized request payload
558
+ 'title' => 'SAVE20',
559
+ 'type' => 'percentage',
560
+ 'amount' => 2500,
561
+ 'start_date' => '2026-01-01 00:00:00',
562
+ 'end_date' => '2026-12-31 23:59:59',
563
+ 'conditions' => [
564
+ 'is_recurring' => 'no',
565
+ // ... other condition fields
566
+ ],
567
+ ],
568
+ 'coupon' => $coupon, // \FluentCart\App\Models\Coupon — The updated Coupon instance
569
+ ];
570
+ ```
571
+
572
+ #### Usage Example:
573
+ ```php
574
+ // Hook after a coupon is updated via admin REST API
575
+ add_action('fluent_cart/coupon_updated', function($data) {
576
+ // Extract updated Coupon model instance
577
+ $coupon = $data['coupon'];
578
+
579
+ // Clear coupon validation cache when a coupon is modified
580
+ wp_cache_delete('fct_coupon_' . $coupon->id, 'fluent_cart');
581
+
582
+ // Sync updated coupon to external promotion platform
583
+ do_action('my_plugin/sync_coupon', $coupon);
584
+ }, 10, 1);
585
+ ```