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.
- package/.gitattributes +2 -0
- package/CLAUDE.md +22 -0
- package/CONTRIBUTING.md +73 -0
- package/LICENSE +21 -0
- package/README.md +127 -0
- package/SKILL.md +127 -0
- package/bin/index.js +281 -0
- package/copy-skills.js +43 -0
- package/package.json +38 -0
- package/skills/fluentcart-developer/SKILL.md +172 -0
- package/skills/fluentcart-developer/examples/README.md +25 -0
- package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/fluent-cart/checkout.php +32 -0
- package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/functions.php +40 -0
- package/skills/fluentcart-developer/examples/sample-custom-addon/fluentcart-custom-addon.php +114 -0
- package/skills/fluentcart-developer/examples/sample-custom-payment-gateway/fluentcart-custom-gateway-example.php +149 -0
- package/skills/fluentcart-developer/examples/sample-fee-surcharge-plugin/fluentcart-fee-surcharge.php +38 -0
- package/skills/fluentcart-developer/examples/sample-shipping-carrier/fluentcart-custom-shipping-carrier.php +62 -0
- package/skills/fluentcart-developer/references/action-hooks-admin-templates.md +787 -0
- package/skills/fluentcart-developer/references/action-hooks-cart-checkout.md +1355 -0
- package/skills/fluentcart-developer/references/action-hooks-customers-users.md +266 -0
- package/skills/fluentcart-developer/references/action-hooks-licenses.md +855 -0
- package/skills/fluentcart-developer/references/action-hooks-orders.md +631 -0
- package/skills/fluentcart-developer/references/action-hooks-payments-integrations.md +963 -0
- package/skills/fluentcart-developer/references/action-hooks-products-coupons.md +585 -0
- package/skills/fluentcart-developer/references/action-hooks-subscriptions.md +661 -0
- package/skills/fluentcart-developer/references/database-models-query-builder.md +194 -0
- package/skills/fluentcart-developer/references/database-models-reference.md +604 -0
- package/skills/fluentcart-developer/references/database-schema-reference.md +940 -0
- package/skills/fluentcart-developer/references/engineering-notes.md +154 -0
- package/skills/fluentcart-developer/references/fee-system-guide.md +449 -0
- package/skills/fluentcart-developer/references/filter-hooks-cart-checkout.md +1202 -0
- package/skills/fluentcart-developer/references/filter-hooks-customers-subscriptions.md +902 -0
- package/skills/fluentcart-developer/references/filter-hooks-integrations-advanced.md +1598 -0
- package/skills/fluentcart-developer/references/filter-hooks-orders-payments.md +1319 -0
- package/skills/fluentcart-developer/references/filter-hooks-products-pricing.md +628 -0
- package/skills/fluentcart-developer/references/filter-hooks-settings-configuration.md +1177 -0
- package/skills/fluentcart-developer/references/fluentcart-developer-guide.md +154 -0
- package/skills/fluentcart-developer/references/ghost-product-selling.md +458 -0
- package/skills/fluentcart-developer/references/modules-and-extensions-reference.md +224 -0
- package/skills/fluentcart-developer/references/paddle-gateway-case-study.md +1925 -0
- package/skills/fluentcart-developer/references/payment-gateway-integration.md +761 -0
- package/skills/fluentcart-developer/references/rest-api-checkout.md +286 -0
- package/skills/fluentcart-developer/references/rest-api-coupons.md +794 -0
- package/skills/fluentcart-developer/references/rest-api-customer-profile.md +190 -0
- package/skills/fluentcart-developer/references/rest-api-customers.md +1121 -0
- package/skills/fluentcart-developer/references/rest-api-dashboard-utilities.md +219 -0
- package/skills/fluentcart-developer/references/rest-api-email-notifications.md +619 -0
- package/skills/fluentcart-developer/references/rest-api-files.md +290 -0
- package/skills/fluentcart-developer/references/rest-api-integrations.md +324 -0
- package/skills/fluentcart-developer/references/rest-api-labels-attributes.md +321 -0
- package/skills/fluentcart-developer/references/rest-api-licensing.md +171 -0
- package/skills/fluentcart-developer/references/rest-api-order-bumps.md +200 -0
- package/skills/fluentcart-developer/references/rest-api-orders.md +1241 -0
- package/skills/fluentcart-developer/references/rest-api-overview.md +131 -0
- package/skills/fluentcart-developer/references/rest-api-products.md +2563 -0
- package/skills/fluentcart-developer/references/rest-api-public-shop.md +172 -0
- package/skills/fluentcart-developer/references/rest-api-reference.md +552 -0
- package/skills/fluentcart-developer/references/rest-api-reports.md +377 -0
- package/skills/fluentcart-developer/references/rest-api-roles-permissions.md +147 -0
- package/skills/fluentcart-developer/references/rest-api-settings.md +528 -0
- package/skills/fluentcart-developer/references/rest-api-shipping.md +800 -0
- package/skills/fluentcart-developer/references/rest-api-subscriptions.md +606 -0
- package/skills/fluentcart-developer/references/rest-api-tax.md +356 -0
- package/skills/fluentcart-developer/references/subscription-customization.md +197 -0
- package/skills/fluentcart-developer/scripts/cli.js +1 -0
- 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 |
|