fluentcart-developer 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. package/.gitattributes +2 -0
  2. package/CLAUDE.md +22 -0
  3. package/CONTRIBUTING.md +73 -0
  4. package/LICENSE +21 -0
  5. package/README.md +127 -0
  6. package/SKILL.md +127 -0
  7. package/bin/index.js +281 -0
  8. package/copy-skills.js +43 -0
  9. package/package.json +38 -0
  10. package/skills/fluentcart-developer/SKILL.md +172 -0
  11. package/skills/fluentcart-developer/examples/README.md +25 -0
  12. package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/fluent-cart/checkout.php +32 -0
  13. package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/functions.php +40 -0
  14. package/skills/fluentcart-developer/examples/sample-custom-addon/fluentcart-custom-addon.php +114 -0
  15. package/skills/fluentcart-developer/examples/sample-custom-payment-gateway/fluentcart-custom-gateway-example.php +149 -0
  16. package/skills/fluentcart-developer/examples/sample-fee-surcharge-plugin/fluentcart-fee-surcharge.php +38 -0
  17. package/skills/fluentcart-developer/examples/sample-shipping-carrier/fluentcart-custom-shipping-carrier.php +62 -0
  18. package/skills/fluentcart-developer/references/action-hooks-admin-templates.md +787 -0
  19. package/skills/fluentcart-developer/references/action-hooks-cart-checkout.md +1355 -0
  20. package/skills/fluentcart-developer/references/action-hooks-customers-users.md +266 -0
  21. package/skills/fluentcart-developer/references/action-hooks-licenses.md +855 -0
  22. package/skills/fluentcart-developer/references/action-hooks-orders.md +631 -0
  23. package/skills/fluentcart-developer/references/action-hooks-payments-integrations.md +963 -0
  24. package/skills/fluentcart-developer/references/action-hooks-products-coupons.md +585 -0
  25. package/skills/fluentcart-developer/references/action-hooks-subscriptions.md +661 -0
  26. package/skills/fluentcart-developer/references/database-models-query-builder.md +194 -0
  27. package/skills/fluentcart-developer/references/database-models-reference.md +604 -0
  28. package/skills/fluentcart-developer/references/database-schema-reference.md +940 -0
  29. package/skills/fluentcart-developer/references/engineering-notes.md +154 -0
  30. package/skills/fluentcart-developer/references/fee-system-guide.md +449 -0
  31. package/skills/fluentcart-developer/references/filter-hooks-cart-checkout.md +1202 -0
  32. package/skills/fluentcart-developer/references/filter-hooks-customers-subscriptions.md +902 -0
  33. package/skills/fluentcart-developer/references/filter-hooks-integrations-advanced.md +1598 -0
  34. package/skills/fluentcart-developer/references/filter-hooks-orders-payments.md +1319 -0
  35. package/skills/fluentcart-developer/references/filter-hooks-products-pricing.md +628 -0
  36. package/skills/fluentcart-developer/references/filter-hooks-settings-configuration.md +1177 -0
  37. package/skills/fluentcart-developer/references/fluentcart-developer-guide.md +154 -0
  38. package/skills/fluentcart-developer/references/ghost-product-selling.md +458 -0
  39. package/skills/fluentcart-developer/references/modules-and-extensions-reference.md +224 -0
  40. package/skills/fluentcart-developer/references/paddle-gateway-case-study.md +1925 -0
  41. package/skills/fluentcart-developer/references/payment-gateway-integration.md +761 -0
  42. package/skills/fluentcart-developer/references/rest-api-checkout.md +286 -0
  43. package/skills/fluentcart-developer/references/rest-api-coupons.md +794 -0
  44. package/skills/fluentcart-developer/references/rest-api-customer-profile.md +190 -0
  45. package/skills/fluentcart-developer/references/rest-api-customers.md +1121 -0
  46. package/skills/fluentcart-developer/references/rest-api-dashboard-utilities.md +219 -0
  47. package/skills/fluentcart-developer/references/rest-api-email-notifications.md +619 -0
  48. package/skills/fluentcart-developer/references/rest-api-files.md +290 -0
  49. package/skills/fluentcart-developer/references/rest-api-integrations.md +324 -0
  50. package/skills/fluentcart-developer/references/rest-api-labels-attributes.md +321 -0
  51. package/skills/fluentcart-developer/references/rest-api-licensing.md +171 -0
  52. package/skills/fluentcart-developer/references/rest-api-order-bumps.md +200 -0
  53. package/skills/fluentcart-developer/references/rest-api-orders.md +1241 -0
  54. package/skills/fluentcart-developer/references/rest-api-overview.md +131 -0
  55. package/skills/fluentcart-developer/references/rest-api-products.md +2563 -0
  56. package/skills/fluentcart-developer/references/rest-api-public-shop.md +172 -0
  57. package/skills/fluentcart-developer/references/rest-api-reference.md +552 -0
  58. package/skills/fluentcart-developer/references/rest-api-reports.md +377 -0
  59. package/skills/fluentcart-developer/references/rest-api-roles-permissions.md +147 -0
  60. package/skills/fluentcart-developer/references/rest-api-settings.md +528 -0
  61. package/skills/fluentcart-developer/references/rest-api-shipping.md +800 -0
  62. package/skills/fluentcart-developer/references/rest-api-subscriptions.md +606 -0
  63. package/skills/fluentcart-developer/references/rest-api-tax.md +356 -0
  64. package/skills/fluentcart-developer/references/subscription-customization.md +197 -0
  65. package/skills/fluentcart-developer/scripts/cli.js +1 -0
  66. package/skills.sh.json +13 -0
