Sales Analytics and Reporting

Overview

Sales Analytics provides comprehensive insights into sales performance, revenue trends, customer behavior, and operational metrics. This guide covers the dashboard, statistics endpoints, and reporting capabilities for analyzing sales data through the REST API.

Sales Dashboard
Order Analytics
Invoice Statistics
Payment Analytics
Revenue Reporting
Customer Analytics
Performance Metrics

Sales Dashboard

Get Dashboard Overview

Endpoint: GET /api/v1/sales/dashboard

Authentication: Required (Bearer token)

Purpose: Retrieve high-level sales metrics and KPIs

Query Parameters:

period (string) - Time period (today, week, month, quarter, year, custom)
from_date (date) - Custom start date (if period=custom)
to_date (date) - Custom end date (if period=custom)
compare_to_previous (boolean) - Include comparison to previous period

Response (200 OK):

json

{
  "data": {
    "period": {
      "label": "This Month",
      "from": "2025-12-01",
      "to": "2025-12-31",
      "days": 31
    },
    "summary": {
      "total_revenue": 1456789.12,
      "total_orders": 1247,
      "average_order_value": 1168.25,
      "total_invoices_sent": 1189,
      "total_invoices_paid": 1034,
      "collection_rate": 86.96,
      "outstanding_receivables": 289456.78
    },
    "orders": {
      "new_orders": 1247,
      "confirmed_orders": 1156,
      "shipped_orders": 1089,
      "completed_orders": 987,
      "cancelled_orders": 45,
      "orders_by_status": {
        "draft": 23,
        "pending": 34,
        "confirmed": 67,
        "processing": 89,
        "shipped": 102,
        "delivered": 145,
        "completed": 987,
        "cancelled": 45
      }
    },
    "invoices": {
      "invoices_sent": 1189,
      "invoices_paid": 1034,
      "invoices_overdue": 67,
      "total_overdue_amount": 89234.56,
      "average_days_to_pay": 23.5
    },
    "payments": {
      "payments_received": 1156,
      "total_paid": 1378234.56,
      "failed_payments": 34,
      "disputed_payments": 2,
      "refunded_amount": 23456.78
    },
    "comparison": {
      "revenue_change_percentage": 15.3,
      "orders_change_percentage": 12.8,
      "aov_change_percentage": 2.2,
      "collection_rate_change": 1.5
    },
    "trends": {
      "daily_revenue": [
        {"date": "2025-12-01", "revenue": 45678.90},
        {"date": "2025-12-02", "revenue": 51234.56}
      ],
      "daily_orders": [
        {"date": "2025-12-01", "orders": 38},
        {"date": "2025-12-02", "orders": 42}
      ]
    }
  }
}

Dashboard Widgets

Key Metrics Widget:

Total Revenue
Total Orders
Average Order Value
Collection Rate
Outstanding Receivables

Recent Orders Widget:

json

GET /api/v1/sales/dashboard/widgets/recent-orders
{
  "data": [
    {
      "id": 123,
      "order_number": "ORD-A3X7K9M2",
      "customer_name": "Acme Corporation",
      "total_amount": 347.47,
      "status": "completed",
      "order_date": "2025-12-17"
    }
  ]
}

Top Customers Widget:

json

GET /api/v1/sales/dashboard/widgets/top-customers
{
  "data": [
    {
      "customer_id": 42,
      "customer_name": "Acme Corporation",
      "total_orders": 45,
      "total_revenue": 125678.90,
      "average_order_value": 2792.86
    }
  ]
}

Sales Goals Widget:

json

GET /api/v1/sales/dashboard/widgets/sales-goals
{
  "data": {
    "monthly_target": 1500000.00,
    "current_revenue": 1456789.12,
    "progress_percentage": 97.12,
    "on_track": true,
    "days_remaining": 14
  }
}

Order Analytics

Order Performance Metrics

Endpoint: GET /api/v1/sales/orders/performance-metrics

Authentication: Required (Bearer token)

Query Parameters:

from_date (date) - Start date
to_date (date) - End date
sales_rep_id (integer) - Filter by sales representative

Response (200 OK):

json

