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,321 @@
1
+ # Labels & Attributes API
2
+
3
+ Manage organizational labels for orders and customers, and product attribute groups and terms used for variation options in FluentCart.
4
+
5
+ **Base URL:** `https://your-site.com/wp-json/fluent-cart/v2`
6
+ **Policies:** `LabelPolicy` (Labels) / `ProductPolicy` (Attributes)
7
+
8
+ ---
9
+
10
+ ## Endpoints Overview
11
+
12
+ | Group | Method | Endpoint | Permission / Policy | Request Class | Description |
13
+ |-------|--------|----------|--------------------|---------------|-------------|
14
+ | **Labels** | GET | `/labels` | `labels/view` | — | Retrieve all labels |
15
+ | | POST | `/labels` | `labels/manage` | `LabelRequest` | Create label and optionally bind to entity |
16
+ | | POST | `/labels/update-label-selections` | `labels/manage` | — | Sync label selection for order/customer |
17
+ | **Attribute Groups** | GET | `/options/attr/groups` | `products/view` | — | List attribute groups (Color, Size, etc.) |
18
+ | | POST | `/options/attr/group` | `products/create` | `AttrGroupRequest` | Create attribute group |
19
+ | | GET | `/options/attr/group/{group_id}` | `products/view` | — | Get single attribute group (with terms) |
20
+ | | PUT | `/options/attr/group/{group_id}` | `products/edit` | `AttrGroupRequest` | Update attribute group |
21
+ | | DELETE | `/options/attr/group/{group_id}` | `products/delete` | — | Delete attribute group (guarded if in use) |
22
+ | **Attribute Terms** | GET | `/options/attr/group/{id}/terms` | `products/view` | — | List terms within attribute group |
23
+ | | POST | `/options/attr/group/{id}/term` | `products/create` | `AttrTermRequest` | Create term within attribute group |
24
+ | | POST | `/options/attr/group/{id}/term/{term_id}` | `products/edit` | `AttrTermRequest` | Update attribute term |
25
+ | | DELETE | `/options/attr/group/{id}/term/{term_id}` | `products/delete` | — | Delete attribute term (guarded if in use) |
26
+ | | POST | `/options/attr/group/{id}/term/{term_id}/serial` | `products/edit` | — | Shift term position (`up` or `down`) |
27
+
28
+ ---
29
+
30
+ ## Labels
31
+
32
+ Labels are tags that attach to orders, customers, or other entities via a polymorphic relationship for organizational filtering.
33
+
34
+ **Prefix:** `/fluent-cart/v2/labels` | **Policy:** `LabelPolicy`
35
+
36
+ ### List Labels
37
+
38
+ `GET /fluent-cart/v2/labels`
39
+
40
+ #### Permission
41
+
42
+ `labels/view`
43
+
44
+ #### Response
45
+
46
+ ```json
47
+ {
48
+ "labels": {
49
+ "labels": [
50
+ { "id": 1, "value": "VIP" },
51
+ { "id": 2, "value": "Wholesale" },
52
+ { "id": 3, "value": "Priority" }
53
+ ]
54
+ }
55
+ }
56
+ ```
57
+
58
+ ---
59
+
60
+ ### Create Label
61
+
62
+ `POST /fluent-cart/v2/labels`
63
+
64
+ Create a new label and optionally attach it to an entity (`Order`, `Customer`).
65
+
66
+ #### Permission
67
+
68
+ `labels/manage` | **Request Class:** `LabelRequest`
69
+
70
+ #### Parameters
71
+
72
+ | Parameter | Type | Location | Required | Description |
73
+ |-----------|------|----------|----------|-------------|
74
+ | `value` | string | body | Yes | Label name. Must be unique across `fct_label` table |
75
+ | `bind_to_type` | string | body | No | Model class to attach (e.g. `Order`, `Customer`) |
76
+ | `bind_to_id` | string | body | Conditional | Entity ID (required if `bind_to_type` is provided) |
77
+
78
+ #### Response
79
+
80
+ ```json
81
+ {
82
+ "data": {
83
+ "id": 4,
84
+ "value": "Returning Customer"
85
+ },
86
+ "message": "Label created successfully!"
87
+ }
88
+ ```
89
+
90
+ #### Example
91
+
92
+ ```bash
93
+ curl -X POST "https://example.com/wp-json/fluent-cart/v2/labels" \
94
+ -u "username:app_password" \
95
+ -H "Content-Type: application/json" \
96
+ -d '{
97
+ "value": "Returning Customer",
98
+ "bind_to_type": "Order",
99
+ "bind_to_id": "42"
100
+ }'
101
+ ```
102
+
103
+ ---
104
+
105
+ ### Update Label Selections
106
+
107
+ `POST /fluent-cart/v2/labels/update-label-selections`
108
+
109
+ Sync attached labels for a target entity. Labels in `selectedLabels` are attached; omitted previously attached labels are detached.
110
+
111
+ #### Permission
112
+
113
+ `labels/manage`
114
+
115
+ #### Parameters
116
+
117
+ | Parameter | Type | Location | Required | Description |
118
+ |-----------|------|----------|----------|-------------|
119
+ | `bind_to_type` | string | body | Yes | Target entity model (e.g., `Order`, `Customer`) |
120
+ | `bind_to_id` | string | body | Yes | Target entity ID |
121
+ | `selectedLabels` | array | body | No | Array of label IDs to attach |
122
+
123
+ ---
124
+
125
+ ## Attribute Groups
126
+
127
+ Attribute groups represent variation categories (e.g., Color, Size, Material).
128
+
129
+ **Prefix:** `/fluent-cart/v2/options/attr` | **Policy:** `ProductPolicy`
130
+
131
+ ### List Attribute Groups
132
+
133
+ `GET /fluent-cart/v2/options/attr/groups`
134
+
135
+ #### Permission
136
+
137
+ `products/view`
138
+
139
+ #### Parameters
140
+
141
+ | Parameter | Type | Location | Required | Description |
142
+ |-----------|------|----------|----------|-------------|
143
+ | `search` | object | query | No | Column search criteria (`title`, `slug`) |
144
+ | `filters` | object | query | No | Filter criteria (e.g., `terms_count`) |
145
+ | `with` | array | query | No | Eager load relations (e.g., `["terms"]`) |
146
+ | `order_by` | string | query | No | Sort column (`title`, `id`, `slug`, `created_at`). Default: `title` |
147
+ | `order_type` | string | query | No | Sort direction (`ASC` or `DESC`). Default: `ASC` |
148
+ | `per_page` | integer | query | No | Items per page (default: 10) |
149
+ | `page` | integer | query | No | Page number |
150
+
151
+ #### Response
152
+
153
+ ```json
154
+ {
155
+ "groups": {
156
+ "total": 3,
157
+ "per_page": 10,
158
+ "current_page": 1,
159
+ "last_page": 1,
160
+ "data": [
161
+ {
162
+ "id": 1,
163
+ "title": "Color",
164
+ "slug": "color",
165
+ "description": "Product color options",
166
+ "settings": null,
167
+ "created_at": "2025-01-10 08:30:00",
168
+ "updated_at": "2025-01-10 08:30:00",
169
+ "terms_count": 5
170
+ }
171
+ ]
172
+ }
173
+ }
174
+ ```
175
+
176
+ ---
177
+
178
+ ### Create Attribute Group
179
+
180
+ `POST /fluent-cart/v2/options/attr/group`
181
+
182
+ #### Permission
183
+
184
+ `products/create` | **Request Class:** `AttrGroupRequest`
185
+
186
+ #### Parameters
187
+
188
+ | Parameter | Type | Location | Required | Description |
189
+ |-----------|------|----------|----------|-------------|
190
+ | `title` | string | body | Yes | Group title (max 50 chars). Must be unique in `fct_atts_groups` |
191
+ | `slug` | string | body | Yes | Group slug (max 50 chars). Must be unique in `fct_atts_groups` |
192
+ | `description` | string | body | No | Group description |
193
+ | `settings` | object | body | No | Additional settings object |
194
+
195
+ ---
196
+
197
+ ### Get Attribute Group
198
+
199
+ `GET /fluent-cart/v2/options/attr/group/{group_id}`
200
+
201
+ #### Parameters
202
+
203
+ | Parameter | Type | Location | Required | Description |
204
+ |-----------|------|----------|----------|-------------|
205
+ | `group_id` | integer | path | Yes | Attribute Group ID |
206
+ | `with` | array | query | No | Eager load relations (e.g., `["terms"]`) |
207
+
208
+ ---
209
+
210
+ ### Update Attribute Group
211
+
212
+ `PUT /fluent-cart/v2/options/attr/group/{group_id}`
213
+
214
+ #### Permission
215
+
216
+ `products/edit` | **Request Class:** `AttrGroupRequest`
217
+
218
+ ---
219
+
220
+ ### Delete Attribute Group
221
+
222
+ `DELETE /fluent-cart/v2/options/attr/group/{group_id}`
223
+
224
+ #### Permission
225
+
226
+ `products/delete`
227
+
228
+ > **Delete Guard:** A group cannot be deleted if any of its terms are currently assigned to product variations. Attempting to delete an active group returns HTTP `403`: `"This group is already in use, can not be deleted."`.
229
+
230
+ ---
231
+
232
+ ## Attribute Terms
233
+
234
+ Individual variation values within an attribute group (e.g., "Red", "Blue", "Green").
235
+
236
+ **Prefix:** `/fluent-cart/v2/options/attr/group/{group_id}` | **Policy:** `ProductPolicy`
237
+
238
+ ### List Attribute Terms
239
+
240
+ `GET /fluent-cart/v2/options/attr/group/{group_id}/terms`
241
+
242
+ #### Parameters
243
+
244
+ | Parameter | Type | Location | Required | Description |
245
+ |-----------|------|----------|----------|-------------|
246
+ | `group_id` | integer | path | Yes | Parent attribute group ID |
247
+ | `search` | object | query | No | Column search (`title`, `slug`) |
248
+ | `order_by` | string | query | No | Sort column (`serial`, `title`, `id`). Default: `serial` |
249
+ | `order_type` | string | query | No | Sort direction (`ASC` or `DESC`). Default: `ASC` |
250
+ | `per_page` | integer | query | No | Items per page (default: 15) |
251
+
252
+ ---
253
+
254
+ ### Create Attribute Term
255
+
256
+ `POST /fluent-cart/v2/options/attr/group/{group_id}/term`
257
+
258
+ #### Permission
259
+
260
+ `products/create` | **Request Class:** `AttrTermRequest`
261
+
262
+ #### Parameters
263
+
264
+ | Parameter | Type | Location | Required | Description |
265
+ |-----------|------|----------|----------|-------------|
266
+ | `group_id` | integer | path | Yes | Parent attribute group ID |
267
+ | `title` | string | body | Yes | Term title (max 50 chars). Must be unique in `fct_atts_terms` |
268
+ | `slug` | string | body | Yes | Term slug (max 50 chars). Must be unique in `fct_atts_terms` |
269
+ | `description` | string | body | No | Term description |
270
+ | `serial` | integer | body | No | Sort order index (default: `10`) |
271
+
272
+ ---
273
+
274
+ ### Update Attribute Term
275
+
276
+ `POST /fluent-cart/v2/options/attr/group/{group_id}/term/{term_id}`
277
+
278
+ #### Permission
279
+
280
+ `products/edit` | **Request Class:** `AttrTermRequest`
281
+
282
+ ---
283
+
284
+ ### Delete Attribute Term
285
+
286
+ `DELETE /fluent-cart/v2/options/attr/group/{group_id}/term/{term_id}`
287
+
288
+ #### Permission
289
+
290
+ `products/delete`
291
+
292
+ > **Delete Guard:** Terms assigned to product variations return HTTP `403`: `"This term is already in use, can not be deleted."`.
293
+
294
+ ---
295
+
296
+ ### Change Term Sort Order (Serial Shift)
297
+
298
+ `POST /fluent-cart/v2/options/attr/group/{group_id}/term/{term_id}/serial`
299
+
300
+ Increments or decrements the sort order `serial` value of a term.
301
+
302
+ #### Permission
303
+
304
+ `products/edit`
305
+
306
+ #### Parameters
307
+
308
+ | Parameter | Type | Location | Required | Description |
309
+ |-----------|------|----------|----------|-------------|
310
+ | `group_id` | integer | path | Yes | Attribute group ID |
311
+ | `term_id` | integer | path | Yes | Term ID to reorder |
312
+ | `direction` | string | body | No | `up` (decrements serial, min 0) or `down` (increments serial). Default: `up` |
313
+
314
+ #### Response
315
+
316
+ ```json
317
+ {
318
+ "data": 2,
319
+ "message": "Serial updated."
320
+ }
321
+ ```
@@ -0,0 +1,171 @@
1
+ # Software Licensing API (Pro)
2
+
3
+ Comprehensive developer reference for managing software licenses in FluentCart Pro, including admin license management, per-product license rules, customer portal self-service, site license activation, and the public non-REST software update API for plugins and themes.
4
+
5
+ **Base URLs:**
6
+ - REST API: `https://your-site.com/wp-json/fluent-cart/v2`
7
+ - Public Update API (Non-REST): `https://your-site.com/?fluent-cart={action}`
8
+
9
+ **Policies:** `LicensePolicy` (Admin) / `CustomerFrontendPolicy` (Customer Portal) / `AdminPolicy` (Site License) / `PublicPolicy` (Public Update API)
10
+
11
+ ---
12
+
13
+ ## Endpoints Overview
14
+
15
+ | Group | Method | Endpoint | Authorization | Description |
16
+ |-------|--------|----------|---------------|-------------|
17
+ | **Admin Licensing** | GET | `/licensing/licenses` | `licenses/view` | List licenses with tab filters (`active`, `expired`, `disabled`, `inactive`) |
18
+ | | GET | `/licensing/licenses/customer/{id}` | `licenses/view` | List licenses for a specific customer |
19
+ | | GET | `/licensing/licenses/{id}` | `licenses/view` | Get full license details, activations, & order relation |
20
+ | | POST | `/licensing/licenses/{id}/regenerate-key` | `licenses/manage` | Generate new random key & invalidate old key |
21
+ | | POST | `/licensing/licenses/{id}/extend-validity` | `licenses/manage` | Change expiration date (`YYYY-MM-DD HH:MM:SS` or `lifetime`) |
22
+ | | POST | `/licensing/licenses/{id}/update_status` | `licenses/manage` | Change status (`active`, `disabled`, `expired`) |
23
+ | | POST | `/licensing/licenses/{id}/update_limit` | `licenses/manage` | Update max site limit (`0` or `"unlimited"`) |
24
+ | | POST | `/licensing/licenses/{id}/activate_site` | `licenses/manage` | Manually activate site URL |
25
+ | | POST | `/licensing/licenses/{id}/deactivate_site` | `licenses/manage` | Deactivate specific site activation by `activation_id` |
26
+ | | DELETE | `/licensing/licenses/{id}/delete` | `licenses/delete` | Delete software license |
27
+ | **Product Settings** | GET | `/licensing/products/{id}/settings` | `licenses/view` | Get per-product variation validity & activation rules |
28
+ | | POST | `/licensing/products/{id}/settings` | `licenses/manage` | Save per-product license configuration (Guarded for bundles) |
29
+ | **Customer Portal** | GET | `/customer-profile/licenses/` | Portal Auth | List logged-in customer's licenses (uses `license_key`) |
30
+ | | GET | `/customer-profile/licenses/{key}` | Portal Auth | Get customer license details & section parts |
31
+ | | GET | `/customer-profile/licenses/{key}/activations` | Portal Auth | List active sites (`is_local` sites don't count towards limit) |
32
+ | | POST | `/customer-profile/licenses/{key}/deactivate_site` | Portal Auth | Deactivate site from customer portal |
33
+ | **Plugin Pro License** | GET | `/settings/license/` | `AdminPolicy` | Get site's FluentCart Pro plugin license status |
34
+ | | POST | `/settings/license/` | `AdminPolicy` | Activate FluentCart Pro plugin license key on site |
35
+ | | DELETE | `/settings/license/` | `AdminPolicy` | Deactivate FluentCart Pro plugin license on site |
36
+ | **Public API (Non-REST)** | GET/POST | `/?fluent-cart=check_license` | Public | Verify license validity & activation count |
37
+ | | POST | `/?fluent-cart=activate_license` | Public | Activate site (Auto-detects staging/local sites) |
38
+ | | POST | `/?fluent-cart=deactivate_license` | Public | Deactivate site URL |
39
+ | | GET/POST | `/?fluent-cart=get_license_version` | Public | Fetch plugin/theme version, changelog, & 48h signed download package URL |
40
+ | | GET | `/?fluent-cart=download_license_package` | Public (Token) | Validates `fct_package` token & 302 redirects to file |
41
+
42
+ ---
43
+
44
+ ## 1. Admin License Management
45
+
46
+ **Prefix:** `/fluent-cart/v2/licensing/licenses` | **Policy:** `LicensePolicy`
47
+
48
+ ### List Licenses
49
+
50
+ `GET /fluent-cart/v2/licensing/licenses`
51
+
52
+ #### Parameters
53
+
54
+ | Parameter | Type | Required | Description |
55
+ |-----------|------|----------|-------------|
56
+ | `active_view` | string | No | Tab filter: `active`, `expired`, `disabled`, `inactive` |
57
+ | `search` | string | No | Search across license key, order ID, customer, activated URLs, or operator syntax (`license_key = abc`) |
58
+ | `sort_by` | string | No | Fillable column to sort by (default: `id`) |
59
+ | `sort_type` | string | No | `asc` or `desc` (default: `desc`) |
60
+ | `filter_type` | string | No | `simple` or `advanced` |
61
+ | `advanced_filters` | string (JSON) | No | JSON filter array (by product variation, customer names, status, activations count, expiration date) |
62
+ | `user_tz` | string | No | Timezone string for date filtering |
63
+
64
+ > **Status Override Note:** If a license has an `expiration_date` in the past, its status field is dynamically overridden to `expired` in the API response even if stored as `active`.
65
+
66
+ ---
67
+
68
+ ### Extend License Validity
69
+
70
+ `POST /fluent-cart/v2/licensing/licenses/{id}/extend-validity`
71
+
72
+ #### Parameters
73
+
74
+ | Parameter | Type | Required | Description |
75
+ |-----------|------|----------|-------------|
76
+ | `id` | integer | Yes | License ID |
77
+ | `expiration_date` | string | Yes | Date string (`YYYY-MM-DD HH:MM:SS`) or string `lifetime` |
78
+
79
+ > Automatically updates status to `active` if currently `inactive` or non-active.
80
+
81
+ ---
82
+
83
+ ### Product License Settings
84
+
85
+ `GET /fluent-cart/v2/licensing/products/{id}/settings`
86
+ `POST /fluent-cart/v2/licensing/products/{id}/settings`
87
+
88
+ Configures software versioning, auto-update file, WP readme/banner metadata, and variation validity rules (`unit`: `day`, `week`, `month`, `year`, `lifetime`; `value`: integer; `activation_limit`: integer/string).
89
+
90
+ > **Bundle Product Guard:** Licensing is disabled for bundle products (`is_bundle_product: true`). Bundle item licenses are generated based on each individual bundle item's license settings. Attempting to save licensing settings on a bundle product returns HTTP `422`.
91
+
92
+ ---
93
+
94
+ ## 2. Customer Portal Self-Service
95
+
96
+ Endpoints under `/fluent-cart/v2/customer-profile/licenses` identify licenses by their `license_key` string (not numeric ID).
97
+
98
+ - `GET /customer-profile/licenses/` — List customer's licenses. Returns `license_key`, `status`, `expiration_date`, `activation_count`, `limit`, `renewal_url`, `has_upgrades`.
99
+ - `GET /customer-profile/licenses/{key}` — Full details & `section_parts` extension hooks.
100
+ - `GET /customer-profile/licenses/{key}/activations` — List activated sites (`site_url`, `is_local`, `status`). `is_local: 1` sites do not count towards the activation limit.
101
+ - `POST /customer-profile/licenses/{key}/deactivate_site` — Deactivate site (`site_url`).
102
+
103
+ ---
104
+
105
+ ## 3. Public License & Software Update API (Non-REST)
106
+
107
+ Designed for distributed software (plugins, themes, desktop applications) to perform automatic updates and activation directly via query string requests.
108
+
109
+ **Base URL:** `https://your-site.com/?fluent-cart={action}`
110
+
111
+ ### Key Endpoints
112
+
113
+ #### 1. Activate License (`/?fluent-cart=activate_license`)
114
+
115
+ `POST /?fluent-cart=activate_license`
116
+
117
+ **Parameters:** `license_key`, `item_id`, `site_url`, `server_version`, `platform_version`.
118
+
119
+ > **Local & Staging Site Auto-Detection:**
120
+ > Sites matching common staging patterns are automatically assigned `is_local = 1` and do not count toward activation limits:
121
+ > - **Subdomains:** `staging.`, `dev.`, `test.`, `qa.`, `sandbox.`, `beta.`, `preview.`, `uat.`, `development.`
122
+ > - **Subfolders:** `/staging/`, `/dev/`, `/test/`
123
+ > - **Domains:** `localhost`, `.wpengine.com`, `.kinsta.cloud`, `.cloudwaysapps.com`, `.pantheonsite.io`
124
+
125
+ ---
126
+
127
+ #### 2. Get License Version (`/?fluent-cart=get_license_version`)
128
+
129
+ `GET/POST /?fluent-cart=get_license_version`
130
+
131
+ **Parameters:** `item_id`, `license_key` (or `activation_hash`), `site_url`.
132
+
133
+ Returns version metadata (`new_version`, `stable_version`, `sections.changelog`, `banners`, `icons`).
134
+ - **Valid License:** Includes `package` signed URL containing a time-limited token (**expires in 48 hours**).
135
+ - **Invalid / Expired License:** Returns version metadata but sets `package: ""` and `download_link: ""`.
136
+
137
+ ---
138
+
139
+ #### 3. Download Package (`/?fluent-cart=download_license_package`)
140
+
141
+ `GET /?fluent-cart=download_license_package&fct_package={token}`
142
+
143
+ Validates `fct_package` Base64 token and returns an HTTP `302` redirect to the actual file download payload.
144
+
145
+ ---
146
+
147
+ ## Hooks & Filters Reference
148
+
149
+ ```php
150
+ // Filter check license response payload
151
+ add_filter('fluent_cart/license/check_license_response', function($response) {
152
+ // Modify response array
153
+ return $response;
154
+ });
155
+
156
+ // Customize staging domain detection
157
+ add_filter('fluent_cart/license/staging_domains', function($domains) {
158
+ $domains[] = 'mycompany-staging.com';
159
+ return $domains;
160
+ });
161
+
162
+ // Customize license expiration grace period (default 15 days)
163
+ add_filter('fluent_cart/license/grace_period_in_days', function($days) {
164
+ return 30;
165
+ });
166
+
167
+ // Action triggered on successful site activation
168
+ add_action('fluent_cart/license/site_activated', function($activationData) {
169
+ // Handle post-activation logic
170
+ });
171
+ ```
@@ -0,0 +1,200 @@
1
+ # Order Bumps API (Pro)
2
+
3
+ Create and manage checkout order bump promotions in FluentCart Pro to offer relevant add-ons or discounted upsell products directly on the checkout form.
4
+
5
+ **Base URL:** `https://your-site.com/wp-json/fluent-cart/v2/order_bump`
6
+ **Policy:** `OrderBumpPolicy` | **Permission:** `store/sensitive` (Requires FluentCart Pro)
7
+
8
+ > All monetary values (e.g., fixed discount amounts, product prices) are in integer **cents** (`$10.00` = `1000`).
9
+
10
+ ---
11
+
12
+ ## Endpoints Overview
13
+
14
+ | Method | Endpoint | Permission | Description |
15
+ |--------|----------|------------|-------------|
16
+ | GET | `/order_bump` | `store/sensitive` | List order bumps with tab filters (`active`, `draft`) |
17
+ | POST | `/order_bump` | `store/sensitive` | Create a new order bump offer (minimal initial payload) |
18
+ | GET | `/order_bump/{id}` | `store/sensitive` | Retrieve order bump details, config, & product variant |
19
+ | PUT | `/order_bump/{id}` | `store/sensitive` | Update configuration, conditions, status, & priority |
20
+ | DELETE | `/order_bump/{id}` | `store/sensitive` | Permanently delete an order bump promotion |
21
+
22
+ ---
23
+
24
+ ## Endpoints Specification
25
+
26
+ ### 1. List Order Bumps
27
+
28
+ `GET /fluent-cart/v2/order_bump`
29
+
30
+ Retrieve a paginated list of order bumps. Each entry eagerly loads its associated `product_variant` and parent `product`.
31
+
32
+ #### Parameters
33
+
34
+ | Parameter | Type | Required | Description |
35
+ |-----------|------|----------|-------------|
36
+ | `active_view` | string | No | Filter by tab: `active` or `draft` |
37
+ | `search` | string | No | Partial title or description search |
38
+ | `sort_by` | string | No | Sort column (default: `id`) |
39
+ | `sort_type` | string | No | `asc` or `desc` (default: `desc`) |
40
+ | `page` | integer | No | Page number |
41
+ | `per_page` | integer | No | Items per page |
42
+
43
+ #### Response
44
+
45
+ ```json
46
+ {
47
+ "order_bumps": {
48
+ "total": 5,
49
+ "per_page": 15,
50
+ "current_page": 1,
51
+ "last_page": 1,
52
+ "data": [
53
+ {
54
+ "id": 1,
55
+ "hash": "a1b2c3d4e5f6...",
56
+ "type": "order_bump",
57
+ "status": "active",
58
+ "src_object_id": 42,
59
+ "title": "Add Extended Warranty",
60
+ "description": "<p>Protect your purchase with our 2-year warranty plan.</p>",
61
+ "conditions": [],
62
+ "config": {
63
+ "discount": {
64
+ "discount_type": "percentage",
65
+ "discount_amount": 10
66
+ },
67
+ "display_conditions_if": "",
68
+ "call_to_action": "Yes, add warranty!"
69
+ },
70
+ "priority": 1,
71
+ "product_variant": {
72
+ "id": 42,
73
+ "product_id": 10,
74
+ "title": "Extended Warranty - 2 Year",
75
+ "price": 2999,
76
+ "product": { "id": 10, "title": "Extended Warranty", "status": "publish" }
77
+ }
78
+ }
79
+ ]
80
+ }
81
+ }
82
+ ```
83
+
84
+ ---
85
+
86
+ ### 2. Create Order Bump
87
+
88
+ `POST /fluent-cart/v2/order_bump`
89
+
90
+ Creates an order bump with initial title and product variation ID.
91
+
92
+ #### Parameters
93
+
94
+ | Parameter | Type | Required | Description |
95
+ |-----------|------|----------|-------------|
96
+ | `title` | string | Yes | Display title for the order bump |
97
+ | `src_object_id` | integer | Yes | Product variation ID offered in the bump |
98
+
99
+ > **Auto-Generated Defaults:** Creates with `type: "order_bump"`, unique MD5 `hash`, empty `conditions: []`, and empty `config: {}`.
100
+
101
+ #### Response
102
+
103
+ ```json
104
+ {
105
+ "message": "Order bump created successfully",
106
+ "id": 5
107
+ }
108
+ ```
109
+
110
+ ---
111
+
112
+ ### 3. Get Single Order Bump
113
+
114
+ `GET /fluent-cart/v2/order_bump/{id}`
115
+
116
+ Returns the order bump configuration and its linked product variant.
117
+
118
+ #### Default Config Fallback
119
+
120
+ If no custom config has been saved yet, returns:
121
+
122
+ ```json
123
+ {
124
+ "discount": {
125
+ "discount_type": "percentage",
126
+ "discount_amount": 0
127
+ },
128
+ "display_conditions_if": "",
129
+ "call_to_action": ""
130
+ }
131
+ ```
132
+
133
+ ---
134
+
135
+ ### 4. Update Order Bump
136
+
137
+ `PUT /fluent-cart/v2/order_bump/{id}`
138
+
139
+ Update configuration, display conditions, status, and sort priority.
140
+
141
+ #### Parameters
142
+
143
+ | Parameter | Type | Required | Description |
144
+ |-----------|------|----------|-------------|
145
+ | `title` | string | Yes | Display title (max 194 chars) |
146
+ | `src_object_id` | integer | Yes | Product variation ID for the bump offer |
147
+ | `status` | string | No | `active` or `draft` (max 50 chars) |
148
+ | `src_object_type` | string | No | Source object type slug (max 50 chars) |
149
+ | `description` | string | No | HTML offer description (sanitized with `wp_kses_post`) |
150
+ | `config` | object | No | Configuration object (see structure below) |
151
+ | `conditions` | array | No | Display rule objects array |
152
+ | `priority` | integer | No | Display order (lower numbers display first, min `1`) |
153
+
154
+ #### Config Object Structure
155
+
156
+ ```json
157
+ {
158
+ "config": {
159
+ "discount": {
160
+ "discount_type": "percentage",
161
+ "discount_amount": 10
162
+ },
163
+ "display_conditions_if": "all",
164
+ "call_to_action": "Yes, add 2-year warranty to my order!"
165
+ }
166
+ }
167
+ ```
168
+
169
+ > **Discount Types:**
170
+ > - `percentage`: `discount_amount` is a number from `0` to `100`.
171
+ > - `fixed`: `discount_amount` is specified in **cents** (e.g. `500` = `$5.00`).
172
+
173
+ ---
174
+
175
+ ### 5. Delete Order Bump
176
+
177
+ `DELETE /fluent-cart/v2/order_bump/{id}`
178
+
179
+ ---
180
+
181
+ ## Data Model & Database Schema
182
+
183
+ Order bumps are stored in the `fct_order_promotions` table filtered by `type = 'order_bump'`.
184
+
185
+ | Column | Data Type | Description |
186
+ |--------|-----------|-------------|
187
+ | `id` | BIGINT (PK) | Auto-increment primary key |
188
+ | `hash` | VARCHAR | Auto-generated unique MD5 hash |
189
+ | `parent_id` | BIGINT | Parent promotion ID (nullable) |
190
+ | `type` | VARCHAR | Always `order_bump` |
191
+ | `status` | VARCHAR | `active` or `draft` |
192
+ | `src_object_id` | BIGINT | Product variation ID (`fct_product_variations.id`) |
193
+ | `src_object_type` | VARCHAR | Identifier type |
194
+ | `title` | VARCHAR | Display title |
195
+ | `description` | TEXT | HTML description |
196
+ | `conditions` | TEXT (JSON) | JSON array of display rule conditions |
197
+ | `config` | TEXT (JSON) | JSON object containing discount & CTA text |
198
+ | `priority` | INT | Sort ordering index |
199
+ | `created_at` | DATETIME | GMT creation timestamp |
200
+ | `updated_at` | DATETIME | GMT update timestamp |