@@ -0,0 +1,154 @@
1
+ # FluentCart Core Complete Developer Guide
2
+
3
+ > Source: Official FluentCart Developer Guide Documentation
4
+
5
+ Welcome to the complete developer guide for **FluentCart** — the self-hosted e-commerce plugin for WordPress. This guide covers core principles, architecture, extension points, codebase structure, and quick start instructions for developing custom add-ons, modules, and integrations.
6
+
7
+ ---
8
+
9
+ ## 🚀 Overview
10
+
11
+ ### What is FluentCart?
12
+ FluentCart is a **Self-Hosted E-commerce Plugin for WordPress** that helps businesses manage online stores, process payments, handle orders, and manage customers natively inside WordPress.
13
+
14
+ Unlike cloud-based SaaS solutions, FluentCart runs entirely on your WordPress site, ensuring total data privacy, unlimited products, zero order transaction surcharges, and complete operational control.
15
+
16
+ ### Why Extend FluentCart?
17
+ FluentCart is engineered from the ground up for deep extensibility:
18
+
19
+ - **315+ Action and Filter Hooks** for intercepting and customizing core execution flows.
20
+ - **Modular Architecture** allowing clean separation of payment gateways, shipping methods, and custom modules.
21
+ - **RESTful API** offering complete programmatic access to e-commerce resources.
22
+ - **WordPress-Native Standards** following modern PHP, PSR coding standards, and WordPress conventions.
23
+
24
+ ---
25
+
26
+ ## 📦 FluentCart Core vs. Pro Version Comparison
27
+
28
+ | Feature Category | Core (Free Version) | Pro (Premium Version) |
29
+ |---|---|---|
30
+ | **Product & Catalog** | Unlimited products, simple & variable pricing | Advanced variations & ghost products |
31
+ | **Order Processing** | Complete order management & receipts | Automated post-order workflows & order operation logs |
32
+ | **Customer Management** | Customer profiles, LTV tracking & addresses | Custom customer meta, advanced segmentation |
33
+ | **Payments & Shipping** | Core payment gateways & shipping zones | Dynamic shipping carriers, custom payment integrations |
34
+ | **Coupons & Discounts** | Standard discount codes & conditions | Stackable coupons, auto-applied promos & Order Bumps |
35
+ | **Software Licensing** | N/A | Full software license keys, site activations & updates |
36
+ | **Subscriptions** | N/A | Recurring billing cycles, trial periods & grace periods |
37
+ | **Roles & Permissions** | Basic WordPress capability checks | Granular team roles & permission management |
38
+
39
+ ---
40
+
41
+ ## 🏗 Core Development Concepts
42
+
43
+ ### 1. Data Architecture
44
+ FluentCart uses a clean, normalized database structure with integer monetary values stored in **cents**:
45
+
46
+ - **Orders (`fct_orders`):** Central record for order status, customer links, totals, and payment status.
47
+ - **Customers (`fct_customers`):** Profiles linked to WordPress users or guest transactions.
48
+ - **Products (WordPress Posts):** Core product metadata stored as custom post types, supplemented by `fct_product_details` and `fct_product_variations`.
49
+ - **Transactions (`fct_order_transactions`):** Payment charges, refunds, and gateway interaction records.
50
+ - **Subscriptions (`fct_subscriptions`):** Recurring billing metadata, billing cycles, and next billing schedules.
51
+
52
+ ### 2. Extension Points
53
+ - **WordPress Action Hooks:** Execute custom code on events (e.g. `fluent_cart/order_paid_done`).
54
+ - **WordPress Filter Hooks:** Modify data in-flight (e.g. `fluent_cart/fee_items`).
55
+ - **Module System:** Register custom payment gateways, shipping carriers, and storage drivers.
56
+ - **REST API:** Build external applications, dashboards, or headless checkout experiences.
57
+
58
+ ---
59
+
60
+ ## 📁 Application Codebase Directory Structure
61
+
62
+ ```
63
+ fluent-cart/
64
+ ├── app/ # Core application logic
65
+ │ ├── Hooks/ # WordPress action/filter handlers
66
+ │ │ ├── Handlers/ # Action/Filter handler classes
67
+ │ │ ├── actions.php # Action hook definitions
68
+ │ │ └── filters.php # Filter hook definitions
69
+ │ ├── Http/ # HTTP layer
70
+ │ │ ├── Controllers/ # Admin & REST API controllers
71
+ │ │ ├── Middleware/ # Request authentication & authorization
72
+ │ │ └── Routes/ # API and admin route definitions
73
+ │ ├── Models/ # Eloquent ORM database models (45+ models)
74
+ │ │ ├── Order.php # Order model
75
+ │ │ ├── Customer.php # Customer model
76
+ │ │ ├── Product.php # Product model
77
+ │ │ └── ... # Core & Pro model files
78
+ │ ├── Services/ # Core business logic services
79
+ │ │ ├── Payment/ # Payment processing drivers
80
+ │ │ ├── Shipping/ # Shipping calculation engines
81
+ │ │ └── Helper.php # Global helper utility functions
82
+ │ ├── Views/ # Admin PHP template views
83
+ │ ├── Events/ # Internal application events
84
+ │ ├── Listeners/ # Event listeners
85
+ │ └── Modules/ # Module registration system
86
+ │
87
+ ├── api/ # REST API resources & endpoint controllers
88
+ │ ├── Orders.php # Order management REST endpoints
89
+ │ ├── Customers.php # Customer management REST endpoints
90
+ │ ├── Products.php # Product catalog REST endpoints
91
+ │ └── Resource/ # JSON response resource transformers
92
+ │
93
+ ├── resources/ # Frontend application assets
94
+ │ ├── admin/ # Vue.js admin single-page application & Gutenberg blocks
95
+ │ ├── public/ # Storefront cart, checkout & portal components
96
+ │ └── styles/ # Core SCSS/CSS design tokens
97
+ │
98
+ ├── database/ # Database schema migrations & seeders
99
+ │ ├── Migrations/ # Table migration files (34+ migrations)
100
+ │ └── DBMigrator.php # Database migration manager
101
+ │
102
+ └── fluent-cart.php # Main WordPress plugin bootstrap entry file
103
+ ```
104
+
105
+ ---
106
+
107
+ ## ⚡ Quick Start Extension Blueprints
108
+
109
+ ### 1. Registering a Custom Extension
110
+ ```php
111
+ <?php
112
+ /**
113
+ * Plugin Name: FluentCart Custom Extension
114
+ * Description: Extension module for FluentCart e-commerce.
115
+ * Version: 1.0.0
116
+ * Author: Developer
117
+ */
118
+
119
+ if (!defined('ABSPATH')) {
120
+ exit; // Prevent direct execution access
121
+ }
122
+
123
+ // Attach listener to WordPress plugins_loaded hook
124
+ add_action('plugins_loaded', function () {
125
+ // Verify that FluentCart plugin is active
126
+ if (!defined('FLUENT_CART')) {
127
+ return; // Exit early if FluentCart is missing
128
+ }
129
+
130
+ // Initialize custom hook listeners and extension modules here
131
+ });
132
+ ```
133
+
134
+ ### 2. Post-Payment Asynchronous Task Listener
135
+ ```php
136
+ // Intercept order paid event asynchronously via Action Scheduler
137
+ add_action('fluent_cart/order_paid_done', function ($payload) {
138
+ // Extract Order model instance from payload array
139
+ $order = $payload['order'];
140
+
141
+ // Extract Customer model instance from payload array
142
+ $customer = $payload['customer'];
143
+
144
+ // Convert total order amount from integer cents to decimal format
145
+ $orderTotal = \FluentCart\App\Helpers\Helper::toDecimal($order->total_amount);
146
+
147
+ // Log payment details into FluentCart system activity log
148
+ fluent_cart_add_log(
149
+ 'Order Completed',
150
+ "Order #{$order->id} for {$customer->email} completed. Amount: ${orderTotal}",
151
+ 'info'
152
+ );
153
+ }, 10, 1);
154
+ ```
@@ -0,0 +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