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,377 @@
|
|
|
1
|
+
# Reports API
|
|
2
|
+
|
|
3
|
+
Access comprehensive sales analytics, revenue data, order statistics, customer insights, subscription metrics, cohort retention, and product performance reports in FluentCart.
|
|
4
|
+
|
|
5
|
+
**Base URL:** `https://your-site.com/wp-json/fluent-cart/v2/reports`
|
|
6
|
+
**Policy:** `ReportPolicy`
|
|
7
|
+
**Permission:** `reports/view` (accessible to `super_admin`, `manager`, and `accountant` roles)
|
|
8
|
+
|
|
9
|
+
> **Monetary Values & Decimal Variations:** All monetary values are in **cents** unless specifically noted (e.g., `sales-growth-chart`, `get-recent-orders`, and `future_installments` return values formatted in dollars decimal). Pro license unlocks custom date ranges; free plan defaults to the last 30 days.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## Standard Report Parameters
|
|
14
|
+
|
|
15
|
+
Most report GET endpoints process query parameters via `ReportHelper::processParams()` using the nested `params[...]` object.
|
|
16
|
+
|
|
17
|
+
| Parameter | Type | Required | Description |
|
|
18
|
+
|-----------|------|----------|-------------|
|
|
19
|
+
| `params[startDate]` | string | No | Start date for report period (`YYYY-MM-DD`). Defaults to 30 days ago |
|
|
20
|
+
| `params[endDate]` | string | No | End date for report period (`YYYY-MM-DD`). Defaults to today |
|
|
21
|
+
| `params[groupKey]` | string | No | Grouping interval: `default` (auto), `daily`, `monthly`, `yearly`, `billing_country`, `shipping_country`, `payment_method`, `payment_status` |
|
|
22
|
+
| `params[currency]` | string | No | Currency code (e.g. `USD`). Defaults to store currency |
|
|
23
|
+
| `params[filterMode]` | string | No | Mode filter: `live` or `test`. Defaults to store setting |
|
|
24
|
+
| `params[variation_ids]` | array | No | Product variation IDs array to filter containing orders |
|
|
25
|
+
| `params[compareType]` | string | No | Comparison period: `previous_period`, `previous_month`, `previous_quarter`, `previous_year`, `custom` |
|
|
26
|
+
| `params[compareDate]` | string | No | Custom comparison start date (required when `compareType` is `custom`) |
|
|
27
|
+
| `params[paymentStatus]` | array | No | Auto-set to report-eligible statuses (`paid`, `partially-paid`, `refunded`, `partially-refunded`) |
|
|
28
|
+
| `params[orderTypes]` | array | No | Filter by order type (`one-time`, `subscription`) |
|
|
29
|
+
| `params[orderStatus]` | array | No | Order status filter (excluding `on-hold` & `failed` by default) |
|
|
30
|
+
| `params[subscriptionType]` | string | No | Subscription type filter (defaults to `subscription`) |
|
|
31
|
+
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## Endpoints Overview
|
|
35
|
+
|
|
36
|
+
| Group | Method | Endpoint | Description |
|
|
37
|
+
|-------|--------|----------|-------------|
|
|
38
|
+
| **Overview** | GET | `/reports/overview` | 12-month YoY revenue breakdown & top countries |
|
|
39
|
+
| **General Reports** | GET | `/reports/fetch-report-meta` | Store currencies, min_date, and store mode |
|
|
40
|
+
| | GET | `/reports/quick-order-stats` | Quick summary stats with date range shortcut |
|
|
41
|
+
| | GET | `/reports/sales-growth` | Sales growth over custom date range |
|
|
42
|
+
| | GET | `/reports/report-overview` | Aggregated order summary & payment method breakdown |
|
|
43
|
+
| | GET | `/reports/search-repeat-customer` | Search & paginate repeat customer profiles |
|
|
44
|
+
| | GET | `/reports/top-products-sold` | Top products sold via Resource API layer |
|
|
45
|
+
| **Revenue Reports** | GET | `/reports/revenue` | Grouped gross/net revenue with period comparisons |
|
|
46
|
+
| | GET | `/reports/revenue-by-group` | Revenue grouped by country, gateway, or status |
|
|
47
|
+
| **Order Reports** | GET | `/reports/order-value-distribution` | Price range order value breakdown |
|
|
48
|
+
| | GET | `/reports/fetch-new-vs-returning-customer` | New vs. returning customer order ratio |
|
|
49
|
+
| | GET | `/reports/fetch-order-by-group` | Orders grouped by gateway, country, or status |
|
|
50
|
+
| | GET | `/reports/fetch-report-by-day-and-hour` | Heatmap matrix of orders by day of week & hour |
|
|
51
|
+
| | GET | `/reports/item-count-distribution` | Distribution of order volume by item counts |
|
|
52
|
+
| | GET | `/reports/order-completion-time` | Order processing & completion time analytics |
|
|
53
|
+
| | GET | `/reports/order-chart` | Time-series order count chart with comparison |
|
|
54
|
+
| **Sales Reports** | GET | `/reports/sales-report` | Complete sales metrics (revenue, orders, items) |
|
|
55
|
+
| | GET | `/reports/fetch-top-sold-products` | Best-selling products ranking |
|
|
56
|
+
| | GET | `/reports/fetch-top-sold-variants` | Best-selling product variations ranking |
|
|
57
|
+
| **Refund Reports** | GET | `/reports/refund-chart` | Time-series refund metrics & summary |
|
|
58
|
+
| | GET | `/reports/weeks-between-refund` | Weeks elapsed between order placement & refund |
|
|
59
|
+
| | GET | `/reports/refund-data-by-group` | Refund statistics grouped by gateway or country |
|
|
60
|
+
| **License Reports** | GET | `/reports/license-chart` | Software license issuance time-series chart |
|
|
61
|
+
| | GET | `/reports/license-pie-chart` | License status distribution (active, expired, revoked) |
|
|
62
|
+
| | GET | `/reports/license-summary` | Overall license issuance & activation metrics |
|
|
63
|
+
| **Dashboard** | GET | `/reports/dashboard-stats` | Summary cards (orders, items, paid value in cents) |
|
|
64
|
+
| | GET | `/reports/sales-growth-chart` | Net revenue growth chart (in dollars decimal) |
|
|
65
|
+
| | GET | `/reports/country-heat-map` | Country distribution for world map visualization |
|
|
66
|
+
| | GET | `/reports/get-recent-orders` | 10 most recent orders (total in dollars decimal) |
|
|
67
|
+
| | GET | `/reports/get-recent-activities` | 10 most recent activity log entries |
|
|
68
|
+
| | GET | `/reports/get-dashboard-summary` | Product catalog & coupon counts summary |
|
|
69
|
+
| **Subscriptions** | GET | `/reports/subscription-chart` | MRR growth & future installment projections |
|
|
70
|
+
| | GET | `/reports/daily-signups` | Daily subscription signup counts |
|
|
71
|
+
| | GET | `/reports/retention-chart` | Subscription subscriber retention chart |
|
|
72
|
+
| | GET | `/reports/future-renewals` | Projected future subscription renewals |
|
|
73
|
+
| | GET | `/reports/subscription-retention` | Billing period retention rate metrics |
|
|
74
|
+
| | GET | `/reports/subscription-cohorts` | Monthly/yearly cohort retention matrix |
|
|
75
|
+
| **Snapshots** | POST | `/reports/retention-snapshots/generate` | Trigger background/sync retention snapshot calculation |
|
|
76
|
+
| | GET | `/reports/retention-snapshots/status` | Poll retention snapshot job status |
|
|
77
|
+
| **Product/Customer** | GET | `/reports/product-report` | Product performance time-series & summary |
|
|
78
|
+
| | GET | `/reports/product-performance` | Ranked product performance chart |
|
|
79
|
+
| | GET | `/reports/customer-report` | Customer acquisition & retention time-series |
|
|
80
|
+
| | GET | `/reports/sources` | UTM attribution & order traffic source report |
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
## Overview & General Reports
|
|
85
|
+
|
|
86
|
+
### Get Revenue Overview
|
|
87
|
+
|
|
88
|
+
`GET /fluent-cart/v2/reports/overview`
|
|
89
|
+
|
|
90
|
+
Year-over-year revenue comparison for the last 12 months vs. prior year. (Covers 30 months of data internally to build 12-month YoY metrics). Top country data is limited to top 5 countries.
|
|
91
|
+
|
|
92
|
+
> **Calculation Rules:**
|
|
93
|
+
> - Gross Revenue = `total_paid`
|
|
94
|
+
> - Net Revenue = `total_paid - total_refund - tax_total - shipping_tax`
|
|
95
|
+
|
|
96
|
+
#### Response
|
|
97
|
+
|
|
98
|
+
```json
|
|
99
|
+
{
|
|
100
|
+
"data": {
|
|
101
|
+
"gross_revenue": {
|
|
102
|
+
"2025-01": {
|
|
103
|
+
"current": 500000,
|
|
104
|
+
"prev": 350000,
|
|
105
|
+
"yoy_growth": "42.86"
|
|
106
|
+
}
|
|
107
|
+
},
|
|
108
|
+
"gross_revenue_quarterly": {
|
|
109
|
+
"Q1-2025": {
|
|
110
|
+
"current": 1500000,
|
|
111
|
+
"prev_year": 1200000,
|
|
112
|
+
"yy_growth": "25.00"
|
|
113
|
+
}
|
|
114
|
+
},
|
|
115
|
+
"gross_summary": {
|
|
116
|
+
"total": 6000000,
|
|
117
|
+
"total_prev": 4800000,
|
|
118
|
+
"yoy_growth": "25.00"
|
|
119
|
+
},
|
|
120
|
+
"top_country_net": {
|
|
121
|
+
"by_month": {
|
|
122
|
+
"2025-01": { "US": 300000, "GB": 150000 }
|
|
123
|
+
},
|
|
124
|
+
"by_countries": { "US": 3600000, "GB": 1800000 }
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
---
|
|
131
|
+
|
|
132
|
+
### Get Quick Order Stats
|
|
133
|
+
|
|
134
|
+
`GET /fluent-cart/v2/reports/quick-order-stats`
|
|
135
|
+
|
|
136
|
+
#### Parameters
|
|
137
|
+
|
|
138
|
+
| Parameter | Type | Location | Required | Description |
|
|
139
|
+
|-----------|------|----------|----------|-------------|
|
|
140
|
+
| `day_range` | string | query | No | Range shortcut (e.g., `-7 days`, `-30 days`, `this_month`, `all_time`). Default: `-0 days` (today) |
|
|
141
|
+
|
|
142
|
+
---
|
|
143
|
+
|
|
144
|
+
### Search Repeat Customers
|
|
145
|
+
|
|
146
|
+
`GET /fluent-cart/v2/reports/search-repeat-customer`
|
|
147
|
+
|
|
148
|
+
#### Parameters
|
|
149
|
+
|
|
150
|
+
| Parameter | Type | Location | Required | Description |
|
|
151
|
+
|-----------|------|----------|----------|-------------|
|
|
152
|
+
| `params[per_page]` | integer | query | No | Items per page (default: 15) |
|
|
153
|
+
| `params[current_page]` | integer | query | No | Current page number |
|
|
154
|
+
|
|
155
|
+
---
|
|
156
|
+
|
|
157
|
+
## Revenue & Order Reports
|
|
158
|
+
|
|
159
|
+
### Get Revenue Data
|
|
160
|
+
|
|
161
|
+
`GET /fluent-cart/v2/reports/revenue`
|
|
162
|
+
|
|
163
|
+
Uses Standard Report Parameters to calculate gross/net revenue time-series and period fluctuations.
|
|
164
|
+
|
|
165
|
+
#### Response
|
|
166
|
+
|
|
167
|
+
```json
|
|
168
|
+
{
|
|
169
|
+
"revenueReport": [
|
|
170
|
+
{
|
|
171
|
+
"year": "2025",
|
|
172
|
+
"group": "2025-01",
|
|
173
|
+
"gross_revenue": 500000,
|
|
174
|
+
"net_revenue": 450000,
|
|
175
|
+
"orders": 45
|
|
176
|
+
}
|
|
177
|
+
],
|
|
178
|
+
"summary": {
|
|
179
|
+
"gross_revenue": 6000000,
|
|
180
|
+
"net_revenue": 5400000,
|
|
181
|
+
"total_orders": 540
|
|
182
|
+
},
|
|
183
|
+
"fluctuations": {
|
|
184
|
+
"gross_revenue": {
|
|
185
|
+
"value": 25.0,
|
|
186
|
+
"direction": "up"
|
|
187
|
+
}
|
|
188
|
+
},
|
|
189
|
+
"appliedGroupKey": "monthly"
|
|
190
|
+
}
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
---
|
|
194
|
+
|
|
195
|
+
### Get Day and Hour Heatmap
|
|
196
|
+
|
|
197
|
+
`GET /fluent-cart/v2/reports/fetch-report-by-day-and-hour`
|
|
198
|
+
|
|
199
|
+
Returns day-of-week (0-6) and hour-of-day (0-23) matrix data for order density heatmaps.
|
|
200
|
+
|
|
201
|
+
---
|
|
202
|
+
|
|
203
|
+
## Dashboard Reports
|
|
204
|
+
|
|
205
|
+
### Get Dashboard Stats
|
|
206
|
+
|
|
207
|
+
`GET /fluent-cart/v2/reports/dashboard-stats`
|
|
208
|
+
|
|
209
|
+
#### Response
|
|
210
|
+
|
|
211
|
+
```json
|
|
212
|
+
{
|
|
213
|
+
"dashBoardStats": {
|
|
214
|
+
"total_orders": {
|
|
215
|
+
"title": "All Orders",
|
|
216
|
+
"icon": "AllOrdersIcon",
|
|
217
|
+
"current_count": 540,
|
|
218
|
+
"compare_count": 480
|
|
219
|
+
},
|
|
220
|
+
"paid_orders": {
|
|
221
|
+
"title": "Paid Orders",
|
|
222
|
+
"icon": "Money",
|
|
223
|
+
"current_count": 520,
|
|
224
|
+
"compare_count": 460
|
|
225
|
+
},
|
|
226
|
+
"total_paid_order_items": {
|
|
227
|
+
"title": "Paid Order Items",
|
|
228
|
+
"icon": "OrderItemsIcon",
|
|
229
|
+
"current_count": 1200,
|
|
230
|
+
"compare_count": 1050
|
|
231
|
+
},
|
|
232
|
+
"total_paid_amounts": {
|
|
233
|
+
"title": "Order Value (Paid)",
|
|
234
|
+
"icon": "OrderValueIcon",
|
|
235
|
+
"current_count": 6000000,
|
|
236
|
+
"compare_count": 5200000,
|
|
237
|
+
"is_cents": true
|
|
238
|
+
}
|
|
239
|
+
}
|
|
240
|
+
}
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
---
|
|
244
|
+
|
|
245
|
+
### Get Sales Growth Chart (Decimal Dollars)
|
|
246
|
+
|
|
247
|
+
`GET /fluent-cart/v2/reports/sales-growth-chart`
|
|
248
|
+
|
|
249
|
+
> **Note:** Net revenue in this response is returned in **decimal dollars**, not cents (`(total_paid - total_refund - tax_total - shipping_tax) / 100`).
|
|
250
|
+
|
|
251
|
+
```json
|
|
252
|
+
{
|
|
253
|
+
"salesGrowthChart": [
|
|
254
|
+
{
|
|
255
|
+
"year": "2025",
|
|
256
|
+
"group": "2025-01",
|
|
257
|
+
"orders": 45,
|
|
258
|
+
"net_revenue": 4500.00
|
|
259
|
+
}
|
|
260
|
+
]
|
|
261
|
+
}
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
---
|
|
265
|
+
|
|
266
|
+
### Get Recent Orders (Decimal Dollars)
|
|
267
|
+
|
|
268
|
+
`GET /fluent-cart/v2/reports/get-recent-orders`
|
|
269
|
+
|
|
270
|
+
> **Note:** `total_amount` is returned in **decimal dollars** (`99.99`).
|
|
271
|
+
|
|
272
|
+
```json
|
|
273
|
+
{
|
|
274
|
+
"recentOrders": [
|
|
275
|
+
{
|
|
276
|
+
"id": 150,
|
|
277
|
+
"customer_id": 42,
|
|
278
|
+
"customer_name": "John Doe",
|
|
279
|
+
"total_amount": 99.99,
|
|
280
|
+
"created_at": "2025-06-15 14:30:00",
|
|
281
|
+
"order_items_count": 3
|
|
282
|
+
}
|
|
283
|
+
]
|
|
284
|
+
}
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
---
|
|
288
|
+
|
|
289
|
+
## Subscription Reports & Retention Snapshots
|
|
290
|
+
|
|
291
|
+
### Get Subscription Chart
|
|
292
|
+
|
|
293
|
+
`GET /fluent-cart/v2/reports/subscription-chart`
|
|
294
|
+
|
|
295
|
+
> **Note:** `future_installments` is returned in **decimal dollars** (`sum((bill_times - bill_count) * recurring_total) / 100`).
|
|
296
|
+
|
|
297
|
+
```json
|
|
298
|
+
{
|
|
299
|
+
"currentMetrics": [
|
|
300
|
+
{
|
|
301
|
+
"year": "2025",
|
|
302
|
+
"group": "2025-01",
|
|
303
|
+
"subscriptions": 20,
|
|
304
|
+
"mrr": 100000
|
|
305
|
+
}
|
|
306
|
+
],
|
|
307
|
+
"summary": {
|
|
308
|
+
"future_installments": 500000.00,
|
|
309
|
+
"total_subscriptions": 150
|
|
310
|
+
}
|
|
311
|
+
}
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
---
|
|
315
|
+
|
|
316
|
+
### Get Subscription Cohorts
|
|
317
|
+
|
|
318
|
+
`GET /fluent-cart/v2/reports/subscription-cohorts`
|
|
319
|
+
|
|
320
|
+
Tracks subscriber retention over time across signup cohorts. Requires pre-generated retention snapshots.
|
|
321
|
+
|
|
322
|
+
#### Parameters
|
|
323
|
+
|
|
324
|
+
| Parameter | Type | Location | Required | Description |
|
|
325
|
+
|-----------|------|----------|----------|-------------|
|
|
326
|
+
| `params[groupBy]` | string | query | No | Cohort interval: `year` (default max 8 years) or `month` (default max 18 months) |
|
|
327
|
+
| `params[metric]` | string | query | No | Metric to track (default: `subscribers`) |
|
|
328
|
+
| `params[variation_ids]` | array | query | No | Variation IDs array (converted to product IDs internally) |
|
|
329
|
+
|
|
330
|
+
---
|
|
331
|
+
|
|
332
|
+
### Generate Retention Snapshots
|
|
333
|
+
|
|
334
|
+
`POST /fluent-cart/v2/reports/retention-snapshots/generate`
|
|
335
|
+
|
|
336
|
+
Triggers snapshot generation. Uses WordPress Action Scheduler for background processing if active; otherwise runs synchronously.
|
|
337
|
+
|
|
338
|
+
#### Parameters
|
|
339
|
+
|
|
340
|
+
| Parameter | Type | Location | Required | Description |
|
|
341
|
+
|-----------|------|----------|----------|-------------|
|
|
342
|
+
| `product_id` | integer | body | No | Specific product ID. If omitted, generates for all products |
|
|
343
|
+
|
|
344
|
+
#### Response (Background Mode)
|
|
345
|
+
|
|
346
|
+
```json
|
|
347
|
+
{
|
|
348
|
+
"success": true,
|
|
349
|
+
"message": "Snapshot generation queued",
|
|
350
|
+
"job_id": 1718456789,
|
|
351
|
+
"mode": "background"
|
|
352
|
+
}
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
---
|
|
356
|
+
|
|
357
|
+
### Check Retention Snapshot Status
|
|
358
|
+
|
|
359
|
+
`GET /fluent-cart/v2/reports/retention-snapshots/status`
|
|
360
|
+
|
|
361
|
+
#### Parameters
|
|
362
|
+
|
|
363
|
+
| Parameter | Type | Location | Required | Description |
|
|
364
|
+
|-----------|------|----------|----------|-------------|
|
|
365
|
+
| `params[job_id]` | integer | query | Yes | Unix timestamp `job_id` returned from generation endpoint |
|
|
366
|
+
|
|
367
|
+
#### Response
|
|
368
|
+
|
|
369
|
+
```json
|
|
370
|
+
{
|
|
371
|
+
"success": true,
|
|
372
|
+
"status": "completed",
|
|
373
|
+
"message": "Job completed",
|
|
374
|
+
"stats": {},
|
|
375
|
+
"data": {}
|
|
376
|
+
}
|
|
377
|
+
```
|
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
# Roles & Permissions API (Pro)
|
|
2
|
+
|
|
3
|
+
Manage custom store roles (`super_admin`, `manager`, `worker`, `accountant`), assign capabilities to WordPress users, search eligible users, and inspect role permission matrices in FluentCart Pro.
|
|
4
|
+
|
|
5
|
+
**Base URL:** `https://your-site.com/wp-json/fluent-cart/v2/roles`
|
|
6
|
+
**Policy:** `AdminPolicy` (Requires WordPress `manage_options` / `is_super_admin` capability)
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## Endpoints Overview
|
|
11
|
+
|
|
12
|
+
| Method | Endpoint | Description |
|
|
13
|
+
|--------|----------|-------------|
|
|
14
|
+
| GET | `/roles/managers` | List all WordPress users assigned a FluentCart shop role |
|
|
15
|
+
| GET | `/roles/user-list` | Search WordPress users eligible for role assignment (excludes WP admins) |
|
|
16
|
+
| GET | `/roles` | List available FluentCart role definitions (titles & descriptions) |
|
|
17
|
+
| POST | `/roles` | Assign a shop role to a WordPress user (grants `fluent_cart_admin` capability) |
|
|
18
|
+
| GET | `/roles/{key}` | Placeholder: Get role details |
|
|
19
|
+
| POST | `/roles/{key}` | Placeholder: Update role definition |
|
|
20
|
+
| DELETE | `/roles/{key}` | Remove a shop role assignment from a user (removes `fluent_cart_admin`) |
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## 1. List & Search Users
|
|
25
|
+
|
|
26
|
+
### List Managers
|
|
27
|
+
|
|
28
|
+
`GET /fluent-cart/v2/roles/managers`
|
|
29
|
+
|
|
30
|
+
Retrieve all WordPress users who have been assigned a shop role along with their permissions array.
|
|
31
|
+
|
|
32
|
+
#### Response
|
|
33
|
+
|
|
34
|
+
```json
|
|
35
|
+
{
|
|
36
|
+
"managers": [
|
|
37
|
+
{
|
|
38
|
+
"id": 5,
|
|
39
|
+
"email": "manager@example.com",
|
|
40
|
+
"display_name": "Jane Manager",
|
|
41
|
+
"username": "janemanager",
|
|
42
|
+
"shop_role": "manager",
|
|
43
|
+
"description": "With All Permissions Except Sensitive Settings",
|
|
44
|
+
"registered_at": "2025-03-10 08:00:00",
|
|
45
|
+
"role_permissions": [
|
|
46
|
+
"store/settings",
|
|
47
|
+
"products/view",
|
|
48
|
+
"orders/view",
|
|
49
|
+
"orders/manage",
|
|
50
|
+
"reports/view"
|
|
51
|
+
]
|
|
52
|
+
}
|
|
53
|
+
]
|
|
54
|
+
}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
### Search Eligible Users
|
|
60
|
+
|
|
61
|
+
`GET /fluent-cart/v2/roles/user-list`
|
|
62
|
+
|
|
63
|
+
Search for WordPress users who can be assigned a shop role.
|
|
64
|
+
|
|
65
|
+
> **Exclusion Rule:** WordPress site Administrators (`manage_options`) are automatically excluded from search results since they already possess full store capabilities.
|
|
66
|
+
|
|
67
|
+
#### Parameters
|
|
68
|
+
|
|
69
|
+
| Parameter | Type | Location | Required | Description |
|
|
70
|
+
|-----------|------|----------|----------|-------------|
|
|
71
|
+
| `search` | string | query | No | Partial search by display name or email address |
|
|
72
|
+
| `user_ids` | string/array | query | No | Include specific user IDs regardless of search term |
|
|
73
|
+
|
|
74
|
+
---
|
|
75
|
+
|
|
76
|
+
## 2. Role Assignments & Definitions
|
|
77
|
+
|
|
78
|
+
### List Roles
|
|
79
|
+
|
|
80
|
+
`GET /fluent-cart/v2/roles`
|
|
81
|
+
|
|
82
|
+
Retrieve built-in role titles and descriptions (`super_admin`, `manager`, `worker`, `accountant`).
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
### Assign Role
|
|
87
|
+
|
|
88
|
+
`POST /fluent-cart/v2/roles`
|
|
89
|
+
|
|
90
|
+
Assigns a role to a user. The user is granted the `fluent_cart_admin` capability and the role key is stored in user meta.
|
|
91
|
+
|
|
92
|
+
#### Parameters
|
|
93
|
+
|
|
94
|
+
| Parameter | Type | Required | Description |
|
|
95
|
+
|-----------|------|----------|-------------|
|
|
96
|
+
| `user_id` | integer | Yes | WordPress user ID |
|
|
97
|
+
| `role_key` | string | Yes | Role slug (`super_admin`, `manager`, `worker`, `accountant`) |
|
|
98
|
+
|
|
99
|
+
#### Response
|
|
100
|
+
|
|
101
|
+
```json
|
|
102
|
+
{
|
|
103
|
+
"message": "Role synced successfully",
|
|
104
|
+
"is_updated": true
|
|
105
|
+
}
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
---
|
|
109
|
+
|
|
110
|
+
### Delete Role Assignment
|
|
111
|
+
|
|
112
|
+
`DELETE /fluent-cart/v2/roles/{key}`
|
|
113
|
+
|
|
114
|
+
Removes the shop role from the specified user and strips the `fluent_cart_admin` capability.
|
|
115
|
+
|
|
116
|
+
#### Parameters
|
|
117
|
+
|
|
118
|
+
| Parameter | Type | Required | Description |
|
|
119
|
+
|-----------|------|----------|-------------|
|
|
120
|
+
| `key` | string | Yes (Path) | Role key being removed |
|
|
121
|
+
| `user_id` | integer | Yes (Body/Query) | WordPress user ID |
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## 3. Built-In Role Definitions & Capability Matrix
|
|
126
|
+
|
|
127
|
+
| Role | Key Permissions Included | Key Restrictions |
|
|
128
|
+
|------|--------------------------|------------------|
|
|
129
|
+
| **Super Admin** | `store/settings`, `store/sensitive`, `products/*`, `customers/*`, `orders/*`, `subscriptions/*`, `licenses/*`, `coupons/*`, `reports/*`, `integrations/*`, `labels/*`, `dashboard_stats/view` | None (Full Access) |
|
|
130
|
+
| **Manager** | All Super Admin permissions except sensitive store settings | Excludes `store/sensitive` |
|
|
131
|
+
| **Worker** | View access for products, customers, orders, subscriptions, licenses, integrations; manage order statuses; view & manage coupons | No product/customer editing, no report access |
|
|
132
|
+
| **Accountant** | View access for products, customers, orders, subscriptions, licenses, coupons, integrations; view & export orders and reports | Read-only with export rights; no management actions |
|
|
133
|
+
|
|
134
|
+
---
|
|
135
|
+
|
|
136
|
+
## Hooks & Extension Filters
|
|
137
|
+
|
|
138
|
+
```php
|
|
139
|
+
// Extend or customize available role definitions
|
|
140
|
+
add_filter('fluent_cart/permission/all_roles', function($roles) {
|
|
141
|
+
$roles['fulfillment_agent'] = [
|
|
142
|
+
'title' => 'Fulfillment Agent',
|
|
143
|
+
'description' => 'Manage orders and shipping statuses only'
|
|
144
|
+
];
|
|
145
|
+
return $roles;
|
|
146
|
+
});
|
|
147
|
+
```
|