Custom Reports Builder

Paid pluginsize Mplanned, not built

Indicative price, not an offer: €49/mo; 10 custom reports, email delivery, drill-down

Generated from docs/plan/paid/custom-reports-builder/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

A paid module for merchants to build custom reports (cohort analysis, LTV by channel, product performance) with drill-down capability, automated scheduling, and email delivery. Core provides order/customer data APIs; this pack adds report template system, scheduler, and drill-down UI.

The problem

Merchant sees ‘Total Revenue: €50K’ on dashboard but needs ‘LTV by acquisition channel’ or ‘top 10 products by margin’—default dashboard doesn’t slice data the way they need. Building a custom report requires hiring a data analyst (€3000+) or waiting for development.

What it does

• Report builder UI: drag-drop fields (product name, revenue, LTV, cohort, channel), choose chart type (bar/line/table)
• Data sources: orders (revenue, discount, customer count), customers (cohort, acquisition channel, LTV), products (sku, margin, category)
• Drill-down: click a bar in chart, see underlying orders/customers that make up that bar
• Pre-built templates: ‘Revenue by Product’, ‘LTV by Channel’, ‘Customer Lifetime Value’, ‘Top Regions’, merchant picks and customizes
• Scheduled delivery: run report on schedule (daily/weekly/monthly), email as attachment (PDF/CSV)
• Filters: date range, product category, region, customer segment, minimum LTV threshold
• Sharing: report URL with read-only access (login required), no modification by viewer

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Real-time alerting (notify when revenue drops 20%)—owned by alerts module, not reporting
• Predictive forecasting (revenue forecast for next month)—requires ML expertise; analytics consulting feature, not automation
• Data warehouse (storing snapshots, historical trending)—too large; pay pack owns report execution, core owns raw data
• Custom SQL queries—security risk; merchants use UI builder, not SQL
• Advanced segmentation (behavioral cohorts based on purchase patterns)—owned by customer analytics module

Data model

New entities: Report (id, merchantId, name, type[custom|template], chartType, fields[], filters, schedule, createdAt); ReportExecution (id, reportId, ranAt, data[], format[pdf|csv]). Links: Report.merchantId → Shop (multitenancy). Migration: none (new data).

API

• POST /api/v1/reports — create custom report (staff only)
• GET /api/v1/reports/{id} — fetch report definition (staff only)
• PATCH /api/v1/reports/{id} — update report definition, filters (staff only)
• POST /api/v1/reports/{id}/run — execute report immediately, return data + chart (staff only)
• GET /api/v1/reports/{id}/data — fetch latest report data (staff/share-link token, read-only)
• POST /api/v1/reports/{id}/schedule — set schedule (daily/weekly/monthly), email recipients (staff only)
• GET /api/v1/reports/{id}/share-link — generate read-only share token, return shareable URL
• GET /api/v1/reports/{id}/drill-down — click chart bar, fetch underlying orders/customers

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Report builder page: template picker (revenue by product, LTV by channel, etc.) or ‘blank report’. Canvas: drag fields onto chart, choose chart type. Data source: date range picker, filters (product category, region, etc.), metric picker (revenue, count, LTV). Preview: shows chart with current data. Schedule section: toggle on/off, frequency picker, email list. Share section: button to generate read-only URL. Reports list: all reports, last run date, next scheduled run.

The seam — why this is paid

Core owns: order data (line items, customer history), customer records, API to fetch data. Paid pack owns: Report entity, template system, scheduling, drill-down logic, PDF/CSV export. Seam drawn here because merchants need SLA on report accuracy—core data API may change, paid support team maintains compatibility and validates reports.

Support commitment: data warehouse SLA, report accuracy audits, BI support

Dependencies

• core:orders — report reads order data (revenue, line items, dates, customer ID)
• core:customers — report reads customer data (acquisition channel, LTV if calculated in core, or this module calculates it)
• core:email — scheduled report delivery
• core:scheduler — trigger report execution on schedule
• core:authentication — share-link tokens must be validated (anonymous but token-gated)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• A merchant selects template ‘Revenue by Product’ and filters to date range 2026-01-01 to 2026-09-01; running the report shows a bar chart with top 5 products by revenue, bars sorted descending, no missing data
• A merchant clicks the bar for ‘Product A, €5000’; drill-down fetches underlying 50 orders, shows order #, date, customer, revenue; table is sortable
• A merchant sets report schedule to ‘weekly on Monday 9 AM’; on next Monday at 9 AM, report is executed and emailed to merchant@shop.de as CSV attachment
• A merchant creates custom report (pick fields: product_name, revenue, margin), sets filter ‘product category = Electronics’; report shows only electronics products with their revenue and margin
• A merchant generates share link for the report; visiting the share URL without login shows the chart (no data table), cannot edit report or see customer PII
• Report is executed at 9 AM Monday; the email is received by 9:15 AM with attachment ‘revenue_by_product_2026-09-01.csv’, file size < 10 MB
• A drill-down with 1000+ orders returns data in < 2 sec (paginated or summary)
• Two merchants from different shops create reports; each sees only their own data, not the other’s shop

Risks

Report execution over 1M+ orders can timeout—must paginate and cache. Share-link tokens must not leak data (validate token on every drill-down request). Report template upgrades (adding new fields) must not break saved reports—migration logic needed. Currency in reports is order-locked; must not show mixed currencies in sum (flag or convert). If merchant deletes a product, old reports still show it (historical accuracy)—decide whether to archive product or keep reference.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.