fluentcart-developer 2.3.0 → 2.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/README.md +59 -59
  2. package/dist/cards/fluentcart/tools.d.ts.map +1 -1
  3. package/dist/cards/fluentcart/tools.js +160 -12
  4. package/dist/cards/fluentcart/tools.js.map +1 -1
  5. package/dist/skills/fluentcart-developer/.claude-plugin/plugin.json +12 -12
  6. package/dist/skills/fluentcart-developer/.mcp.json +11 -11
  7. package/dist/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/fluent-cart/checkout.php +32 -32
  8. package/dist/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/functions.php +40 -40
  9. package/dist/skills/fluentcart-developer/examples/sample-fee-surcharge-plugin/fluentcart-fee-surcharge.php +38 -38
  10. package/dist/skills/fluentcart-developer/references/action-hooks-cart-checkout.md +1355 -1355
  11. package/dist/skills/fluentcart-developer/references/action-hooks-customers-users.md +266 -266
  12. package/dist/skills/fluentcart-developer/references/action-hooks-licenses.md +855 -855
  13. package/dist/skills/fluentcart-developer/references/action-hooks-orders.md +631 -631
  14. package/dist/skills/fluentcart-developer/references/action-hooks-payments-integrations.md +963 -963
  15. package/dist/skills/fluentcart-developer/references/action-hooks-products-coupons.md +585 -585
  16. package/dist/skills/fluentcart-developer/references/action-hooks-subscriptions.md +661 -661
  17. package/dist/skills/fluentcart-developer/references/database-models-query-builder.md +194 -194
  18. package/dist/skills/fluentcart-developer/references/database-models-reference.md +604 -604
  19. package/dist/skills/fluentcart-developer/references/engineering-notes.md +154 -154
  20. package/dist/skills/fluentcart-developer/references/fee-system-guide.md +449 -449
  21. package/dist/skills/fluentcart-developer/references/filter-hooks-cart-checkout.md +1202 -1202
  22. package/dist/skills/fluentcart-developer/references/filter-hooks-integrations-advanced.md +1598 -1598
  23. package/dist/skills/fluentcart-developer/references/filter-hooks-products-pricing.md +628 -628
  24. package/dist/skills/fluentcart-developer/references/filter-hooks-settings-configuration.md +1177 -1177
  25. package/dist/skills/fluentcart-developer/references/fluentcart-developer-guide.md +154 -154
  26. package/dist/skills/fluentcart-developer/references/ghost-product-selling.md +458 -458
  27. package/dist/skills/fluentcart-developer/references/modules-and-extensions-reference.md +224 -224
  28. package/dist/skills/fluentcart-developer/references/payment-gateway-integration.md +761 -761
  29. package/dist/skills/fluentcart-developer/references/rest-api-customer-profile.md +190 -190
  30. package/dist/skills/fluentcart-developer/references/rest-api-customers.md +1121 -1121
  31. package/dist/skills/fluentcart-developer/references/rest-api-dashboard-utilities.md +219 -219
  32. package/dist/skills/fluentcart-developer/references/rest-api-email-notifications.md +619 -619
  33. package/dist/skills/fluentcart-developer/references/rest-api-files.md +290 -290
  34. package/dist/skills/fluentcart-developer/references/rest-api-integrations.md +324 -324
  35. package/dist/skills/fluentcart-developer/references/rest-api-labels-attributes.md +321 -321
  36. package/dist/skills/fluentcart-developer/references/rest-api-order-bumps.md +200 -200
  37. package/dist/skills/fluentcart-developer/references/rest-api-overview.md +131 -131
  38. package/dist/skills/fluentcart-developer/references/rest-api-public-shop.md +172 -172
  39. package/dist/skills/fluentcart-developer/references/rest-api-reference.md +552 -552
  40. package/dist/skills/fluentcart-developer/references/rest-api-reports.md +377 -377
  41. package/dist/skills/fluentcart-developer/references/rest-api-roles-permissions.md +147 -147
  42. package/dist/skills/fluentcart-developer/references/rest-api-settings.md +528 -528
  43. package/dist/skills/fluentcart-developer/references/rest-api-shipping.md +799 -799
  44. package/dist/skills/fluentcart-developer/references/rest-api-tax.md +356 -356
  45. package/dist/skills/fluentcart-developer/references/subscription-customization.md +197 -197
  46. package/dist/skills/fluentcart-developer/scripts/cli.js +1 -1
  47. package/dist/version.d.ts +1 -1
  48. package/dist/version.js +1 -1
  49. package/package.json +65 -65