{
  "data": {
    "period": {
      "from": "2025-12-01",
      "to": "2025-12-31"
    },
    "order_metrics": {
      "total_orders": 1247,
      "total_revenue": 1456789.12,
      "average_order_value": 1168.25,
      "median_order_value": 987.50,
      "highest_order_value": 15678.90,
      "lowest_order_value": 49.99,
      "orders_by_status": {
        "completed": 987,
        "processing": 156,
        "cancelled": 45,
        "pending": 59
      },
      "cancellation_rate": 3.61
    },
    "fulfillment_metrics": {
      "average_fulfillment_days": 3.2,
      "median_fulfillment_days": 3.0,
      "on_time_delivery_rate": 94.5,
      "late_delivery_rate": 5.5,
      "fastest_fulfillment_days": 1,
      "slowest_fulfillment_days": 12,
      "orders_pending_fulfillment": 156
    },
    "customer_metrics": {
      "unique_customers": 567,
      "new_customers": 234,
      "returning_customers": 333,
      "repeat_customer_rate": 58.7,
      "average_orders_per_customer": 2.2
    },
    "channel_metrics": {
      "by_source": {
        "online_store": {"count": 678, "revenue": 789234.56},
        "phone": {"count": 234, "revenue": 345678.90},
        "email": {"count": 189, "revenue": 234567.89},
        "api": {"count": 146, "revenue": 87307.77}
      }
    },
    "top_sales_reps": [
      {
        "sales_rep_id": 5,
        "name": "Jane Smith",
        "orders": 234,
        "revenue": 289456.78,
        "average_order_value": 1236.75,
        "win_rate": 78.5
      }
    ]
  }
}

High-Value Orders

Endpoint: GET /api/v1/sales/orders/high-value

Query Parameters:

minimum_amount (number) - Minimum order value (default: 10000)
status (string) - Filter by order status
from_date (date) - Start date
to_date (date) - End date

Response (200 OK):

json

{
  "data": [
    {
      "id": 125,
      "order_number": "ORD-B7Y9L2K5",
      "customer": {
        "id": 45,
        "company_name": "Enterprise Corp"
      },
      "total_amount": 125678.90,
      "order_date": "2025-12-15",
      "status": "completed",
      "sales_rep": {
        "id": 5,
        "name": "Jane Smith"
      }
    }
  ],
  "meta": {
    "total_orders": 23,
    "total_value": 456789.12,
    "average_value": 19860.83,
    "percentage_of_total_revenue": 31.35
  }
}

Orders by Status Report

Endpoint: GET /api/v1/sales/orders?group_by=status

Response:

json

{
  "data": {
    "draft": {
      "count": 23,
      "total_value": 34567.89
    },
    "pending": {
      "count": 34,
      "total_value": 45678.90
    },
    "confirmed": {
      "count": 67,
      "total_value": 89012.34
    },
    "completed": {
      "count": 987,
      "total_value": 1234567.89
    }
  }
}

Invoice Statistics

Invoice Analytics

Endpoint: GET /api/v1/sales/invoices/statistics

Authentication: Required (Bearer token)

Query Parameters:

from_date (date) - Start date
to_date (date) - End date
customer_id (integer) - Filter by customer

Response (200 OK):

json

{
  "data": {
    "period": {
      "from": "2025-12-01",
      "to": "2025-12-31"
    },
    "invoice_counts": {
      "total": 1189,
      "draft": 34,
      "sent": 121,
      "partially_paid": 23,
      "paid": 1034,
      "overdue": 67,
      "cancelled": 10
    },
    "financial_metrics": {
      "total_invoiced": 1456789.12,
      "total_paid": 1378234.56,
      "total_outstanding": 78554.56,
      "total_overdue": 89234.56,
      "average_invoice_value": 1225.35,
      "collection_rate": 94.61,
      "write_off_amount": 5678.90
    },
    "payment_metrics": {
      "average_days_to_pay": 23.5,
      "median_days_to_pay": 18.0,
      "on_time_payment_rate": 78.3,
      "late_payment_rate": 21.7,
      "days_sales_outstanding": 35.2
    },
    "aging_analysis": {
      "current": 289456.78,
      "1_30_days": 34567.89,
      "31_60_days": 12345.67,
      "61_90_days": 5678.90,
      "over_90_days": 3456.78
    },
    "top_customers_by_invoices": [
      {
        "customer_id": 42,
        "customer_name": "Acme Corporation",
        "invoice_count": 45,
        "total_invoiced": 125678.90,
        "total_paid": 125678.90,
        "payment_performance": "excellent"
      }
    ]
  }
}

