fluentcart-developer 1.1.0 → 1.1.1

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 (65) hide show
  1. package/CLAUDE.md +22 -22
  2. package/LICENSE +21 -21
  3. package/README.md +169 -127
  4. package/SKILL.md +127 -127
  5. package/bin/index.js +281 -281
  6. package/package.json +48 -37
  7. package/skills/fluentcart-developer/SKILL.md +172 -172
  8. package/skills/fluentcart-developer/examples/README.md +25 -25
  9. package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/fluent-cart/checkout.php +32 -32
  10. package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/functions.php +40 -40
  11. package/skills/fluentcart-developer/examples/sample-custom-addon/fluentcart-custom-addon.php +114 -114
  12. package/skills/fluentcart-developer/examples/sample-custom-payment-gateway/fluentcart-custom-gateway-example.php +149 -149
  13. package/skills/fluentcart-developer/examples/sample-fee-surcharge-plugin/fluentcart-fee-surcharge.php +38 -38
  14. package/skills/fluentcart-developer/examples/sample-shipping-carrier/fluentcart-custom-shipping-carrier.php +62 -62
  15. package/skills/fluentcart-developer/references/action-hooks-admin-templates.md +787 -787
  16. package/skills/fluentcart-developer/references/action-hooks-cart-checkout.md +1355 -1355
  17. package/skills/fluentcart-developer/references/action-hooks-customers-users.md +266 -266
  18. package/skills/fluentcart-developer/references/action-hooks-licenses.md +855 -855
  19. package/skills/fluentcart-developer/references/action-hooks-orders.md +631 -631
  20. package/skills/fluentcart-developer/references/action-hooks-payments-integrations.md +963 -963
  21. package/skills/fluentcart-developer/references/action-hooks-products-coupons.md +585 -585
  22. package/skills/fluentcart-developer/references/action-hooks-subscriptions.md +661 -661
  23. package/skills/fluentcart-developer/references/database-models-query-builder.md +194 -194
  24. package/skills/fluentcart-developer/references/database-models-reference.md +604 -604
  25. package/skills/fluentcart-developer/references/database-schema-reference.md +940 -940
  26. package/skills/fluentcart-developer/references/engineering-notes.md +154 -154
  27. package/skills/fluentcart-developer/references/fee-system-guide.md +449 -449
  28. package/skills/fluentcart-developer/references/filter-hooks-cart-checkout.md +1202 -1202
  29. package/skills/fluentcart-developer/references/filter-hooks-customers-subscriptions.md +902 -902
  30. package/skills/fluentcart-developer/references/filter-hooks-integrations-advanced.md +1598 -1598
  31. package/skills/fluentcart-developer/references/filter-hooks-orders-payments.md +1319 -1319
  32. package/skills/fluentcart-developer/references/filter-hooks-products-pricing.md +628 -628
  33. package/skills/fluentcart-developer/references/filter-hooks-settings-configuration.md +1177 -1177
  34. package/skills/fluentcart-developer/references/fluentcart-developer-guide.md +154 -154
  35. package/skills/fluentcart-developer/references/ghost-product-selling.md +458 -458
  36. package/skills/fluentcart-developer/references/modules-and-extensions-reference.md +224 -224
  37. package/skills/fluentcart-developer/references/payment-gateway-integration.md +761 -761
  38. package/skills/fluentcart-developer/references/rest-api-checkout.md +286 -286
  39. package/skills/fluentcart-developer/references/rest-api-coupons.md +794 -794
  40. package/skills/fluentcart-developer/references/rest-api-customer-profile.md +190 -190
  41. package/skills/fluentcart-developer/references/rest-api-customers.md +1121 -1121
  42. package/skills/fluentcart-developer/references/rest-api-dashboard-utilities.md +219 -219
  43. package/skills/fluentcart-developer/references/rest-api-email-notifications.md +619 -619
  44. package/skills/fluentcart-developer/references/rest-api-files.md +290 -290
  45. package/skills/fluentcart-developer/references/rest-api-integrations.md +324 -324
  46. package/skills/fluentcart-developer/references/rest-api-labels-attributes.md +321 -321
  47. package/skills/fluentcart-developer/references/rest-api-licensing.md +171 -171
  48. package/skills/fluentcart-developer/references/rest-api-order-bumps.md +200 -200
  49. package/skills/fluentcart-developer/references/rest-api-orders.md +1241 -1241
  50. package/skills/fluentcart-developer/references/rest-api-overview.md +131 -131
  51. package/skills/fluentcart-developer/references/rest-api-products.md +2563 -2563
  52. package/skills/fluentcart-developer/references/rest-api-public-shop.md +172 -172
  53. package/skills/fluentcart-developer/references/rest-api-reference.md +552 -552
  54. package/skills/fluentcart-developer/references/rest-api-reports.md +377 -377
  55. package/skills/fluentcart-developer/references/rest-api-roles-permissions.md +147 -147
  56. package/skills/fluentcart-developer/references/rest-api-settings.md +528 -528
  57. package/skills/fluentcart-developer/references/rest-api-shipping.md +799 -799
  58. package/skills/fluentcart-developer/references/rest-api-subscriptions.md +606 -606
  59. package/skills/fluentcart-developer/references/rest-api-tax.md +356 -356
  60. package/skills/fluentcart-developer/references/subscription-customization.md +197 -197
  61. package/skills/fluentcart-developer/scripts/cli.js +1 -1
  62. package/.gitattributes +0 -2
  63. package/CONTRIBUTING.md +0 -73
  64. package/copy-skills.js +0 -43
  65. package/skills.sh.json +0 -13
@@ -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
+ ```