fluentcart-developer 2.3.0 → 2.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/README.md +59 -59
  2. package/dist/cards/fluentcart/tools.d.ts.map +1 -1
  3. package/dist/cards/fluentcart/tools.js +160 -12
  4. package/dist/cards/fluentcart/tools.js.map +1 -1
  5. package/dist/skills/fluentcart-developer/.claude-plugin/plugin.json +12 -12
  6. package/dist/skills/fluentcart-developer/.mcp.json +11 -11
  7. package/dist/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/fluent-cart/checkout.php +32 -32
  8. package/dist/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/functions.php +40 -40
  9. package/dist/skills/fluentcart-developer/examples/sample-fee-surcharge-plugin/fluentcart-fee-surcharge.php +38 -38
  10. package/dist/skills/fluentcart-developer/references/action-hooks-cart-checkout.md +1355 -1355
  11. package/dist/skills/fluentcart-developer/references/action-hooks-customers-users.md +266 -266
  12. package/dist/skills/fluentcart-developer/references/action-hooks-licenses.md +855 -855
  13. package/dist/skills/fluentcart-developer/references/action-hooks-orders.md +631 -631
  14. package/dist/skills/fluentcart-developer/references/action-hooks-payments-integrations.md +963 -963
  15. package/dist/skills/fluentcart-developer/references/action-hooks-products-coupons.md +585 -585
  16. package/dist/skills/fluentcart-developer/references/action-hooks-subscriptions.md +661 -661
  17. package/dist/skills/fluentcart-developer/references/database-models-query-builder.md +194 -194
  18. package/dist/skills/fluentcart-developer/references/database-models-reference.md +604 -604
  19. package/dist/skills/fluentcart-developer/references/engineering-notes.md +154 -154
  20. package/dist/skills/fluentcart-developer/references/fee-system-guide.md +449 -449
  21. package/dist/skills/fluentcart-developer/references/filter-hooks-cart-checkout.md +1202 -1202
  22. package/dist/skills/fluentcart-developer/references/filter-hooks-integrations-advanced.md +1598 -1598
  23. package/dist/skills/fluentcart-developer/references/filter-hooks-products-pricing.md +628 -628
  24. package/dist/skills/fluentcart-developer/references/filter-hooks-settings-configuration.md +1177 -1177
  25. package/dist/skills/fluentcart-developer/references/fluentcart-developer-guide.md +154 -154
  26. package/dist/skills/fluentcart-developer/references/ghost-product-selling.md +458 -458
  27. package/dist/skills/fluentcart-developer/references/modules-and-extensions-reference.md +224 -224
  28. package/dist/skills/fluentcart-developer/references/payment-gateway-integration.md +761 -761
  29. package/dist/skills/fluentcart-developer/references/rest-api-customer-profile.md +190 -190
  30. package/dist/skills/fluentcart-developer/references/rest-api-customers.md +1121 -1121
  31. package/dist/skills/fluentcart-developer/references/rest-api-dashboard-utilities.md +219 -219
  32. package/dist/skills/fluentcart-developer/references/rest-api-email-notifications.md +619 -619
  33. package/dist/skills/fluentcart-developer/references/rest-api-files.md +290 -290
  34. package/dist/skills/fluentcart-developer/references/rest-api-integrations.md +324 -324
  35. package/dist/skills/fluentcart-developer/references/rest-api-labels-attributes.md +321 -321
  36. package/dist/skills/fluentcart-developer/references/rest-api-order-bumps.md +200 -200
  37. package/dist/skills/fluentcart-developer/references/rest-api-overview.md +131 -131
  38. package/dist/skills/fluentcart-developer/references/rest-api-public-shop.md +172 -172
  39. package/dist/skills/fluentcart-developer/references/rest-api-reference.md +552 -552
  40. package/dist/skills/fluentcart-developer/references/rest-api-reports.md +377 -377
  41. package/dist/skills/fluentcart-developer/references/rest-api-roles-permissions.md +147 -147
  42. package/dist/skills/fluentcart-developer/references/rest-api-settings.md +528 -528
  43. package/dist/skills/fluentcart-developer/references/rest-api-shipping.md +799 -799
  44. package/dist/skills/fluentcart-developer/references/rest-api-tax.md +356 -356
  45. package/dist/skills/fluentcart-developer/references/subscription-customization.md +197 -197
  46. package/dist/skills/fluentcart-developer/scripts/cli.js +1 -1
  47. package/dist/version.d.ts +1 -1
  48. package/dist/version.js +1 -1
  49. package/package.json +65 -65