Invoice Aging Report

Endpoint: GET /api/v1/sales/invoices/aging-report

Purpose: Accounts receivable aging analysis

Query Parameters:

as_of_date (date) - Report date (default: today)
customer_id (integer) - Filter by customer
include_paid (boolean) - Include paid invoices (default: false)

Response (200 OK):

json

{
  "data": {
    "report_date": "2025-12-31",
    "aging_buckets": {
      "current": {
        "label": "Current (Not Due)",
        "count": 121,
        "total_amount": 289456.78,
        "percentage": 75.4
      },
      "1_30_days": {
        "label": "1-30 Days Overdue",
        "count": 45,
        "total_amount": 34567.89,
        "percentage": 9.0
      },
      "31_60_days": {
        "label": "31-60 Days Overdue",
        "count": 15,
        "total_amount": 12345.67,
        "percentage": 3.2
      },
      "61_90_days": {
        "label": "61-90 Days Overdue",
        "count": 5,
        "total_amount": 5678.90,
        "percentage": 1.5
      },
      "over_90_days": {
        "label": "Over 90 Days",
        "count": 2,
        "total_amount": 3456.78,
        "percentage": 0.9
      }
    },
    "summary": {
      "total_invoices": 188,
      "total_outstanding": 345506.02,
      "overdue_amount": 55904.24,
      "overdue_percentage": 16.2,
      "average_days_outstanding": 28.7
    },
    "by_customer": [
      {
        "customer_id": 42,
        "customer_name": "Acme Corporation",
        "customer_number": "CUST-00042",
        "current": 45678.90,
        "1_30_days": 5000.00,
        "31_60_days": 0.00,
        "61_90_days": 0.00,
        "over_90_days": 0.00,
        "total_outstanding": 50678.90,
        "credit_limit": 100000.00,
        "available_credit": 49321.10
      }
    ]
  }
}

Payment Analytics

Payment Statistics

Endpoint: GET /api/v1/sales/payments/statistics

Authentication: Required (Bearer token)

Query Parameters:

from_date (date) - Start date
to_date (date) - End date
method (string) - Filter by payment method
status (string) - Filter by payment status

Response (200 OK):

json

{
  "data": {
    "period": {
      "from": "2025-12-01",
      "to": "2025-12-31"
    },
    "payment_counts": {
      "total": 1156,
      "completed": 1089,
      "pending": 23,
      "failed": 34,
      "refunded": 7,
      "disputed": 3
    },
    "financial_metrics": {
      "total_processed": 1378234.56,
      "total_refunded": 12345.67,
      "total_fees": 45678.90,
      "net_revenue": 1320209.99,
      "average_transaction": 1192.18
    },
    "method_breakdown": {
      "credit_card": {
        "count": 789,
        "amount": 945678.90,
        "percentage": 68.6,
        "average_transaction": 1198.83,
        "fees": 32456.78
      },
      "bank_transfer": {
        "count": 234,
        "amount": 287654.32,
        "percentage": 20.9,
        "average_transaction": 1229.08,
        "fees": 2300.83
      },
      "paypal": {
        "count": 89,
        "amount": 98765.43,
        "percentage": 7.2,
        "average_transaction": 1109.73,
        "fees": 3456.79
      },
      "check": {
        "count": 34,
        "amount": 34567.89,
        "percentage": 2.5,
        "average_transaction": 1016.70,
        "fees": 0.00
      },
      "cash": {
        "count": 10,
        "amount": 11568.02,
        "percentage": 0.8,
        "average_transaction": 1156.80,
        "fees": 0.00
      }
    },
    "success_metrics": {
      "success_rate": 96.90,
      "failure_rate": 2.94,
      "refund_rate": 0.61,
      "dispute_rate": 0.26,
      "average_processing_time_seconds": 4.8
    },
    "gateway_performance": {
      "stripe": {
        "count": 856,
        "success_rate": 97.2,
        "average_response_time_ms": 1234
      },
      "paypal": {
        "count": 89,
        "success_rate": 95.5,
        "average_response_time_ms": 2345
      }
    }
  }
}

