aditya.siregar 4f5950543e init

2025-07-18 20:10:29 +07:00

7.3 KiB

Raw Blame History

Profit/Loss Analytics API

This document describes the Profit/Loss Analytics API that provides comprehensive financial analysis for the POS system, including revenue, costs, and profitability metrics.

Overview

The Profit/Loss Analytics API allows you to:

Analyze profit and loss performance over time periods
Track gross profit and net profit margins
View product-wise profitability
Monitor cost vs revenue trends
Calculate profitability ratios

Authentication

All analytics endpoints require authentication and admin/manager permissions.

Endpoints

Get Profit/Loss Analytics

Endpoint: GET /api/v1/analytics/profit-loss

Description: Retrieves comprehensive profit and loss analytics data including summary metrics, time-series data, and product profitability analysis.

Query Parameters:

outlet_id (UUID, optional) - Filter by specific outlet
date_from (string, required) - Start date in DD-MM-YYYY format
date_to (string, required) - End date in DD-MM-YYYY format
group_by (string, optional) - Time grouping: hour, day, week, month (default: day)

Example Request:

curl -X GET "http://localhost:8080/api/v1/analytics/profit-loss?date_from=01-12-2023&date_to=31-12-2023&group_by=day" \
  -H "Authorization: Bearer <token>" \
  -H "Organization-ID: <org-id>"

Example Response:

{
  "success": true,
  "data": {
    "organization_id": "123e4567-e89b-12d3-a456-426614174000",
    "outlet_id": "123e4567-e89b-12d3-a456-426614174001",
    "date_from": "2023-12-01T00:00:00Z",
    "date_to": "2023-12-31T23:59:59Z",
    "group_by": "day",
    "summary": {
      "total_revenue": 125000.00,
      "total_cost": 75000.00,
      "gross_profit": 50000.00,
      "gross_profit_margin": 40.00,
      "total_tax": 12500.00,
      "total_discount": 2500.00,
      "net_profit": 35000.00,
      "net_profit_margin": 28.00,
      "total_orders": 1250,
      "average_profit": 28.00,
      "profitability_ratio": 66.67
    },
    "data": [
      {
        "date": "2023-12-01T00:00:00Z",
        "revenue": 4032.26,
        "cost": 2419.35,
        "gross_profit": 1612.91,
        "gross_profit_margin": 40.00,
        "tax": 403.23,
        "discount": 80.65,
        "net_profit": 1129.03,
        "net_profit_margin": 28.00,
        "orders": 40
      },
      {
        "date": "2023-12-02T00:00:00Z",
        "revenue": 3750.00,
        "cost": 2250.00,
        "gross_profit": 1500.00,
        "gross_profit_margin": 40.00,
        "tax": 375.00,
        "discount": 75.00,
        "net_profit": 1050.00,
        "net_profit_margin": 28.00,
        "orders": 35
      }
    ],
    "product_data": [
      {
        "product_id": "123e4567-e89b-12d3-a456-426614174002",
        "product_name": "Premium Burger",
        "category_id": "123e4567-e89b-12d3-a456-426614174003",
        "category_name": "Main Course",
        "quantity_sold": 150,
        "revenue": 2250.00,
        "cost": 900.00,
        "gross_profit": 1350.00,
        "gross_profit_margin": 60.00,
        "average_price": 15.00,
        "average_cost": 6.00,
        "profit_per_unit": 9.00
      },
      {
        "product_id": "123e4567-e89b-12d3-a456-426614174004",
        "product_name": "Caesar Salad",
        "category_id": "123e4567-e89b-12d3-a456-426614174005",
        "category_name": "Salads",
        "quantity_sold": 80,
        "revenue": 960.00,
        "cost": 384.00,
        "gross_profit": 576.00,
        "gross_profit_margin": 60.00,
        "average_price": 12.00,
        "average_cost": 4.80,
        "profit_per_unit": 7.20
      }
    ]
  }
}

Response Structure

Summary Object

total_revenue - Total revenue for the period
total_cost - Total cost of goods sold
gross_profit - Revenue minus cost (total_revenue - total_cost)
gross_profit_margin - Gross profit as percentage of revenue
total_tax - Total tax collected
total_discount - Total discounts given
net_profit - Profit after taxes and discounts
net_profit_margin - Net profit as percentage of revenue
total_orders - Number of completed orders
average_profit - Average profit per order
profitability_ratio - Gross profit as percentage of total cost

Time Series Data

The data array contains profit/loss metrics grouped by the specified time period:

date - Date/time for the data point
revenue - Revenue for the period
cost - Cost for the period
gross_profit - Gross profit for the period
gross_profit_margin - Gross profit margin percentage
tax - Tax amount for the period
discount - Discount amount for the period
net_profit - Net profit for the period
net_profit_margin - Net profit margin percentage
orders - Number of orders in the period

Product Profitability Data

The product_data array shows the top 20 most profitable products:

product_id - Unique product identifier
product_name - Product name
category_id - Product category identifier
category_name - Category name
quantity_sold - Total units sold
revenue - Total revenue from the product
cost - Total cost for the product
gross_profit - Total gross profit
gross_profit_margin - Profit margin percentage
average_price - Average selling price per unit
average_cost - Average cost per unit
profit_per_unit - Average profit per unit

Key Metrics Explained

Gross Profit Margin

Calculated as: (Revenue - Cost) / Revenue × 100 Shows the percentage of revenue retained after direct costs.

Net Profit Margin

Calculated as: (Revenue - Cost - Discount) / Revenue × 100 Shows the percentage of revenue retained after all direct costs and discounts.

Profitability Ratio

Calculated as: Gross Profit / Total Cost × 100 Shows the return on investment for costs incurred.

Use Cases

Financial Performance Analysis - Track overall profitability trends
Product Performance - Identify most and least profitable products
Cost Management - Monitor cost ratios and margins
Pricing Strategy - Analyze impact of pricing on profitability
Inventory Decisions - Focus on high-margin products
Business Intelligence - Make data-driven financial decisions

Error Responses

The API returns standard error responses with appropriate HTTP status codes:

400 Bad Request:

{
  "success": false,
  "errors": [
    {
      "code": "invalid_request",
      "entity": "AnalyticsHandler::GetProfitLossAnalytics", 
      "message": "date_from is required"
    }
  ]
}

401 Unauthorized:

{
  "success": false,
  "errors": [
    {
      "code": "unauthorized",
      "entity": "AuthMiddleware",
      "message": "Invalid or missing authentication token"
    }
  ]
}

403 Forbidden:

{
  "success": false,
  "errors": [
    {
      "code": "forbidden", 
      "entity": "AuthMiddleware",
      "message": "Admin or manager role required"
    }
  ]
}

Notes

Only completed and paid orders are included in profit/loss calculations
Voided and refunded orders are excluded from the analysis
Product profitability is sorted by gross profit in descending order
Time series data is automatically filled for periods with no data (showing zero values)
All monetary values are in the organization's base currency
Margins and ratios are calculated as percentages with 2 decimal precision

7.3 KiB Raw Blame History Unescape Escape