Skip to main content

​
Overview

The Statistics API provides aggregated sales data, profit margins, and product performance analytics across different time periods.
All endpoints in this section require admin privileges.

​
Get Dashboard Summary

Retrieves aggregated sales and profit margin statistics for three time periods: daily, weekly (last 7 days), and monthly (last 30 days).

​
Response

​
daily
object
Statistics for today:
​
sales_total
number
Total sales amount
​
sales_count
integer
Number of sales transactions
​
margin_total
number
Total profit margin (sum of all product margins)
​
period
string
Period label: "Diario"
​
weekly
object
Statistics for the last 7 days (same structure as daily)
​
monthly
object
Statistics for the last 30 days (same structure as daily)
curl -X GET https://api.torn.com/stats/summary \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Margin Calculation

The margin_total is calculated using the following formula for each sold item: 
margin = quantity × (unit_price - unit_cost)
This gives you the total profit (before taxes and expenses) for all products sold in the period.

​
Get Top Products

Returns rankings of best-performing products by quantity sold and by profit margin.

​
Query Parameters

​
days
integer
default:"30"
Number of days to look back for the analysisExample: days=7 for last week’s top products
​
limit
integer
default:"5"
Number of top products to return in each rankingExample: limit=10 for top 10 products

​
Response

​
by_quantity
array
Top products ranked by total quantity sold:
​
product_id
integer
Product identifier
​
nombre
string
Product name
​
full_name
string
Full name including parent product (for variants). Format: "Parent Product Variant Name" or just product name if no parent.
​
total_qty
number
Total quantity sold
​
total_sales
number
Total sales revenue from this product
​
total_margin
number
Total profit margin from this product
​
by_margin
array
Top products ranked by total profit margin (same structure as by_quantity)
curl -X GET https://api.torn.com/stats/top-products?days=30&limit=5 \
  -H "Authorization: Bearer YOUR_TOKEN"
Different Rankings: The same product may appear in different positions in the two rankings. A high-volume, low-margin product might top the quantity list but rank lower in the margin list.

​
Generate Period Report

Generates a detailed sales and profitability report for a specific period, breaking down performance by product.

​
Query Parameters

​
period
string
default:"day"
Report period type. Options:
  • day - Single day report
  • week - Weekly report (Monday to Sunday)
  • month - Monthly report (full calendar month)
​
date
string
default:"today"
Reference date in YYYY-MM-DD format. The period will be calculated based on this date:
  • day: Report for this specific date
  • week: Report for the week containing this date
  • month: Report for the month containing this date
Example: date=2024-03-15

​
Response

​
fecha
datetime
Reference date used for the report
​
period
string
Period label: "Diario", "Semanal", or "Mensual"
​
total_ventas
number
Total gross sales for the entire period
​
total_utilidad
number
Total profit margin for the entire period
​
items
array
Detailed breakdown by product:
​
product_id
integer
Product identifier
​
full_name
string
Full product name (including parent if variant)
​
cantidad
number
Total quantity sold
​
monto_total
number
Total sales revenue from this product
​
utilidad
number
Total profit from this product (revenue - cost)
curl -X GET "https://api.torn.com/stats/report?period=day&date=2024-03-15" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Period Date Ranges

Here’s how date ranges are calculated for each period type:

Daily

Start: 00:00:00 of the specified dateEnd: 23:59:59 of the specified date

Weekly

Start: 00:00:00 of the Monday of the week containing the specified dateEnd: 23:59:59 of the Sunday of that week

Monthly

Start: 00:00:00 of the 1st day of the monthEnd: 23:59:59 of the last day of the month

​
Use Cases

Use /stats/summary to display high-level KPIs on an executive dashboard:
  • Compare daily vs. weekly vs. monthly performance
  • Track profit margins alongside sales volume
  • Monitor sales velocity (sales_count)
Use /stats/top-products to optimize inventory:
  • Identify fast-moving products by quantity
  • Find high-margin products worth promoting
  • Adjust stock levels based on sales velocity
Use /stats/report for detailed product analysis:
  • Compare profitability across your catalog
  • Identify underperforming products
  • Calculate average margins by category
  • Generate reports for accounting/management
Generate reports for multiple periods to identify trends:
# Compare last 4 weeks
curl "https://api.torn.com/stats/report?period=week&date=2024-02-26"
curl "https://api.torn.com/stats/report?period=week&date=2024-03-04"
curl "https://api.torn.com/stats/report?period=week&date=2024-03-11"
curl "https://api.torn.com/stats/report?period=week&date=2024-03-18"

​
Best Practices

Margin vs. Markup: The margin calculation uses (price - cost), which gives you absolute profit. To calculate margin percentage, use: (total_margin / total_sales) × 100
Variant Products: Products with variants show the parent name prepended to the variant name in full_name. Use this to group variant performance under parent products in your UI.
Performance Considerations: Generating reports for long time periods with many products can be resource-intensive. Consider:
  • Caching historical reports (past periods won’t change)
  • Limiting the date range for real-time queries
  • Using background jobs for large report generation
Cost Data Accuracy: Margin calculations depend on accurate costo_unitario (unit cost) data in your product records. Ensure costs are updated regularly, especially after receiving new inventory at different prices.

Build docs developers (and LLMs) love

Get started for freeTalk to us