Kulcare Docs
DeveloperBilling

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/json

Table of Contents

  1. Services Delivered
  2. Payments Received
  3. Bills Generated
  4. Activity Logs - NEW: Implemented
  5. 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:

ParameterTypeRequiredDefaultDescription
facility_idstringNo-Filter by facility ID
patient_facility_idstringNo-Filter by patient facility ID
patient_idstringNo-Filter by patient ID
practitioner_idstringNo-Filter by practitioner ID
encounter_idstringNo-Filter by encounter/appointment ID
category_idstringNo-Filter by service category ID
service_typestringNo-Filter by service type (consultation, procedure, etc.)
statusstringNo-Filter by status
is_paidbooleanNo-Filter by payment status (true=paid, false=unpaid)
is_billedbooleanNo-Filter by billing status (true=billed, false=unbilled)
start_datedateNo-Filter services from this date (YYYY-MM-DD)
end_datedateNo-Filter services until this date (YYYY-MM-DD)
searchstringNo-Search by service name
patient_namestringNo-Search by patient name
sort_bystringNoservice_datetimeSort column (service_datetime, service_name, total_amount, status, created_at, updated_at)
sort_orderstringNodescSort order (asc, desc)
pageintegerNo1Page number
per_pageintegerNo25Items 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:

ParameterTypeRequiredDescription
patient_facility_idstringYesPatient 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:

ParameterTypeRequiredDefaultDescription
facility_idstringNo-Filter by facility ID
patient_idstringNo-Filter by patient ID
practitioner_idstringNo-Filter by practitioner ID
appointment_idstringNo-Filter by appointment ID
statusstringNo-Filter by status (pending, completed, failed, cancelled)
payment_methodstringNo-Filter by payment method (cash, card, upi, net_banking, etc.)
start_datedateNo-Filter payments from this date (YYYY-MM-DD)
end_datedateNo-Filter payments until this date (YYYY-MM-DD)
searchstringNo-Search by payment number
sort_bystringNopayment_dateSort column (payment_date, amount, payment_number, status, created_at)
sort_orderstringNodescSort order (asc, desc)
pageintegerNo1Page number
per_pageintegerNo25Items 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:

ParameterTypeRequiredDefaultDescription
facility_idstringNo-Filter by facility ID
patient_idstringNo-Filter by patient ID
patient_facility_idstringNo-Filter by patient facility ID
encounter_idstringNo-Filter by encounter/appointment ID
statusstringNo-Filter by status (draft, issued, paid, partially_paid, overdue, cancelled)
overduebooleanNo-Filter overdue invoices (true = only overdue)
start_datedateNo-Filter invoices from this date (YYYY-MM-DD)
end_datedateNo-Filter invoices until this date (YYYY-MM-DD)
searchstringNo-Search by invoice number
sort_bystringNoinvoice_dateSort column (invoice_date, invoice_number, total_amount, status, created_at)
sort_orderstringNodescSort order (asc, desc)
pageintegerNo1Page number
per_pageintegerNo25Items 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:

ParameterTypeRequiredDescription
idstringYesInvoice ID

Query Parameters:

ParameterTypeRequiredDefaultDescription
viewstringNodetailedResponse 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:

ParameterTypeRequiredDefaultDescription
facility_idstringNo-Filter by facility ID
user_idstringNo-Filter by user who performed the action
entity_typestringNo-Filter by entity type (service, payment, invoice)
actionstringNo-Filter by action type (create, update, delete)
searchstringNo-Search by description or resource name
start_datedateNo-Filter logs from this date (YYYY-MM-DD)
end_datedateNo-Filter logs until this date (YYYY-MM-DD)
sort_bystringNocreated_atSort column (created_at, action, resource_type)
sort_orderstringNodescSort order (asc, desc)
pageintegerNo1Page number
per_pageintegerNo25Items 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:

ActionDescription
createEntity created
updateEntity updated
deleteEntity deleted

Entity Types:

TypeDescription
servicePatient Service (Billing::PatientService)
paymentPayment (Billing::Payment)
invoiceInvoice (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:

ParameterTypeRequiredDescription
facility_idstringYesFacility ID

Query Parameters:

ParameterTypeRequiredDefaultDescription
start_timestringYes-Start datetime in ISO 8601 format
end_timestringYes-End datetime in ISO 8601 format
monthlybooleanNo-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 invoices
  • unbilled_amount: Total amount from unbilled services
  • paid_amount: Total amount received on invoices
  • unpaid_amount: Outstanding balance on invoices
  • teleconsultation: Total amount from telemedicine services

Visit Types - Amount grouped by visit type (Walkin, Virtual, Fixed).

Earnings - Revenue breakdown:

  • total_revenue: Total revenue from all services
  • amount_pending: Revenue not yet received
  • billed_amount: Amount that has been billed
  • amount_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-31

Activity 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-31

Billing 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.999Z

Data Models

Service Status

StatusDescription
pendingService created but not yet delivered
in_progressService currently being delivered
completedService completed successfully
cancelledService cancelled
refundedService refunded

Payment Status

StatusDescription
pendingPayment initiated but not completed
completedPayment successful
failedPayment failed
cancelledPayment cancelled

Payment Methods

MethodDescription
cashCash payment
cardCredit/Debit card
upiUPI payment
net_bankingNet banking
walletDigital wallet
chequeCheque payment

Invoice Status

StatusDescription
draftInvoice created but not issued
issuedInvoice issued to patient
paidFully paid
partially_paidPartially paid
overduePayment overdue
cancelledInvoice 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

  1. Pagination: All list endpoints support pagination. Use page and per_page parameters to navigate through results. Pagination metadata is returned in the meta.pagination object.

  2. Date Format: All dates should be in ISO 8601 format (YYYY-MM-DD) or ISO 8601 datetime format (YYYY-MM-DDTHH:mm:ssZ).

  3. Sorting: Results can be sorted by any field in the sort_by list. Default is usually by date in descending order (newest first).

  4. Filtering: Multiple filters can be combined. For example, you can filter by both facility_id and status.

  5. Search: The search parameter performs a case-insensitive partial match on relevant fields (invoice number, payment number, service name, etc.).

  6. Currency: All amounts are in the currency configured for the tenant/facility (default: INR).

  7. Soft Deletes: Deleted records are automatically excluded from list queries unless explicitly requested.


  • 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

On this page