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.
- package/README.md +59 -59
- package/dist/cards/fluentcart/tools.d.ts.map +1 -1
- package/dist/cards/fluentcart/tools.js +160 -12
- package/dist/cards/fluentcart/tools.js.map +1 -1
- package/dist/skills/fluentcart-developer/.claude-plugin/plugin.json +12 -12
- package/dist/skills/fluentcart-developer/.mcp.json +11 -11
- package/dist/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/fluent-cart/checkout.php +32 -32
- package/dist/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/functions.php +40 -40
- package/dist/skills/fluentcart-developer/examples/sample-fee-surcharge-plugin/fluentcart-fee-surcharge.php +38 -38
- package/dist/skills/fluentcart-developer/references/action-hooks-cart-checkout.md +1355 -1355
- package/dist/skills/fluentcart-developer/references/action-hooks-customers-users.md +266 -266
- package/dist/skills/fluentcart-developer/references/action-hooks-licenses.md +855 -855
- package/dist/skills/fluentcart-developer/references/action-hooks-orders.md +631 -631
- package/dist/skills/fluentcart-developer/references/action-hooks-payments-integrations.md +963 -963
- package/dist/skills/fluentcart-developer/references/action-hooks-products-coupons.md +585 -585
- package/dist/skills/fluentcart-developer/references/action-hooks-subscriptions.md +661 -661
- package/dist/skills/fluentcart-developer/references/database-models-query-builder.md +194 -194
- package/dist/skills/fluentcart-developer/references/database-models-reference.md +604 -604
- package/dist/skills/fluentcart-developer/references/engineering-notes.md +154 -154
- package/dist/skills/fluentcart-developer/references/fee-system-guide.md +449 -449
- package/dist/skills/fluentcart-developer/references/filter-hooks-cart-checkout.md +1202 -1202
- package/dist/skills/fluentcart-developer/references/filter-hooks-integrations-advanced.md +1598 -1598
- package/dist/skills/fluentcart-developer/references/filter-hooks-products-pricing.md +628 -628
- package/dist/skills/fluentcart-developer/references/filter-hooks-settings-configuration.md +1177 -1177
- package/dist/skills/fluentcart-developer/references/fluentcart-developer-guide.md +154 -154
- package/dist/skills/fluentcart-developer/references/ghost-product-selling.md +458 -458
- package/dist/skills/fluentcart-developer/references/modules-and-extensions-reference.md +224 -224
- package/dist/skills/fluentcart-developer/references/payment-gateway-integration.md +761 -761
- package/dist/skills/fluentcart-developer/references/rest-api-customer-profile.md +190 -190
- package/dist/skills/fluentcart-developer/references/rest-api-customers.md +1121 -1121
- package/dist/skills/fluentcart-developer/references/rest-api-dashboard-utilities.md +219 -219
- package/dist/skills/fluentcart-developer/references/rest-api-email-notifications.md +619 -619
- package/dist/skills/fluentcart-developer/references/rest-api-files.md +290 -290
- package/dist/skills/fluentcart-developer/references/rest-api-integrations.md +324 -324
- package/dist/skills/fluentcart-developer/references/rest-api-labels-attributes.md +321 -321
- package/dist/skills/fluentcart-developer/references/rest-api-order-bumps.md +200 -200
- package/dist/skills/fluentcart-developer/references/rest-api-overview.md +131 -131
- package/dist/skills/fluentcart-developer/references/rest-api-public-shop.md +172 -172
- package/dist/skills/fluentcart-developer/references/rest-api-reference.md +552 -552
- package/dist/skills/fluentcart-developer/references/rest-api-reports.md +377 -377
- package/dist/skills/fluentcart-developer/references/rest-api-roles-permissions.md +147 -147
- package/dist/skills/fluentcart-developer/references/rest-api-settings.md +528 -528
- package/dist/skills/fluentcart-developer/references/rest-api-shipping.md +799 -799
- package/dist/skills/fluentcart-developer/references/rest-api-tax.md +356 -356
- package/dist/skills/fluentcart-developer/references/subscription-customization.md +197 -197
- package/dist/skills/fluentcart-developer/scripts/cli.js +1 -1
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- 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
|