@@ -1,200 +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 |
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 |
@@ -1,131 +1,131 @@
1
- # FluentCart REST API
2
-
3
- Complete REST API reference for FluentCart and FluentCart Pro. This documentation covers 367+ endpoints organized by module, with full parameter details, response examples, and authentication guides.
4
-
5
- ---
6
-
7
- ## Getting Started
8
-
9
- **Base URL:** `https://your-site.com/wp-json/fluent-cart/v2`
10
-
11
- All admin endpoints require authentication. Public and customer portal endpoints have different authentication requirements as noted in each module.
12
-
13
- ### Authentication
14
-
15
- **Admin API** — Use WordPress Application Passwords (HTTP Basic Auth):
16
-
17
- 1. Go to WordPress Dashboard → Users → Your Profile
18
- 2. Scroll to Application Passwords section
19
- 3. Create a new application password
20
- 4. Use the credentials with every request:
21
-
22
- ```bash
23
- curl -X GET "https://your-site.com/wp-json/fluent-cart/v2/orders" \
24
- -u "username:application_password"
25
- ```
26
-
27
- **Customer Portal API** — Uses WordPress cookie-based authentication with nonce verification:
28
-
29
- ```bash
30
- curl -X GET "https://your-site.com/wp-json/fluent-cart/v2/customer-profile/" \
31
- -H "X-WP-Nonce: <nonce>" \
32
- --cookie "wordpress_logged_in_xxx=..."
33
- ```
34
-
35
- **Public API** — No authentication required.
36
-
37
- ### Conventions
38
-
39
- - All monetary values are in **cents** (e.g., `$10.00` = `1000`). Use integer arithmetic.
40
- - All timestamps are in **UTC/GMT**.
41
- - Pagination uses `page` and `per_page` parameters (default: `per_page=10`).
42
- - Responses use standard HTTP status codes (`200`, `400`, `403`, `404`, `422`).
43
- - The REST namespace is `fluent-cart/v2`.
44
-
45
- ---
46
-
47
- ## API Modules
48
-
49
- ### Core Resources
50
-
51
- | Module | Endpoints | Description |
52
- |--------|-----------|-------------|
53
- | Orders | 22 | Order CRUD, payments, refunds, shipping, fulfillment, notes, transactions |
54
- | Products | 59 | Product CRUD, variations, attributes, downloadables, pricing, bundles |
55
- | Customers | 18 | Customer CRUD, addresses, WordPress user association, notes |
56
- | Coupons | 12 | Coupon CRUD, validation, usage tracking |
57
- | Subscriptions | 17 | Subscription lifecycle, billing, cancellations, payment method management |
58
-
59
- ### Configuration
60
-
61
- | Module | Endpoints | Description |
62
- |--------|-----------|-------------|
63
- | Tax | 26 | Tax classes, rates, EU VAT, configuration |
64
- | Shipping | 15 | Shipping zones, methods, classes |
65
- | Settings | 30 | Store settings, payment methods, modules, storage, permissions, checkout fields |
66
- | Email Notifications | 11 | Email template management, previews, test sending |
67
-
68
- ### Analytics & Content
69
-
70
- | Module | Endpoints | Description |
71
- |--------|-----------|-------------|
72
- | Reports | 45 | Revenue, orders, sales, refunds, subscriptions, dashboards, retention |
73
- | Integrations | 17 | Add-ons, global feeds, product integration feeds |
74
- | Files | 5 | File uploads, storage management, editor uploads |
75
- | Labels & Attributes | 13 | Product labels, attribute groups, attribute terms |
76
- | Dashboard | 20 | Dashboard stats, onboarding, activity log, print templates, widgets |
77
-
78
- ### Storefront & Checkout
79
-
80
- | Module | Endpoints | Description |
81
- |--------|-----------|-------------|
82
- | Public Shop | 3 | Public product listing, search, server-rendered views |
83
- | Checkout | 7 | Order placement, payment processing, shipping methods, country info |
84
- | Customer Profile | 21 | Customer portal — orders, downloads, addresses, profile management |
85
-
86
- ### Pro Features
87
-
88
- | Module | Endpoints | Description |
89
- |--------|-----------|-------------|
90
- | Licensing | 24 | License management, activations, public license API, WordPress update API |
91
- | Roles & Permissions | 7 | FluentCart role assignment and management |
92
- | Order Bumps | 5 | Order bump CRUD with display conditions |
93
-
94
- ---
95
-
96
- ## Permission System
97
-
98
- FluentCart uses a policy-based authorization system with 32 granular permissions across 4 built-in roles:
99
-
100
- | Role | Description |
101
- |------|-------------|
102
- | `super_admin` | Full access to all features |
103
- | `manager` | Manage orders, customers, products, and settings |
104
- | `worker` | Day-to-day operations — orders, customers, products |
105
- | `accountant` | Read-only access to orders, customers, and reports |
106
-
107
- Each endpoint documents its required permission (e.g., `orders/view`, `products/edit`, `store/sensitive`).
108
-
109
- ---
110
-
111
- ## Error Handling
112
-
113
- All error responses follow a consistent format:
114
-
115
- ```json
116
- {
117
- "message": "Error description",
118
- "errors": {
119
- "field_name": ["Validation error message"]
120
- }
121
- }
122
- ```
123
-
124
- | Status Code | Meaning |
125
- |-------------|---------|
126
- | `200` | Success |
127
- | `400` | Bad Request — validation failed or invalid parameters |
128
- | `403` | Forbidden — insufficient permissions |
129
- | `404` | Not Found — resource does not exist |
130
- | `422` | Unprocessable Entity — business logic error |
131
- | `429` | Too Many Requests — rate limited |
1
+ # FluentCart REST API
2
+
3
+ Complete REST API reference for FluentCart and FluentCart Pro. This documentation covers 367+ endpoints organized by module, with full parameter details, response examples, and authentication guides.
4
+
5
+ ---
6
+
7
+ ## Getting Started
8
+
9
+ **Base URL:** `https://your-site.com/wp-json/fluent-cart/v2`
10
+
11
+ All admin endpoints require authentication. Public and customer portal endpoints have different authentication requirements as noted in each module.
12
+
13
+ ### Authentication
14
+
15
+ **Admin API** — Use WordPress Application Passwords (HTTP Basic Auth):
16
+
17
+ 1. Go to WordPress Dashboard → Users → Your Profile
18
+ 2. Scroll to Application Passwords section
19
+ 3. Create a new application password
20
+ 4. Use the credentials with every request:
21
+
22
+ ```bash
23
+ curl -X GET "https://your-site.com/wp-json/fluent-cart/v2/orders" \
24
+ -u "username:application_password"
25
+ ```
26
+
27
+ **Customer Portal API** — Uses WordPress cookie-based authentication with nonce verification:
28
+
29
+ ```bash
30
+ curl -X GET "https://your-site.com/wp-json/fluent-cart/v2/customer-profile/" \
31
+ -H "X-WP-Nonce: <nonce>" \
32
+ --cookie "wordpress_logged_in_xxx=..."
33
+ ```
34
+
35
+ **Public API** — No authentication required.
36
+
37
+ ### Conventions
38
+
39
+ - All monetary values are in **cents** (e.g., `$10.00` = `1000`). Use integer arithmetic.
40
+ - All timestamps are in **UTC/GMT**.
41
+ - Pagination uses `page` and `per_page` parameters (default: `per_page=10`).
42
+ - Responses use standard HTTP status codes (`200`, `400`, `403`, `404`, `422`).
43
+ - The REST namespace is `fluent-cart/v2`.
44
+
45
+ ---
46
+
47
+ ## API Modules
48
+
49
+ ### Core Resources
50
+
51
+ | Module | Endpoints | Description |
52
+ |--------|-----------|-------------|
53
+ | Orders | 22 | Order CRUD, payments, refunds, shipping, fulfillment, notes, transactions |
54
+ | Products | 59 | Product CRUD, variations, attributes, downloadables, pricing, bundles |
55
+ | Customers | 18 | Customer CRUD, addresses, WordPress user association, notes |
56
+ | Coupons | 12 | Coupon CRUD, validation, usage tracking |
57
+ | Subscriptions | 17 | Subscription lifecycle, billing, cancellations, payment method management |
58
+
59
+ ### Configuration
60
+
61
+ | Module | Endpoints | Description |
62
+ |--------|-----------|-------------|
63
+ | Tax | 26 | Tax classes, rates, EU VAT, configuration |
64
+ | Shipping | 15 | Shipping zones, methods, classes |
65
+ | Settings | 30 | Store settings, payment methods, modules, storage, permissions, checkout fields |
66
+ | Email Notifications | 11 | Email template management, previews, test sending |
67
+
68
+ ### Analytics & Content
69
+
70
+ | Module | Endpoints | Description |
71
+ |--------|-----------|-------------|
72
+ | Reports | 45 | Revenue, orders, sales, refunds, subscriptions, dashboards, retention |
73
+ | Integrations | 17 | Add-ons, global feeds, product integration feeds |
74
+ | Files | 5 | File uploads, storage management, editor uploads |
75
+ | Labels & Attributes | 13 | Product labels, attribute groups, attribute terms |
76
+ | Dashboard | 20 | Dashboard stats, onboarding, activity log, print templates, widgets |
77
+
78
+ ### Storefront & Checkout
79
+
80
+ | Module | Endpoints | Description |
81
+ |--------|-----------|-------------|
82
+ | Public Shop | 3 | Public product listing, search, server-rendered views |
83
+ | Checkout | 7 | Order placement, payment processing, shipping methods, country info |
84
+ | Customer Profile | 21 | Customer portal — orders, downloads, addresses, profile management |
85
+
86
+ ### Pro Features
87
+
88
+ | Module | Endpoints | Description |
89
+ |--------|-----------|-------------|
90
+ | Licensing | 24 | License management, activations, public license API, WordPress update API |
91
+ | Roles & Permissions | 7 | FluentCart role assignment and management |
92
+ | Order Bumps | 5 | Order bump CRUD with display conditions |
93
+
94
+ ---
95
+
96
+ ## Permission System
97
+
98
+ FluentCart uses a policy-based authorization system with 32 granular permissions across 4 built-in roles:
99
+
100
+ | Role | Description |
101
+ |------|-------------|
102
+ | `super_admin` | Full access to all features |
103
+ | `manager` | Manage orders, customers, products, and settings |
104
+ | `worker` | Day-to-day operations — orders, customers, products |
105
+ | `accountant` | Read-only access to orders, customers, and reports |
106
+
107
+ Each endpoint documents its required permission (e.g., `orders/view`, `products/edit`, `store/sensitive`).
108
+
109
+ ---
110
+
111
+ ## Error Handling
112
+
113
+ All error responses follow a consistent format:
114
+
115
+ ```json
116
+ {
117
+ "message": "Error description",
118
+ "errors": {
119
+ "field_name": ["Validation error message"]
120
+ }
121
+ }
122
+ ```
123
+
124
+ | Status Code | Meaning |
125
+ |-------------|---------|
126
+ | `200` | Success |
127
+ | `400` | Bad Request — validation failed or invalid parameters |
128
+ | `403` | Forbidden — insufficient permissions |
129
+ | `404` | Not Found — resource does not exist |
130
+ | `422` | Unprocessable Entity — business logic error |
131
+ | `429` | Too Many Requests — rate limited |