Failed Payments Report

Endpoint: GET /api/v1/sales/payments/failed

Purpose: Analyze payment failures for recovery opportunities

Response:

json

{
  "data": [
    {
      "id": 791,
      "payment_number": "PAY-12345680",
      "amount": 299.00,
      "method": "credit_card",
      "failure_reason": "insufficient_funds",
      "failed_at": "2025-12-20T11:00:00Z",
      "retry_count": 2,
      "can_retry": true,
      "customer": {
        "id": 43,
        "company_name": "Beta Corp",
        "email": "billing@beta.com"
      }
    }
  ],
  "meta": {
    "total_failed": 34,
    "total_failed_amount": 45678.90,
    "retryable_count": 28,
    "retryable_amount": 38901.23,
    "by_reason": {
      "insufficient_funds": 18,
      "card_declined": 8,
      "expired_card": 5,
      "invalid_details": 3
    }
  }
}

Disputed Payments Report

Endpoint: GET /api/v1/sales/payments/disputed

Response:

json

{
  "data": [
    {
      "id": 789,
      "payment_number": "PAY-12345678",
      "amount": 347.47,
      "dispute_reason": "fraudulent",
      "disputed_at": "2025-12-25T00:00:00Z",
      "evidence_due_date": "2026-01-08",
      "days_to_respond": 14,
      "requires_urgent_action": false
    }
  ],
  "meta": {
    "total_disputed": 3,
    "total_disputed_amount": 1234.56,
    "evidence_required": 3,
    "urgent_disputes": 0,
    "won_disputes": 15,
    "lost_disputes": 2
  }
}

Revenue Reporting

Revenue by Period

Endpoint: GET /api/v1/sales/dashboard/revenue

Query Parameters:

period (string) - Group by (day, week, month, quarter, year)
from_date (date) - Start date
to_date (date) - End date

Response:

json

{
  "data": {
    "period_type": "month",
    "revenue_by_period": [
      {
        "period": "2025-01",
        "revenue": 1234567.89,
        "orders": 1089,
        "average_order_value": 1133.64
      },
      {
        "period": "2025-02",
        "revenue": 1456789.12,
        "orders": 1247,
        "average_order_value": 1168.25
      }
    ],
    "summary": {
      "total_revenue": 2691357.01,
      "average_monthly_revenue": 1345678.51,
      "highest_month": {"period": "2025-02", "revenue": 1456789.12},
      "lowest_month": {"period": "2025-01", "revenue": 1234567.89},
      "growth_rate": 18.0
    }
  }
}

Revenue by Product

Endpoint: GET /api/v1/sales/dashboard/revenue?group_by=product

Response:

json

{
  "data": {
    "by_product": [
      {
        "product_id": 101,
        "sku": "WIDGET-001",
        "name": "Premium Widget",
        "units_sold": 456,
        "revenue": 45678.90,
        "percentage_of_total": 15.3
      },
      {
        "product_id": 102,
        "sku": "GADGET-002",
        "name": "Smart Gadget",
        "units_sold": 234,
        "revenue": 35123.45,
        "percentage_of_total": 11.7
      }
    ]
  }
}

Customer Analytics

Customer Purchase Behavior

Endpoint: GET /api/v1/sales/dashboard/customer-analytics

Response (200 OK):

json

{
  "data": {
    "customer_segmentation": {
      "new_customers": {
        "count": 234,
        "revenue": 234567.89,
        "average_order_value": 1002.17
      },
      "returning_customers": {
        "count": 333,
        "revenue": 1222221.23,
        "average_order_value": 1368.25
      },
      "vip_customers": {
        "count": 45,
        "revenue": 567890.12,
        "average_order_value": 12619.78
      }
    },
    "customer_lifetime_value": {
      "average": 5678.90,
      "median": 3456.78,
      "top_10_percent": 25678.90
    },
    "purchase_frequency": {
      "average_orders_per_customer": 2.2,
      "repeat_purchase_rate": 58.7,
      "time_between_purchases_days": 45.3
    },
    "top_customers": [
      {
        "customer_id": 42,
        "customer_name": "Acme Corporation",
        "total_orders": 45,
        "total_revenue": 125678.90,
        "average_order_value": 2792.86,
        "customer_since": "2023-03-15",
        "lifetime_value": 125678.90
      }
    ]
  }
}

