Billing Revenue Report APIs
Overview
This document provides comprehensive API reference for the Billing Revenue Report tab endpoints. These endpoints are used to fetch revenue data including services delivered, payments received, and bills generated.
Base URL: /api
Authentication: Bearer token required
Headers:
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
Content-Type: application/jsonTable of Contents
- Services Delivered
- Payments Received
- Bills Generated
- Activity Logs - NEW: Implemented
- Billing Summary - NEW: Implemented
1. Services Delivered
1.1 List All Services
Endpoint: GET /billing/patient_services
Description: Lists all patient services (services delivered) across the tenant with optional filters.
Query Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
facility_id | string | No | - | Filter by facility ID |
patient_facility_id | string | No | - | Filter by patient facility ID |
patient_id | string | No | - | Filter by patient ID |
practitioner_id | string | No | - | Filter by practitioner ID |
encounter_id | string | No | - | Filter by encounter/appointment ID |
category_id | string | No | - | Filter by service category ID |
service_type | string | No | - | Filter by service type (consultation, procedure, etc.) |
status | string | No | - | Filter by status |
is_paid | boolean | No | - | Filter by payment status (true=paid, false=unpaid) |
is_billed | boolean | No | - | Filter by billing status (true=billed, false=unbilled) |
start_date | date | No | - | Filter services from this date (YYYY-MM-DD) |
end_date | date | No | - | Filter services until this date (YYYY-MM-DD) |
search | string | No | - | Search by service name |
patient_name | string | No | - | Search by patient name |
sort_by | string | No | service_datetime | Sort column (service_datetime, service_name, total_amount, status, created_at, updated_at) |
sort_order | string | No | desc | Sort order (asc, desc) |
page | integer | No | 1 | Page number |
per_page | integer | No | 25 | Items per page (max 100) |
Response: 200 OK
{
"data": [
{
"id": "019c89f1-7a31-7637-ab47-16a0c98c4e45",
"service_name": "General Consultation",
"service_datetime": "2025-01-15T10:30:00Z",
"service_type": "consultation",
"total_amount": 1000.00,
"discount_percent": 10.0,
"discount_amount": 100.00,
"net_amount": 900.00,
"status": "completed",
"is_paid": true,
"is_billed": true,
"billed_at": "2025-01-15T11:00:00Z",
"patient_id": "019c79c4-eae6-7889-a3e2-588b9a02f112",
"patient_facility_id": "019c79c4-eb06-7157-9a0f-7a7f5146b2db",
"facility_id": "01900002-0000-7000-8000-000000000001",
"practitioner_id": "01900003-0000-7000-8000-000000000001",
"encounter_id": "019c89f1-7a31-7637-ab47-16a0c98c4e45",
"category_id": "019c89ef-5c6b-774b-8409-a589be298ed1",
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-01-15T11:00:00Z"
}
],
"meta": {
"request_id": "uuid",
"pagination": {
"total_entries": 150,
"total_pages": 6,
"current_page": 1,
"per_page": 25
}
}
}1.2 Services for Patient Facility
Endpoint: GET /billing/patient_facilities/:patient_facility_id/services
Path Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
patient_facility_id | string | Yes | Patient Facility ID |
Query Parameters: Same as List All Services
Response: 200 OK
Same response format as List All Services.
2. Payments Received
2.1 List All Payments
Endpoint: GET /billing/payments
Description: Lists all payments received across the tenant with optional filters.
Query Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
facility_id | string | No | - | Filter by facility ID |
patient_id | string | No | - | Filter by patient ID |
practitioner_id | string | No | - | Filter by practitioner ID |
appointment_id | string | No | - | Filter by appointment ID |
status | string | No | - | Filter by status (pending, completed, failed, cancelled) |
payment_method | string | No | - | Filter by payment method (cash, card, upi, net_banking, etc.) |
start_date | date | No | - | Filter payments from this date (YYYY-MM-DD) |
end_date | date | No | - | Filter payments until this date (YYYY-MM-DD) |
search | string | No | - | Search by payment number |
sort_by | string | No | payment_date | Sort column (payment_date, amount, payment_number, status, created_at) |
sort_order | string | No | desc | Sort order (asc, desc) |
page | integer | No | 1 | Page number |
per_page | integer | No | 25 | Items per page (max 100) |
Response: 200 OK
{
"data": [
{
"id": "019c89f1-7a31-7637-ab47-16a0c98c4e45",
"payment_number": "PAY-2025-000001",
"payment_date": "2025-01-15T10:30:00Z",
"amount": 1500.00,
"currency": "INR",
"status": "completed",
"payment_method": "card",
"patient_id": "019c79c4-eae6-7889-a3e2-588b9a02f112",
"facility_id": "01900002-0000-7000-8000-000000000001",
"practitioner_id": "01900003-0000-7000-8000-000000000001",
"appointment_id": "019c89f1-7a31-7637-ab47-16a0c98c4e45",
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-01-15T10:30:00Z"
}
],
"meta": {
"request_id": "uuid",
"pagination": {
"total_entries": 200,
"total_pages": 8,
"current_page": 1,
"per_page": 25
}
}
}2.2 List Pending Payments
Endpoint: GET /billing/payments/pending
Description: Lists all pending payments awaiting completion.
Query Parameters: Same pagination parameters as List All Payments
Response: 200 OK
Same response format as List All Payments.
3. Bills Generated
3.1 List All Invoices
Endpoint: GET /billing/invoices
Description: Lists all invoices/bills generated across the tenant with optional filters.
Query Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
facility_id | string | No | - | Filter by facility ID |
patient_id | string | No | - | Filter by patient ID |
patient_facility_id | string | No | - | Filter by patient facility ID |
encounter_id | string | No | - | Filter by encounter/appointment ID |
status | string | No | - | Filter by status (draft, issued, paid, partially_paid, overdue, cancelled) |
overdue | boolean | No | - | Filter overdue invoices (true = only overdue) |
start_date | date | No | - | Filter invoices from this date (YYYY-MM-DD) |
end_date | date | No | - | Filter invoices until this date (YYYY-MM-DD) |
search | string | No | - | Search by invoice number |
sort_by | string | No | invoice_date | Sort column (invoice_date, invoice_number, total_amount, status, created_at) |
sort_order | string | No | desc | Sort order (asc, desc) |
page | integer | No | 1 | Page number |
per_page | integer | No | 25 | Items per page (max 100) |
Response: 200 OK
{
"data": [
{
"id": "019c89f1-7a31-7637-ab47-16a0c98c4e45",
"invoice_number": "INV-2025-000001",
"invoice_date": "2025-01-15T10:30:00Z",
"due_date": "2025-01-30T10:30:00Z",
"status": "issued",
"total_amount": 2700.00,
"amount_paid": 1500.00,
"balance_due": 1200.00,
"currency": "INR",
"patient_id": "019c79c4-eae6-7889-a3e2-588b9a02f112",
"patient_facility_id": "019c79c4-eb06-7157-9a0f-7a7f5146b2db",
"facility_id": "01900002-0000-7000-8000-000000000001",
"encounter_id": "019c89f1-7a31-7637-ab47-16a0c98c4e45",
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-01-15T11:00:00Z"
}
],
"meta": {
"request_id": "uuid",
"pagination": {
"total_entries": 75,
"total_pages": 3,
"current_page": 1,
"per_page": 25
}
}
}3.2 Invoice Details
Endpoint: GET /billing/invoices/:id
Path Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Invoice ID |
Query Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
view | string | No | detailed | Response view (normal, detailed, with_items) |
Response: 200 OK
{
"data": {
"id": "019c89f1-7a31-7637-ab47-16a0c98c4e45",
"invoice_number": "INV-2025-000001",
"invoice_date": "2025-01-15T10:30:00Z",
"due_date": "2025-01-30T10:30:00Z",
"status": "issued",
"total_amount": 2700.00,
"subtotal": 2700.00,
"tax_amount": 0.00,
"discount_amount": 0.00,
"amount_paid": 1500.00,
"balance_due": 1200.00,
"currency": "INR",
"patient_id": "019c79c4-eae6-7889-a3e2-588b9a02f112",
"patient_facility_id": "019c79c4-eb06-7157-9a0f-7a7f5146b2db",
"facility_id": "01900002-0000-7000-8000-000000000001",
"encounter_id": "019c89f1-7a31-7637-ab47-16a0c98c4e45",
"notes": "Payment due within 15 days",
"items": [
{
"id": "019c89f1-7a31-7637-ab47-16a0c98c4e46",
"description": "General Consultation",
"quantity": 1,
"unit_price": 1000.00,
"discount_percent": 0.0,
"discount_amount": 0.00,
"tax_percent": 0.0,
"tax_amount": 0.00,
"line_total": 1000.00,
"chargeable_type": "Billing::PatientService",
"chargeable_id": "019c89f1-7a31-7637-ab47-16a0c98c4e47"
},
{
"id": "019c89f1-7a31-7637-ab47-16a0c98c4e48",
"description": "Follow-up Consultation",
"quantity": 2,
"unit_price": 850.00,
"discount_percent": 0.0,
"discount_amount": 0.00,
"tax_percent": 0.0,
"tax_amount": 0.00,
"line_total": 1700.00,
"chargeable_type": "Billing::PatientService",
"chargeable_id": "019c89f1-7a31-7637-ab47-16a0c98c4e49"
}
],
"payments": [
{
"id": "019c89f1-7a31-7637-ab47-16a0c98c4e50",
"payment_number": "PAY-2025-000001",
"payment_date": "2025-01-15T10:30:00Z",
"amount": 1500.00,
"status": "completed",
"payment_method": "card"
}
],
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-01-15T11:00:00Z",
"created_by": "01900003-0000-7000-8000-000000000001",
"issued_at": "2025-01-15T11:00:00Z"
},
"meta": {
"request_id": "uuid"
}
}4. Activity Logs
4.1 List Billing Activity Logs
Endpoint: GET /billing/billing_activity_logs
Description: Lists all billing-related activity logs with filtering and pagination. Tracks create, update, and delete actions on services, payments, and invoices.
Query Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
facility_id | string | No | - | Filter by facility ID |
user_id | string | No | - | Filter by user who performed the action |
entity_type | string | No | - | Filter by entity type (service, payment, invoice) |
action | string | No | - | Filter by action type (create, update, delete) |
search | string | No | - | Search by description or resource name |
start_date | date | No | - | Filter logs from this date (YYYY-MM-DD) |
end_date | date | No | - | Filter logs until this date (YYYY-MM-DD) |
sort_by | string | No | created_at | Sort column (created_at, action, resource_type) |
sort_order | string | No | desc | Sort order (asc, desc) |
page | integer | No | 1 | Page number |
per_page | integer | No | 25 | Items per page (max 100) |
Response: 200 OK
{
"data": [
{
"id": "019c89f1-7a31-7637-ab47-16a0c98c4e45",
"action": "create",
"resource_type": "Billing::PatientService",
"resource_id": "019c89f1-7a31-7637-ab47-16a0c98c4e46",
"resource_name": "General Consultation",
"description": "Created service: General Consultation (1000.0)",
"created_at": "2025-01-15T10:30:00Z",
"user": {
"id": "01900003-0000-7000-8000-000000000001",
"name": "Raj Kumar",
"email": "raj@example.com"
},
"facility": {
"id": "01900002-0000-7000-8000-000000000001",
"name": "City Clinic"
},
"metadata": {
"changes": {},
"patient_id": "019c79c4-eae6-7889-a3e2-588b9a02f112",
"facility_id": "01900002-0000-7000-8000-000000000001",
"status": "completed"
}
},
{
"id": "019c89f1-7a31-7637-ab47-16a0c98c4e47",
"action": "create",
"resource_type": "Billing::Payment",
"resource_id": "019c89f1-7a31-7637-ab47-16a0c98c4e48",
"resource_name": "PAY-2025-000001",
"description": "Received payment: PAY-2025-000001 (1500.0 INR)",
"created_at": "2025-01-15T11:00:00Z",
"user": {
"id": "01900003-0000-7000-8000-000000000001",
"name": "Raj Kumar",
"email": "raj@example.com"
},
"facility": {
"id": "01900002-0000-7000-8000-000000000001",
"name": "City Clinic"
},
"metadata": {
"changes": {},
"patient_id": "019c79c4-eae6-7889-a3e2-588b9a02f112"
}
},
{
"id": "019c89f1-7a31-7637-ab47-16a0c98c4e49",
"action": "create",
"resource_type": "Billing::Invoice",
"resource_id": "019c89f1-7a31-7637-ab47-16a0c98c4e50",
"resource_name": "INV-2025-000001",
"description": "Generated invoice: INV-2025-000001 (2700.0)",
"created_at": "2025-01-15T12:00:00Z",
"user": {
"id": "01900003-0000-7000-8000-000000000001",
"name": "Raj Kumar",
"email": "raj@example.com"
},
"facility": {
"id": "01900002-0000-7000-8000-000000000001",
"name": "City Clinic"
},
"metadata": {
"changes": {},
"patient_id": "019c79c4-eae6-7889-a3e2-588b9a02f112"
}
}
],
"meta": {
"request_id": "uuid",
"pagination": {
"total_entries": 150,
"total_pages": 6,
"current_page": 1,
"per_page": 25
}
}
}Action Types:
| Action | Description |
|---|---|
create | Entity created |
update | Entity updated |
delete | Entity deleted |
Entity Types:
| Type | Description |
|---|---|
service | Patient Service (Billing::PatientService) |
payment | Payment (Billing::Payment) |
invoice | Invoice (Billing::Invoice) |
5. Billing Summary Dashboard
5.1 Get Billing Summary
Endpoint: GET /billing/facilities/:facility_id/summary
Description: Provides comprehensive billing analytics for the revenue dashboard. Returns aggregated data including bills by payment mode, services by name, billing summary, visit types, earnings, and time-series data.
Path Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
facility_id | string | Yes | Facility ID |
Query Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
start_time | string | Yes | - | Start datetime in ISO 8601 format |
end_time | string | Yes | - | End datetime in ISO 8601 format |
monthly | boolean | No | - | Flag for monthly breakdown (optional) |
Response: 200 OK
{
"data": {
"bills": [
{ "mode_of_payment": "Cash", "amount": 556.0 },
{ "mode_of_payment": "Card", "amount": 500.0 },
{ "mode_of_payment": "Upi", "amount": 0.0 },
{ "mode_of_payment": "Cheque", "amount": 0.0 },
{ "mode_of_payment": "Others", "amount": 2278.0 },
{ "mode_of_payment": "Payment_link", "amount": 0.0 }
],
"services": [
{ "service_name": "Dr. Mohit Bhatia's Consultation", "total_count": 6, "amount": 1021002010.0 },
{ "service_name": "General Consultation", "total_count": 3, "amount": 3000.0 }
],
"billing_summary": {
"billed_amount": 50000.0,
"unbilled_amount": 15000.0,
"paid_amount": 35000.0,
"unpaid_amount": 15000.0,
"teleconsultation": 5000.0
},
"visit_types": [
{ "visit_type": "Walkin", "amount": 5000.0 },
{ "visit_type": "Virtual", "amount": 2000.0 },
{ "visit_type": "Fixed", "amount": 8000.0 }
],
"earnings": {
"total_revenue": 65000.0,
"amount_pending": 30000.0,
"billed_amount": 50000.0,
"amount_received": 35000.0
},
"daywise_total_revenue": [
{ "date_ts": "2025-01-28", "value": 0.0 },
{ "date_ts": "2025-01-30", "value": 50000.0 },
{ "date_ts": "2025-01-31", "value": 65000.0 }
],
"daywise_total_patients": [
{ "date_ts": "2025-01-28", "value": 18 },
{ "date_ts": "2025-01-30", "value": 21 },
{ "date_ts": "2025-01-31", "value": 25 }
],
"prev_month_total_revenue": [
{ "date_ts": "2025-12-28", "value": 28529.0 },
{ "date_ts": "2025-12-30", "value": 36794.0 },
{ "date_ts": "2025-12-31", "value": 36794.0 }
],
"prev_month_total_patients": [
{ "date_ts": "2025-12-28", "value": 33 },
{ "date_ts": "2025-12-30", "value": 47 },
{ "date_ts": "2025-12-31", "value": 64 }
]
}
}5.2 Response Data Sections
Bills - Payment amounts grouped by payment mode (Cash, Card, Upi, Cheque, Others, Payment_link).
Services - Services grouped by name with total count and amount.
Billing Summary - Overall billing statistics:
billed_amount: Total amount from issued invoicesunbilled_amount: Total amount from unbilled servicespaid_amount: Total amount received on invoicesunpaid_amount: Outstanding balance on invoicesteleconsultation: Total amount from telemedicine services
Visit Types - Amount grouped by visit type (Walkin, Virtual, Fixed).
Earnings - Revenue breakdown:
total_revenue: Total revenue from all servicesamount_pending: Revenue not yet receivedbilled_amount: Amount that has been billedamount_received: Total payments received
Daywise Total Revenue - Time-series data (every 2 days) for current month.
Daywise Total Patients - Patient count time-series (every 2 days) for current month.
Previous Month Revenue - Revenue time-series (every 2 days) for previous month.
Previous Month Patients - Patient count time-series (every 2 days) for previous month.
Common Use Cases
Revenue Summary for Date Range
# Services delivered in date range
GET /billing/patient_services?start_date=2025-01-01&end_date=2025-01-31&facility_id={facility_id}
# Payments received in date range
GET /billing/payments?start_date=2025-01-01&end_date=2025-01-31&status=completed&facility_id={facility_id}
# Bills generated in date range
GET /billing/invoices?start_date=2025-01-01&end_date=2025-01-31&facility_id={facility_id}Outstanding Invoices Report
GET /billing/invoices?status=issued&facility_id={facility_id}Unbilled Services Report
GET /billing/patient_services?is_billed=false&facility_id={facility_id}Unpaid Services Report
GET /billing/patient_services?is_paid=false&facility_id={facility_id}Payment Collection Report
GET /billing/payments?status=completed&start_date=2025-01-01&end_date=2025-01-31&facility_id={facility_id}Practitioner-wise Revenue
GET /billing/patient_services?practitioner_id={practitioner_id}&start_date=2025-01-01&end_date=2025-01-31
GET /billing/payments?practitioner_id={practitioner_id}&start_date=2025-01-01&end_date=2025-01-31Activity Audit Trail
# All billing activities for a facility
GET /billing/billing_activity_logs?facility_id={facility_id}
# Activities by specific user
GET /billing/billing_activity_logs?user_id={user_id}
# Activities by entity type
GET /billing/billing_activity_logs?entity_type=service
# Activities by action type
GET /billing/billing_activity_logs?action=create
# Activities in date range
GET /billing/billing_activity_logs?start_date=2025-01-01&end_date=2025-01-31Billing Summary Dashboard
# Get billing summary for facility
GET /billing/facilities/{facility_id}/summary?start_time=2025-12-31T18:30:00.000Z&end_time=2026-01-31T18:29:59.999ZData Models
Service Status
| Status | Description |
|---|---|
pending | Service created but not yet delivered |
in_progress | Service currently being delivered |
completed | Service completed successfully |
cancelled | Service cancelled |
refunded | Service refunded |
Payment Status
| Status | Description |
|---|---|
pending | Payment initiated but not completed |
completed | Payment successful |
failed | Payment failed |
cancelled | Payment cancelled |
Payment Methods
| Method | Description |
|---|---|
cash | Cash payment |
card | Credit/Debit card |
upi | UPI payment |
net_banking | Net banking |
wallet | Digital wallet |
cheque | Cheque payment |
Invoice Status
| Status | Description |
|---|---|
draft | Invoice created but not issued |
issued | Invoice issued to patient |
paid | Fully paid |
partially_paid | Partially paid |
overdue | Payment overdue |
cancelled | Invoice cancelled |
Error Responses
Validation Error (422)
{
"success": false,
"errors": [
{
"detail": "Start date is required"
}
]
}Not Found (404)
{
"error": {
"code": "NOT_FOUND",
"message": "Resource not found"
}
}Unauthorized (401)
{
"error": "Unauthorized"
}Forbidden (403)
{
"error": {
"code": "FORBIDDEN",
"message": "You don't have permission to access this resource"
}
}Notes
-
Pagination: All list endpoints support pagination. Use
pageandper_pageparameters to navigate through results. Pagination metadata is returned in themeta.paginationobject. -
Date Format: All dates should be in ISO 8601 format (
YYYY-MM-DD) or ISO 8601 datetime format (YYYY-MM-DDTHH:mm:ssZ). -
Sorting: Results can be sorted by any field in the
sort_bylist. Default is usually by date in descending order (newest first). -
Filtering: Multiple filters can be combined. For example, you can filter by both
facility_idandstatus. -
Search: The
searchparameter performs a case-insensitive partial match on relevant fields (invoice number, payment number, service name, etc.). -
Currency: All amounts are in the currency configured for the tenant/facility (default: INR).
-
Soft Deletes: Deleted records are automatically excluded from list queries unless explicitly requested.
Related Endpoints
- Patient Package Subscriptions API:
/api/identity/patient_package_subscriptions- Manage patient subscriptions to care packages - Patient Facilities API:
/api/clinical/patient_facilities- Manage patient-facility associations - Patients API:
/api/clinical/patients- Manage patient records - Facilities API:
/api/identity/facilities- Manage facility records