Common Statistics Provider

The Common Statistics Provider is the built-in provider for everyday commerce analytics in medusa-stats. It exposes the default metrics most stores need first: cart analysis, order performance, sales reporting, customer retention, product movement, and inventory alerts.

This article summarizes every available statistic and the parameters you can pass to each one.

#Available Statistics

#Cart metrics

• cart_progress_breakdown - Breaks carts into Empty, With Items, Customer Info, Payment, and Completed buckets.
  • Parameters: include_completed (boolean, default false)
• average_cart_value - Average cart value over time.
  • Parameters: currency_code (string, optional), status (all | completed | active | abandoned, default all)
• abandoned_cart_value - Average value of abandoned carts.
  • Parameters: currency_code (string, optional), abandoned_after_hours (number, default 24)
• total_cart_value - Total value of carts over time.
  • Parameters: currency_code (string, optional)

#Order and promotion metrics

• order_refund_ratio - Refunds as a percentage of total sales.
  • Parameters: currency_code (string, optional)
• order_promotion_ratio - Discounts as a percentage of total sales.
  • Parameters: none
• total_promotions_value - Total discount value applied to orders.
  • Parameters: currency_code (string, optional)
• orders_by_status - Orders grouped by status.
  • Parameters: statuses (string[], default pending, completed, canceled, requires_action)
• average_units_per_order - Average number of units per order.
  • Parameters: none
• orders_by_time - Orders over time.
  • Parameters: status (all | completed | pending | canceled, default completed)
• orders_chart - Flexible order chart for count, total value, or average value.
  • Parameters: metric (count | total_value | average_value, default count)

#Region, channel, and payment metrics

• regions_popularity - Orders grouped by region.
  • Parameters: limit (number, default 10)
• sales_channel_popularity - Orders grouped by sales channel.
  • Parameters: none
• orders_frequency_distribution - Distribution of time between repeat orders.
  • Parameters: bucket_size (number, default 7)
• payment_provider_popularity - Orders grouped by payment provider.
  • Parameters: none

#Sales metrics

• average_sales - Average sales over time.
  • Parameters: currency_code (string, optional)
• sales_per_channel - Sales grouped by sales channel.
  • Parameters: currency_code (string, optional)
• net_sales - Net sales after discounts, refunds, and optional tax handling.
  • Parameters: currency_code (string, optional), include_tax (boolean, default true)
• sales_by_time - Sales over time.
  • Parameters: currency_code (string, optional)
• sales_by_currency - Sales grouped by currency.
  • Parameters: none
• sales_chart - Flexible sales chart for total or refund-adjusted reporting.
  • Parameters: currency_code (string, optional), include_refunds (boolean, default false)
• refunds_total - Refund totals over time.
  • Parameters: currency_code (string, optional)

#Customer metrics

• average_sales_per_customer - Average sales per customer.
  • Parameters: currency_code (string, optional), customer_segment (all | new | returning, default all)
• customer_lifetime_value - Average lifetime value per customer.
  • Parameters: currency_code (string, optional)
• new_customers_by_time - New customers over time.
  • Parameters: none
• repeat_customer_rate - Percentage of customers with repeated orders.
  • Parameters: minimum_orders (number, default 2)
• customers_chart - Flexible customer chart for total, new, active, or repeat customers.
  • Parameters: metric (total | new | active | repeat, default total)
• cumulative_customers - Cumulative customer count over time.
  • Parameters: none
• customer_retention_rate - Retention trend over time.
  • Parameters: cohort_period (day | week | month | quarter, default month)

#Product and inventory metrics

• top_variants - Top-selling product variants.
  • Parameters: limit (number, default 20), metric (quantity | revenue, default quantity)
• top_returned_variants - Most frequently returned variants.
  • Parameters: limit (number, default 20)
• products_sold_count - Sold product count over time.
  • Parameters: count_type (total_units | unique_products, default total_units)
• out_of_stock_variants - Number of variants at or below a stock threshold.
  • Parameters: location_id (string, optional), threshold (number, default 0)

#How to Read the Results

Most statistics return time-series values when the statistic is dimensioned as time. Others return category buckets for pie and bar charts, or a single numeric result for inventory counts.

The common provider is the best place to start when you want ready-made analytics for orders, sales, customer activity, and stock health without building custom calculations.