Performance Metrics

Key Performance Indicators

Endpoint: GET /api/v1/sales/dashboard/performance

Response:

json

{
  "data": {
    "revenue_kpis": {
      "monthly_recurring_revenue": 45678.90,
      "annual_run_rate": 17456789.12,
      "revenue_growth_rate": 15.3,
      "revenue_per_customer": 2567.89
    },
    "efficiency_kpis": {
      "order_to_cash_cycle_days": 28.5,
      "days_sales_outstanding": 35.2,
      "collection_efficiency": 94.61,
      "order_fulfillment_time_days": 3.2
    },
    "customer_kpis": {
      "customer_acquisition_cost": 234.56,
      "customer_lifetime_value": 5678.90,
      "ltv_to_cac_ratio": 24.2,
      "customer_retention_rate": 87.5,
      "churn_rate": 12.5
    },
    "operational_kpis": {
      "order_accuracy_rate": 98.7,
      "on_time_delivery_rate": 94.5,
      "order_cancellation_rate": 3.6,
      "return_rate": 2.1
    }
  }
}

Exporting Reports

Export to CSV

Endpoint: GET /api/v1/sales/orders/export?format=csv

Query Parameters:

format (string) - Export format (csv, excel, pdf)
from_date (date) - Start date
to_date (date) - End date
status (string) - Filter by status

Response: CSV file download

Export to Excel

Endpoint: GET /api/v1/sales/invoices/export?format=excel

Response: Excel (.xlsx) file download

Best Practices

Monitor Daily: Check dashboard metrics every business day
Track Trends: Look for patterns in weekly/monthly data
Set Alerts: Configure notifications for KPI thresholds
Compare Periods: Always compare current vs previous periods
Drill Down: Use dashboard overview to identify areas needing attention
Export Regularly: Generate monthly reports for management
Analyze Failures: Review failed payments and disputes weekly
Track Customer Behavior: Monitor customer segmentation and lifetime value
Measure O2C Cycle: Track order-to-cash cycle time for process improvement
Review Aging: Check accounts receivable aging weekly

Order Management - Order data used in analytics
Invoice Workflow - Invoice metrics and aging
Payment Processing - Payment statistics
Order-to-Cash Workflow - Complete cycle metrics

Sales Analytics and Reporting ​

Overview ​

Table of Contents ​

Sales Dashboard ​

Get Dashboard Overview ​

Dashboard Widgets ​

Order Analytics ​

Order Performance Metrics ​

High-Value Orders ​

Orders by Status Report ​

Invoice Statistics ​

Invoice Analytics ​

Invoice Aging Report ​

Payment Analytics ​

Payment Statistics ​

Failed Payments Report ​

Disputed Payments Report ​

Revenue Reporting ​

Revenue by Period ​

Revenue by Product ​

Customer Analytics ​

Customer Purchase Behavior ​

Performance Metrics ​

Key Performance Indicators ​

Exporting Reports ​

Export to CSV ​

Export to Excel ​

Best Practices ​

Related Guides ​

Sales Analytics and Reporting

Overview

Table of Contents

Sales Dashboard

Get Dashboard Overview

Dashboard Widgets

Order Analytics

Order Performance Metrics

High-Value Orders

Orders by Status Report

Invoice Statistics

Invoice Analytics

Invoice Aging Report

Payment Analytics

Payment Statistics

Failed Payments Report

Disputed Payments Report

Revenue Reporting

Revenue by Period

Revenue by Product

Customer Analytics

Customer Purchase Behavior

Performance Metrics

Key Performance Indicators

Exporting Reports

Export to CSV

Export to Excel

Best Practices

Related Guides