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,377 +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
- ```
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
+ ```