@@ -1,458 +1,458 @@
1
- # Ghost Product Selling Options
2
-
3
- FluentCart provides a powerful hook system that allows developers to sell ghost products that don't exist in the product catalog. This feature enables selling add-ons, gift wrapping, custom subscriptions, and any other custom items through your store.
4
-
5
- ---
6
-
7
- ## Overview
8
-
9
- Custom product selling allows you to add items to the cart that are not stored as regular products in the database. This is useful for:
10
-
11
- - **Add-on Products** - Gift wrapping, insurance, custom options
12
- - **Custom Subscriptions** - Recurring billing for non-catalog items
13
- - **Dynamic Products** - Products created on-the-fly based on user selections
14
- - **Service-Based Items** - One-time or recurring service purchases
15
-
16
- ---
17
-
18
- ## Implementation Flow
19
-
20
- The complete implementation follows this flow:
21
-
22
- ```
23
- Add Button → Add Validation Hook → Handle Quantity Change Hook → Checkout Validation Hook
24
- ```
25
-
26
- ---
27
-
28
- ## Step 1: Add Button (Frontend)
29
-
30
- Add the appropriate button to your page based on the item type.
31
-
32
- ### One-Time Custom Item (Add to Cart)
33
-
34
- For one-time purchases that are added to the cart:
35
-
36
- ```html
37
- <button
38
- data-cart-id="1000"
39
- data-quantity="1"
40
- data-is-custom="true"
41
- data-fluent-cart-add-to-cart-button
42
- >
43
- Add Gift Wrapping
44
- </button>
45
- ```
46
-
47
- ### Subscription Custom Item (Instant Checkout)
48
-
49
- For subscription items that go directly to checkout:
50
-
51
- ```html
52
- <a href="https://yourstore.com/?fluent-cart=instant_checkout&item_id=3001&quantity=1&is_custom=true">
53
- Buy Now
54
- </a>
55
- ```
56
-
57
- > **Note:** Replace `https://yourstore.com` with your actual site URL and `3001` with your custom item ID.
58
-
59
- ---
60
-
61
- ## Step 2: Add Validation Hook (Backend)
62
-
63
- Use this filter to validate and return the custom product item when it's added to the cart.
64
-
65
- ### Hook: `fluent_cart/cart/validate_custom_item`
66
-
67
- **Parameters:**
68
-
69
- | Parameter | Type | Description |
70
- |-----------|------|-------------|
71
- | `$variation` | `object/array` | The variation object to be modified |
72
- | `$item` | `array` | The item data from the request |
73
-
74
- **Returns:** The modified variation object
75
-
76
- ### Example: Validate New Custom Item
77
-
78
- ```php
79
- add_filter('fluent_cart/cart/validate_custom_item',
80
- function($variation, $item) {
81
- // Check if the item is flagged as custom
82
- if ((bool)$item['is_custom']) {
83
- // Build the custom variation object with all required fields
84
- $variation = (object) [
85
- 'item_id' => absint($item['item_id']),
86
- 'object_id' => absint($item['item_id']),
87
- 'post_id' => 5000,
88
- 'quantity' => max(1, (int)$item['quantity']),
89
- 'price' => floatval(5000),
90
- 'unit_price' => floatval(5000),
91
- 'line_total' => floatval(5000) * max(1, (int)$item['quantity']),
92
- 'post_title' => sanitize_text_field('Weekly Protein Pack'),
93
- 'title' => sanitize_text_field('Subscription Version 1'),
94
- 'is_custom' => true,
95
- 'payment_type' => 'subscription',
96
- "other_info" => [
97
- "payment_type" => "subscription",
98
- "repeat_interval" => "monthly",
99
- "installment" => "no",
100
- "manage_setup_fee" => "yes",
101
- "signup_fee" => 500
102
- ],
103
-
104
- ];
105
- }
106
- return $variation;
107
- }, 10, 2);
108
- ```
109
-
110
- ---
111
-
112
- ## Step 3: Handle Quantity Changes (Cart)
113
-
114
- This step applies only to **one-time items** for quantity increment/decrement actions.
115
-
116
- ### Hook: `fluent_cart/cart/custom_item_quantity_changed`
117
-
118
- **Parameters:**
119
-
120
- | Parameter | Type | Description |
121
- |-----------|------|-------------|
122
- | `$variation` | `object/array` | The variation object to be updated |
123
- | `$item` | `array` | Item data including quantity changes |
124
-
125
- **Returns:** The modified variation object with updated quantity and totals
126
-
127
- ### Example: Change Existing Item Quantity
128
-
129
- ```php
130
- add_filter('fluent_cart/cart/custom_item_quantity_changed', function ($variation, $item) {
131
-
132
- // Skip non-custom items
133
- if (empty($item['is_custom'])) {
134
- return $variation;
135
- }
136
-
137
- // Ensure array format for manipulation
138
- $variation = (array) $variation;
139
-
140
- $newQty = (int) ($item['new_quantity'] ?? 1);
141
- $oldQty = (int) ($item['old_quantity'] ?? 1);
142
- $byInput = (bool) ($item['by_input'] ?? false);
143
-
144
- /**
145
- * If quantity changed via increment, decrement or delete buttons
146
- */
147
- if (!$byInput) {
148
- $newQty = $newQty == 0 ? 0 : ($oldQty+$newQty);
149
- }
150
-
151
- // Recalculate line total based on new quantity
152
- $price = (float) ($variation['price'] ?? 0);
153
-
154
- $variation['quantity'] = $newQty;
155
- $variation['line_total'] = $price * $newQty;
156
-
157
- return $variation;
158
-
159
- }, 10, 2);
160
- ```
161
-
162
- ---
163
-
164
- ## Step 4: Checkout Validation
165
-
166
- This hook runs before payment processing for both one-time and subscription items.
167
-
168
- ### Hook: `fluent_cart/payment/validate_custom_item`
169
-
170
- **Parameters:**
171
-
172
- | Parameter | Type | Description |
173
- |-----------|------|-------------|
174
- | `$items` | `array` | Array containing product and variation objects |
175
- | `$data` | `array` | Additional checkout data |
176
-
177
- **Returns:** Modified items array
178
-
179
- ### Example: Payment Validate Item
180
-
181
- ```php
182
- add_filter('fluent_cart/payment/validate_custom_item', function ($items, $data) {
183
-
184
- [$product, $variation] = $items;
185
-
186
- // Mark the item as custom visually in admin and receipts
187
- $variation->title .= ' (Custom Item)';
188
- $product->post_title .= ' [Custom]';
189
-
190
- return [$product, $variation];
191
-
192
- }, 10, 2);
193
- ```
194
-
195
- ---
196
-
197
- ## Step 5: Admin Order Update Handling (Optional)
198
-
199
- Handle custom item updates from the WordPress admin panel after an order is placed.
200
-
201
- ### Order Item Changed
202
-
203
- **Action:** `fluent_cart/order/custom_item_changed`
204
-
205
- **Parameters:**
206
-
207
- | Parameter | Type | Description |
208
- |-----------|------|-------------|
209
- | `$oldItem` | `array` | The original item data |
210
- | `$item` | `array` | The updated item data |
211
-
212
- **Returns:** The item to be saved
213
-
214
- ### Example: Order Item Changed
215
-
216
- ```php
217
- add_filter('fluent_cart/order/custom_item_changed', function ($oldItem, $item) {
218
-
219
- $oldItem = (array) $oldItem;
220
- $item = (array) $item;
221
-
222
- $isCustom = (bool) ($item['is_custom'] ?? false);
223
- $newQuantity = (int) ($item['quantity'] ?? 1);
224
- $oldQuantity = (int) ($oldItem['quantity'] ?? 1);
225
-
226
- /**
227
- * If item is a Custom Item → always save updated changes
228
- */
229
- if ($isCustom) {
230
- return $item;
231
- }
232
-
233
- /**
234
- * If quantity is unchanged → return old item (no update)
235
- */
236
- if ($oldQuantity === $newQuantity) {
237
- return $oldItem;
238
- }
239
-
240
- /**
241
- * If quantity changed → allow update
242
- */
243
- return $item;
244
-
245
- }, 10, 2);
246
- ```
247
-
248
- ### Before Custom Items Are Deleted
249
-
250
- **Action:** `fluent_cart/order/before_custom_items_deleted`
251
-
252
- **Parameters:**
253
-
254
- | Parameter | Type | Description |
255
- |-----------|------|-------------|
256
- | `$customItems` | `array` | Array of custom items to be deleted |
257
- | `$order` | `object` | The order object |
258
-
259
- ### Example: Before Order Item Deleted
260
-
261
- ```php
262
- add_action('fluent_cart/order/before_custom_items_deleted', function ($customItems, $order) {
263
-
264
- // Log each custom item before deletion
265
- foreach ($customItems as $item) {
266
- error_log(
267
- sprintf(
268
- 'Custom item about to be deleted. Order #%d | Item ID: %d | Qty: %d',
269
- $order->id,
270
- $item->id,
271
- $item->quantity
272
- )
273
- );
274
-
275
- // Restore external stock if needed
276
- }
277
-
278
- }, 10, 2);
279
- ```
280
-
281
- ### After Custom Items Are Deleted
282
-
283
- **Action:** `fluent_cart/order/after_custom_items_deleted`
284
-
285
- **Parameters:**
286
-
287
- | Parameter | Type | Description |
288
- |-----------|------|-------------|
289
- | `$customItems` | `array` | Array of deleted custom items |
290
- | `$order` | `object` | The order object |
291
-
292
- ### Example: After Order Item Deleted
293
-
294
- ```php
295
- add_action('fluent_cart/order/after_custom_items_deleted', function ($customItems, $order) {
296
-
297
- // Log deletion and perform cleanup for each item
298
- foreach ($customItems as $item) {
299
- error_log(
300
- sprintf(
301
- 'Custom item deleted. Order #%d | Item ID: %d | Qty: %d',
302
- $order->id,
303
- $item->id,
304
- $item->quantity
305
- )
306
- );
307
-
308
- // Analytics or internal counters
309
- // Notify admin
310
- // wp_mail('admin@example.com', 'Custom Item Deleted', 'Item ID ' . $item->id . ' was deleted');
311
- }
312
-
313
- }, 10, 2);
314
- ```
315
-
316
- ---
317
-
318
- ## Sample Datasets
319
-
320
- ### One-Time Item
321
-
322
- ```php
323
- $item = [
324
- "item_id" => 1000,
325
- "object_id" => 1000,
326
- "post_id" => 10000,
327
- "quantity" => 1,
328
- "is_custom" => true,
329
- "post_title" => "Air Max 1 running shoe",
330
- "title" => "Version 1",
331
- "price" => 2000,
332
- "unit_price" => 2000,
333
- "line_total" => 2000 * 1, // quantity is 1
334
- "payment_type" => "onetime",
335
- "fulfillment_type" => "digital",
336
- "featured_media" => "http://wordpress.test/wp-content/uploads/2025/11/white-navy-athletic-shoe-4-1.jpeg",
337
- "sold_individually"=> 0,
338
- "other_info" => [
339
- "payment_type" => "onetime"
340
- ],
341
- "view_url" => "https://www.example.com/product/air-max-1-running-shoe"
342
- ];
343
- ```
344
-
345
- ### Subscription Item
346
-
347
- ```php
348
- $item = [
349
- "item_id" => 2000,
350
- "object_id" => 2000,
351
- "post_id" => 20000,
352
- "quantity" => 1, // always 1 for subscription
353
- "is_custom" => true,
354
- "post_title" => "Weekly Protein Pack",
355
- "title" => "Subscription Version 1",
356
- "price" => 2500,
357
- "unit_price" => 2500,
358
- "line_total" => 2500 * 1,
359
- "payment_type" => "subscription",
360
- "fulfillment_type" => "digital",
361
- "featured_media" => "http://wordpress.test/wp-content/uploads/2025/11/protein-pack-1.jpeg",
362
- "sold_individually"=> 1, // enforce quantity = 1
363
- "other_info" => [
364
- "payment_type" => "subscription",
365
- "repeat_interval" => "monthly",
366
- "installment" => "no",
367
- "manage_setup_fee" => "yes",
368
- "signup_fee" => 500
369
- ],
370
- "view_url" => "https://www.example.com/product/weekly-protein-pack"
371
- ];
372
- ```
373
-
374
- ### Payment Gateway Validation During Checkout
375
-
376
- ```php
377
- $variation = (object)[
378
- "item_id" => 1000,
379
- "object_id" => 1000,
380
- "post_id" => 10000,
381
- "quantity" => 1,
382
- "is_custom" => true,
383
- "post_title" => "Air Max 1 running shoe",
384
- "title" => "Version 1",
385
- "price" => 2000,
386
- "unit_price" => 2000,
387
- "line_total" => 2000 * 1,
388
- "payment_type" => "onetime",
389
- "fulfillment_type" => "digital",
390
- "featured_media" => "http://wordpress.test/wp-content/uploads/2025/11/white-navy-athletic-shoe-4-1.jpeg",
391
- "sold_individually"=> 0,
392
- "other_info" => [
393
- "payment_type" => "onetime"
394
- ],
395
- "view_url" => "https://www.example.com/product/air-max-1-running-shoe"
396
- ];
397
-
398
- $product = (object)[
399
- "ID" => 148,
400
- "post_title" => "Air Max 1 running shoe",
401
- "post_status" => "publish",
402
- ];
403
- ```
404
-
405
- ---
406
-
407
- ## Key Properties Reference
408
-
409
- ### Item Object Properties
410
-
411
- | Property | Type | Description | Example |
412
- |----------|------|-------------|---------|
413
- | `item_id` | integer | Unique identifier for the custom item | `1000` |
414
- | `object_id` | integer | Reference ID for the item | `1000` |
415
- | `post_id` | integer | WordPress post ID reference | `5000` |
416
- | `quantity` | integer | Item quantity | `1` |
417
- | `is_custom` | boolean | Marks item as custom | `true` |
418
- | `post_title` | string | Product title | `"Air Max 1 running shoe"` |
419
- | `title` | string | Variation title | `"Version 1"` |
420
- | `price` | float | Unit price | `2000` |
421
- | `unit_price` | float | Unit price (same as price) | `2000` |
422
- | `line_total` | float | Total price (price × quantity) | `2000` |
423
- | `payment_type` | string | `onetime` or `subscription` | `"onetime"` |
424
- | `fulfillment_type` | string | `digital` or `physical` | `"digital"` |
425
- | `featured_media` | string | Media URL | `"http://..."` |
426
- | `sold_individually` | integer | `0` for no, `1` for yes | `0` |
427
- | `other_info` | array | Additional information | See below |
428
-
429
- ### `other_info` Properties for Subscriptions
430
-
431
- | Property | Type | Description | Example |
432
- |----------|------|-------------|---------|
433
- | `payment_type` | string | Type of payment | `"subscription"` |
434
- | `repeat_interval` | string | Billing frequency | `"monthly"` |
435
- | `installment` | string | Installment plan | `"no"` |
436
- | `manage_setup_fee` | string | Enable setup fee | `"yes"` |
437
- | `signup_fee` | float | Setup fee amount | `500` |
438
-
439
- ---
440
-
441
- ## Best Practices
442
-
443
- - **Always Validate Data:** Use the validation hook to ensure item data is correct before adding to cart
444
- - **Handle Quantity Changes:** Implement quantity change handlers for one-time items
445
- - **Mark Custom Items:** Use `is_custom` flag to distinguish custom items from regular products (required for all custom items)
446
- - **Set Correct Payment Type:** Ensure `payment_type` is set correctly (`onetime` or `subscription`)
447
- - **Calculate Totals:** Always calculate `line_total` as `price × quantity`
448
- - **Use Sanitization:** Apply `sanitize_text_field()` and `absint()` for security
449
- - **Handle Admin Actions:** Implement order update handlers if admins will modify orders
450
-
451
- ---
452
-
453
- ## Related Documentation
454
-
455
- - [Developer Hooks](action-hooks-orders.md) - Complete hooks and filters reference
456
- - [Products API](rest-api-reference.md) - Product management API
457
- - [Orders API](rest-api-reference.md) - Order management API
458
- - [Database Models](database-models-reference.md) - Data model documentation
1
+ # Ghost Product Selling Options
2
+
3
+ FluentCart provides a powerful hook system that allows developers to sell ghost products that don't exist in the product catalog. This feature enables selling add-ons, gift wrapping, custom subscriptions, and any other custom items through your store.
4
+
5
+ ---
6
+
7
+ ## Overview
8
+
9
+ Custom product selling allows you to add items to the cart that are not stored as regular products in the database. This is useful for:
10
+
11
+ - **Add-on Products** - Gift wrapping, insurance, custom options
12
+ - **Custom Subscriptions** - Recurring billing for non-catalog items
13
+ - **Dynamic Products** - Products created on-the-fly based on user selections
14
+ - **Service-Based Items** - One-time or recurring service purchases
15
+
16
+ ---
17
+
18
+ ## Implementation Flow
19
+
20
+ The complete implementation follows this flow:
21
+
22
+ ```
23
+ Add Button → Add Validation Hook → Handle Quantity Change Hook → Checkout Validation Hook
24
+ ```
25
+
26
+ ---
27
+
28
+ ## Step 1: Add Button (Frontend)
29
+
30
+ Add the appropriate button to your page based on the item type.
31
+
32
+ ### One-Time Custom Item (Add to Cart)
33
+
34
+ For one-time purchases that are added to the cart:
35
+
36
+ ```html
37
+ <button
38
+ data-cart-id="1000"
39
+ data-quantity="1"
40
+ data-is-custom="true"
41
+ data-fluent-cart-add-to-cart-button
42
+ >
43
+ Add Gift Wrapping
44
+ </button>
45
+ ```
46
+
47
+ ### Subscription Custom Item (Instant Checkout)
48
+
49
+ For subscription items that go directly to checkout:
50
+
51
+ ```html
52
+ <a href="https://yourstore.com/?fluent-cart=instant_checkout&item_id=3001&quantity=1&is_custom=true">
53
+ Buy Now
54
+ </a>
55
+ ```
56
+
57
+ > **Note:** Replace `https://yourstore.com` with your actual site URL and `3001` with your custom item ID.
58
+
59
+ ---
60
+
61
+ ## Step 2: Add Validation Hook (Backend)
62
+
63
+ Use this filter to validate and return the custom product item when it's added to the cart.
64
+
65
+ ### Hook: `fluent_cart/cart/validate_custom_item`
66
+
67
+ **Parameters:**
68
+
69
+ | Parameter | Type | Description |
70
+ |-----------|------|-------------|
71
+ | `$variation` | `object/array` | The variation object to be modified |
72
+ | `$item` | `array` | The item data from the request |
73
+
74
+ **Returns:** The modified variation object
75
+
76
+ ### Example: Validate New Custom Item
77
+
78
+ ```php
79
+ add_filter('fluent_cart/cart/validate_custom_item',
80
+ function($variation, $item) {
81
+ // Check if the item is flagged as custom
82
+ if ((bool)$item['is_custom']) {
83
+ // Build the custom variation object with all required fields
84
+ $variation = (object) [
85
+ 'item_id' => absint($item['item_id']),
86
+ 'object_id' => absint($item['item_id']),
87
+ 'post_id' => 5000,
88
+ 'quantity' => max(1, (int)$item['quantity']),
89
+ 'price' => floatval(5000),
90
+ 'unit_price' => floatval(5000),
91
+ 'line_total' => floatval(5000) * max(1, (int)$item['quantity']),
92
+ 'post_title' => sanitize_text_field('Weekly Protein Pack'),
93
+ 'title' => sanitize_text_field('Subscription Version 1'),
94
+ 'is_custom' => true,
95
+ 'payment_type' => 'subscription',
96
+ "other_info" => [
97
+ "payment_type" => "subscription",
98
+ "repeat_interval" => "monthly",
99
+ "installment" => "no",
100
+ "manage_setup_fee" => "yes",
101
+ "signup_fee" => 500
102
+ ],
103
+
104
+ ];
105
+ }
106
+ return $variation;
107
+ }, 10, 2);
108
+ ```
109
+
110
+ ---
111
+
112
+ ## Step 3: Handle Quantity Changes (Cart)
113
+
114
+ This step applies only to **one-time items** for quantity increment/decrement actions.
115
+
116
+ ### Hook: `fluent_cart/cart/custom_item_quantity_changed`
117
+
118
+ **Parameters:**
119
+
120
+ | Parameter | Type | Description |
121
+ |-----------|------|-------------|
122
+ | `$variation` | `object/array` | The variation object to be updated |
123
+ | `$item` | `array` | Item data including quantity changes |
124
+
125
+ **Returns:** The modified variation object with updated quantity and totals
126
+
127
+ ### Example: Change Existing Item Quantity
128
+
129
+ ```php
130
+ add_filter('fluent_cart/cart/custom_item_quantity_changed', function ($variation, $item) {
131
+
132
+ // Skip non-custom items
133
+ if (empty($item['is_custom'])) {
134
+ return $variation;
135
+ }
136
+
137
+ // Ensure array format for manipulation
138
+ $variation = (array) $variation;
139
+
140
+ $newQty = (int) ($item['new_quantity'] ?? 1);
141
+ $oldQty = (int) ($item['old_quantity'] ?? 1);
142
+ $byInput = (bool) ($item['by_input'] ?? false);
143
+
144
+ /**
145
+ * If quantity changed via increment, decrement or delete buttons
146
+ */
147
+ if (!$byInput) {
148
+ $newQty = $newQty == 0 ? 0 : ($oldQty+$newQty);
149
+ }
150
+
151
+ // Recalculate line total based on new quantity
152
+ $price = (float) ($variation['price'] ?? 0);
153
+
154
+ $variation['quantity'] = $newQty;
155
+ $variation['line_total'] = $price * $newQty;
156
+
157
+ return $variation;
158
+
159
+ }, 10, 2);
160
+ ```
161
+
162
+ ---
163
+
164
+ ## Step 4: Checkout Validation
165
+
166
+ This hook runs before payment processing for both one-time and subscription items.
167
+
168
+ ### Hook: `fluent_cart/payment/validate_custom_item`
169
+
170
+ **Parameters:**
171
+
172
+ | Parameter | Type | Description |
173
+ |-----------|------|-------------|
174
+ | `$items` | `array` | Array containing product and variation objects |
175
+ | `$data` | `array` | Additional checkout data |
176
+
177
+ **Returns:** Modified items array
178
+
179
+ ### Example: Payment Validate Item
180
+
181
+ ```php
182
+ add_filter('fluent_cart/payment/validate_custom_item', function ($items, $data) {
183
+
184
+ [$product, $variation] = $items;
185
+
186
+ // Mark the item as custom visually in admin and receipts
187
+ $variation->title .= ' (Custom Item)';
188
+ $product->post_title .= ' [Custom]';
189
+
190
+ return [$product, $variation];
191
+
192
+ }, 10, 2);
193
+ ```
194
+
195
+ ---
196
+
197
+ ## Step 5: Admin Order Update Handling (Optional)
198
+
199
+ Handle custom item updates from the WordPress admin panel after an order is placed.
200
+
201
+ ### Order Item Changed
202
+
203
+ **Action:** `fluent_cart/order/custom_item_changed`
204
+
205
+ **Parameters:**
206
+
207
+ | Parameter | Type | Description |
208
+ |-----------|------|-------------|
209
+ | `$oldItem` | `array` | The original item data |
210
+ | `$item` | `array` | The updated item data |
211
+
212
+ **Returns:** The item to be saved
213
+
214
+ ### Example: Order Item Changed
215
+
216
+ ```php
217
+ add_filter('fluent_cart/order/custom_item_changed', function ($oldItem, $item) {
218
+
219
+ $oldItem = (array) $oldItem;
220
+ $item = (array) $item;
221
+
222
+ $isCustom = (bool) ($item['is_custom'] ?? false);
223
+ $newQuantity = (int) ($item['quantity'] ?? 1);
224
+ $oldQuantity = (int) ($oldItem['quantity'] ?? 1);
225
+
226
+ /**
227
+ * If item is a Custom Item → always save updated changes
228
+ */
229
+ if ($isCustom) {
230
+ return $item;
231
+ }
232
+
233
+ /**
234
+ * If quantity is unchanged → return old item (no update)
235
+ */
236
+ if ($oldQuantity === $newQuantity) {
237
+ return $oldItem;
238
+ }
239
+
240
+ /**
241
+ * If quantity changed → allow update
242
+ */
243
+ return $item;
244
+
245
+ }, 10, 2);
246
+ ```
247
+
248
+ ### Before Custom Items Are Deleted
249
+
250
+ **Action:** `fluent_cart/order/before_custom_items_deleted`
251
+
252
+ **Parameters:**
253
+
254
+ | Parameter | Type | Description |
255
+ |-----------|------|-------------|
256
+ | `$customItems` | `array` | Array of custom items to be deleted |
257
+ | `$order` | `object` | The order object |
258
+
259
+ ### Example: Before Order Item Deleted
260
+
261
+ ```php
262
+ add_action('fluent_cart/order/before_custom_items_deleted', function ($customItems, $order) {
263
+
264
+ // Log each custom item before deletion
265
+ foreach ($customItems as $item) {
266
+ error_log(
267
+ sprintf(
268
+ 'Custom item about to be deleted. Order #%d | Item ID: %d | Qty: %d',
269
+ $order->id,
270
+ $item->id,
271
+ $item->quantity
272
+ )
273
+ );
274
+
275
+ // Restore external stock if needed
276
+ }
277
+
278
+ }, 10, 2);
279
+ ```
280
+
281
+ ### After Custom Items Are Deleted
282
+
283
+ **Action:** `fluent_cart/order/after_custom_items_deleted`
284
+
285
+ **Parameters:**
286
+
287
+ | Parameter | Type | Description |
288
+ |-----------|------|-------------|
289
+ | `$customItems` | `array` | Array of deleted custom items |
290
+ | `$order` | `object` | The order object |
291
+
292
+ ### Example: After Order Item Deleted
293
+
294
+ ```php
295
+ add_action('fluent_cart/order/after_custom_items_deleted', function ($customItems, $order) {
296
+
297
+ // Log deletion and perform cleanup for each item
298
+ foreach ($customItems as $item) {
299
+ error_log(
300
+ sprintf(
301
+ 'Custom item deleted. Order #%d | Item ID: %d | Qty: %d',
302
+ $order->id,
303
+ $item->id,
304
+ $item->quantity
305
+ )
306
+ );
307
+
308
+ // Analytics or internal counters
309
+ // Notify admin
310
+ // wp_mail('admin@example.com', 'Custom Item Deleted', 'Item ID ' . $item->id . ' was deleted');
311
+ }
312
+
313
+ }, 10, 2);
314
+ ```
315
+
316
+ ---
317
+
318
+ ## Sample Datasets
319
+
320
+ ### One-Time Item
321
+
322
+ ```php
323
+ $item = [
324
+ "item_id" => 1000,
325
+ "object_id" => 1000,
326
+ "post_id" => 10000,
327
+ "quantity" => 1,
328
+ "is_custom" => true,
329
+ "post_title" => "Air Max 1 running shoe",
330
+ "title" => "Version 1",
331
+ "price" => 2000,
332
+ "unit_price" => 2000,
333
+ "line_total" => 2000 * 1, // quantity is 1
334
+ "payment_type" => "onetime",
335
+ "fulfillment_type" => "digital",
336
+ "featured_media" => "http://wordpress.test/wp-content/uploads/2025/11/white-navy-athletic-shoe-4-1.jpeg",
337
+ "sold_individually"=> 0,
338
+ "other_info" => [
339
+ "payment_type" => "onetime"
340
+ ],
341
+ "view_url" => "https://www.example.com/product/air-max-1-running-shoe"
342
+ ];
343
+ ```
344
+
345
+ ### Subscription Item
346
+
347
+ ```php
348
+ $item = [
349
+ "item_id" => 2000,
350
+ "object_id" => 2000,
351
+ "post_id" => 20000,
352
+ "quantity" => 1, // always 1 for subscription
353
+ "is_custom" => true,
354
+ "post_title" => "Weekly Protein Pack",
355
+ "title" => "Subscription Version 1",
356
+ "price" => 2500,
357
+ "unit_price" => 2500,
358
+ "line_total" => 2500 * 1,
359
+ "payment_type" => "subscription",
360
+ "fulfillment_type" => "digital",
361
+ "featured_media" => "http://wordpress.test/wp-content/uploads/2025/11/protein-pack-1.jpeg",
362
+ "sold_individually"=> 1, // enforce quantity = 1
363
+ "other_info" => [
364
+ "payment_type" => "subscription",
365
+ "repeat_interval" => "monthly",
366
+ "installment" => "no",
367
+ "manage_setup_fee" => "yes",
368
+ "signup_fee" => 500
369
+ ],
370
+ "view_url" => "https://www.example.com/product/weekly-protein-pack"
371
+ ];
372
+ ```
373
+
374
+ ### Payment Gateway Validation During Checkout
375
+
376
+ ```php
377
+ $variation = (object)[
378
+ "item_id" => 1000,
379
+ "object_id" => 1000,
380
+ "post_id" => 10000,
381
+ "quantity" => 1,
382
+ "is_custom" => true,
383
+ "post_title" => "Air Max 1 running shoe",
384
+ "title" => "Version 1",
385
+ "price" => 2000,
386
+ "unit_price" => 2000,
387
+ "line_total" => 2000 * 1,
388
+ "payment_type" => "onetime",
389
+ "fulfillment_type" => "digital",
390
+ "featured_media" => "http://wordpress.test/wp-content/uploads/2025/11/white-navy-athletic-shoe-4-1.jpeg",
391
+ "sold_individually"=> 0,
392
+ "other_info" => [
393
+ "payment_type" => "onetime"
394
+ ],
395
+ "view_url" => "https://www.example.com/product/air-max-1-running-shoe"
396
+ ];
397
+
398
+ $product = (object)[
399
+ "ID" => 148,
400
+ "post_title" => "Air Max 1 running shoe",
401
+ "post_status" => "publish",
402
+ ];
403
+ ```
404
+
405
+ ---
406
+
407
+ ## Key Properties Reference
408
+
409
+ ### Item Object Properties
410
+
411
+ | Property | Type | Description | Example |
412
+ |----------|------|-------------|---------|
413
+ | `item_id` | integer | Unique identifier for the custom item | `1000` |
414
+ | `object_id` | integer | Reference ID for the item | `1000` |
415
+ | `post_id` | integer | WordPress post ID reference | `5000` |
416
+ | `quantity` | integer | Item quantity | `1` |
417
+ | `is_custom` | boolean | Marks item as custom | `true` |
418
+ | `post_title` | string | Product title | `"Air Max 1 running shoe"` |
419
+ | `title` | string | Variation title | `"Version 1"` |
420
+ | `price` | float | Unit price | `2000` |
421
+ | `unit_price` | float | Unit price (same as price) | `2000` |
422
+ | `line_total` | float | Total price (price × quantity) | `2000` |
423
+ | `payment_type` | string | `onetime` or `subscription` | `"onetime"` |
424
+ | `fulfillment_type` | string | `digital` or `physical` | `"digital"` |
425
+ | `featured_media` | string | Media URL | `"http://..."` |
426
+ | `sold_individually` | integer | `0` for no, `1` for yes | `0` |
427
+ | `other_info` | array | Additional information | See below |
428
+
429
+ ### `other_info` Properties for Subscriptions
430
+
431
+ | Property | Type | Description | Example |
432
+ |----------|------|-------------|---------|
433
+ | `payment_type` | string | Type of payment | `"subscription"` |
434
+ | `repeat_interval` | string | Billing frequency | `"monthly"` |
435
+ | `installment` | string | Installment plan | `"no"` |
436
+ | `manage_setup_fee` | string | Enable setup fee | `"yes"` |
437
+ | `signup_fee` | float | Setup fee amount | `500` |
438
+
439
+ ---
440
+
441
+ ## Best Practices
442
+
443
+ - **Always Validate Data:** Use the validation hook to ensure item data is correct before adding to cart
444
+ - **Handle Quantity Changes:** Implement quantity change handlers for one-time items
445
+ - **Mark Custom Items:** Use `is_custom` flag to distinguish custom items from regular products (required for all custom items)
446
+ - **Set Correct Payment Type:** Ensure `payment_type` is set correctly (`onetime` or `subscription`)
447
+ - **Calculate Totals:** Always calculate `line_total` as `price × quantity`
448
+ - **Use Sanitization:** Apply `sanitize_text_field()` and `absint()` for security
449
+ - **Handle Admin Actions:** Implement order update handlers if admins will modify orders
450
+
451
+ ---
452
+
453
+ ## Related Documentation
454
+
455
+ - [Developer Hooks](action-hooks-orders.md) - Complete hooks and filters reference
456
+ - [Products API](rest-api-reference.md) - Product management API
457
+ - [Orders API](rest-api-reference.md) - Order management API
458
+ - [Database Models](database-models-reference.md) - Data model documentation