Kulcare Docs
DeveloperBilling03 api reference

Clinic Stakeholders and Revenue Sharing APIs

This document provides comprehensive API documentation for managing clinic stakeholders and revenue sharing functionality in the Kulcare platform.

Table of Contents

Overview

The Kulcare platform provides APIs for managing clinic stakeholders and implementing revenue sharing mechanisms. These APIs enable:

  • Management of clinic stakeholders (doctors, partners, investors)
  • Configuration of revenue sharing rules
  • Automated commission calculations
  • Settlement generation and processing
  • Revenue distribution tracking

Authentication

All API endpoints require authentication using JWT tokens in the Authorization header:

Authorization: Bearer <your-jwt-token>

Clinic Stakeholders APIs

1. List Clinic Stakeholders

Retrieve all stakeholders associated with a clinic.

Endpoint: GET /clinics/:clinic_id/clinic_stakeholders

Parameters:

  • clinic_id (required): ID of the clinic

Response:

{
  "success": true,
  "data": {
    "clinic_stakeholders": [
      {
        "id": 1,
        "name": "Dr. John Doe",
        "email": "john.doe@example.com",
        "country_code": "+91",
        "phone_number": "9876543210",
        "stakeholder_type": "doctor",
        "status": "active",
        "user_id": 123,
        "photo": null,
        "invited_at": null,
        "created_at": "2024-01-15T10:00:00Z"
      }
    ]
  }
}

2. Create Clinic Stakeholder

Add a new stakeholder to a clinic.

Endpoint: POST /clinics/:clinic_id/clinic_stakeholders

Request Body:

{
  "name": "Dr. Jane Smith",
  "email": "jane.smith@example.com",
  "country_code": "+91",
  "phone_number": "9876543211",
  "stakeholder_type": "doctor",
  "photo": null
}

Required Fields:

  • clinic_id: ID of the clinic
  • name: Stakeholder name
  • stakeholder_type: Type of stakeholder (e.g., "doctor", "partner", "investor")

Optional Fields:

  • email: Email address
  • country_code: Country code (defaults to "+91")
  • phone_number: Phone number
  • photo: Photo URL

Response:

{
  "success": true,
  "message": "stakeholder saved",
  "data": {
    "id": 2,
    "name": "Dr. Jane Smith",
    "email": "jane.smith@example.com",
    "country_code": "+91",
    "phone_number": "9876543211",
    "stakeholder_type": "doctor",
    "status": "invited",
    "user_id": null,
    "photo": null,
    "invited_at": "2024-09-04T12:00:00Z",
    "created_at": "2024-09-04T12:00:00Z"
  }
}

Notes:

  • If the user exists in the system, status will be "active"
  • If the user doesn't exist, status will be "invited" and an invitation will be sent

3. Delete Clinic Stakeholder

Remove a stakeholder from a clinic.

Endpoint: DELETE /clinics/:clinic_id/clinic_stakeholders/:id

Parameters:

  • clinic_id: ID of the clinic
  • id: ID of the stakeholder

Response:

{
  "success": true,
  "message": "Stakeholder removed successfully"
}

4. Reinvite Stakeholder

Resend invitation to a stakeholder.

Endpoint: POST /clinics/:clinic_id/clinic_stakeholders/:id/reinvite

Parameters:

  • clinic_id: ID of the clinic
  • id: ID of the stakeholder

Response:

{
  "success": true,
  "message": "Invitation resent successfully"
}

Revenue Sharing APIs

1. Commission Dashboard

Get commission overview for a clinic.

Endpoint: GET /clinics/:clinic_id/commission_dashboard

Parameters:

  • clinic_id (required): ID of the clinic
  • start_date (optional): Start date for the period (format: YYYY-MM-DD)
  • end_date (optional): End date for the period (format: YYYY-MM-DD)
  • page (optional): Page number for pagination (default: 1)
  • per_page (optional): Items per page (default: 20)

Response:

{
  "success": true,
  "data": {
    "summary": {
      "total_revenue": 150000.0,
      "total_commission": 45000.0,
      "appointment_count": 120,
      "average_commission_rate": 30.0
    },
    "period": {
      "start": "2024-09-01",
      "end": "2024-09-30"
    },
    "calculations": [
      {
        "id": 101,
        "appointment_id": 5001,
        "gross_amount": 1500.0,
        "calculated_commission": 450.0,
        "calculated_at": "2024-09-03T14:30:00Z",
        "status": "pending",
        "clinic_doctor": {
          "id": 45,
          "doctor_id": 123,
          "name": "Dr. John Doe",
          "fees": 1500.0,
          "telemedicine_fees": 1000.0
        }
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 6,
      "total_entries": 120,
      "per_page": 20
    }
  }
}

2. Revenue Share Configurations

List Configurations

Endpoint: GET /clinics/:clinic_id/revenue_share_configurations

Parameters:

  • clinic_id (required): ID of the clinic

Response:

{
  "success": true,
  "message": "Revenue share configurations fetched successfully",
  "data": {
    "revenue_share_configurations": [
      {
        "id": 2,
        "configuration_name": "New Standard Revenue Distribution",
        "description": "Default revenue sharing setup",
        "effective_from": "2025-02-01T00:00:00.000Z",
        "effective_until": "2026-02-01T00:00:00.000Z",
        "status": "active",
        "approved_at": "2025-09-03T09:24:12.011Z",
        "created_at": "2025-09-03T09:20:07.366Z",
        "updated_at": "2025-09-03T09:24:12.021Z",
        "distribution_rules": {
          "distribution_frequency": "monthly",
          "auto_approval_threshold": 50000
        },
        "total_percentage_allocated": "100.0",
        "can_be_activated": false,
        "created_by": "Meenakshi",
        "approved_by": "Meenakshi",
        "stakeholders": [
          {
            "id": 1,
            "clinic_stakeholder_id": 2,
            "stakeholder_type": "platform",
            "stakeholder_name": "Kulcare",
            "share_percentage": "60.0",
            "share_amount": null,
            "minimum_amount": "0.0",
            "maximum_amount": null,
            "payout_method": "bank_transfer",
            "clinic_stakeholder": {
              "id": 2,
              "name": "Kulcare",
              "email": null,
              "phone_number": null,
              "stakeholder_type": "platform",
              "status": "invited"
            }
          },
          {
            "id": 2,
            "clinic_stakeholder_id": 3,
            "stakeholder_type": "owner",
            "stakeholder_name": "Kirti Sharma",
            "share_percentage": "40.0",
            "share_amount": null,
            "minimum_amount": "0.0",
            "maximum_amount": null,
            "payout_method": "bank_transfer",
            "clinic_stakeholder": {
              "id": 3,
              "name": "Kirti Sharma",
              "email": null,
              "phone_number": "5555501502",
              "stakeholder_type": "owner",
              "status": "invited"
            }
          }
        ]
      }
    ]
  }
}

Create Configuration

Endpoint: POST /clinics/:clinic_id/revenue_share_configurations

Request Body:

{
  "configuration_name": "New Standard Revenue Distribution",
  "description": "Default revenue sharing setup",
  "stakeholders": [
    {
      "stakeholder_id": 2,
      "share_percentage": 60.0
    },
    {
      "stakeholder_id": "3",
      "share_percentage": 40.0
    }
  ],
  "effective_from": "2025-02-01",
  "effective_until": "2026-02-01",
  "distribution_rules": {
    "distribution_frequency": "monthly",
    "auto_approval_threshold": 50000
  }
}

Show Configuration

Endpoint: GET /clinics/:clinic_id/revenue_share_configurations/:id

Parameters:

  • clinic_id: ID of the clinic
  • id: ID of the configuration

Activate Configuration

Endpoint: POST /clinics/:clinic_id/revenue_share_configurations/:id/activate

Parameters:

  • clinic_id: ID of the clinic
  • id: ID of the configuration

Response:

{
  "success": true,
  "message": "Configuration activated successfully"
}

Commission Management APIs

1. List Commission Rules

Endpoint: GET /clinics/:clinic_id/commission_rules

Parameters:

  • clinic_id (required): ID of the clinic
  • page (optional): Page number
  • perpage (optional): Items per page
  • rule_type_id (optional): Filter by rule type
  • service_type_id (optional): Filter by service type
  • search_text (optional): Search in rule names

Response:

{
  "success": true,
  "data": {
    "commission_rules": [
      {
        "id": 1,
        "rule_name": "Standard Consultation",
        "rule_description": "Default commission for consultations",
        "commission_percentage": "30.0",
        "fixed_amount": null,
        "effective_from": "2024-01-01",
        "effective_to": null,
        "priority": 1,
        "active": true,
        "applies_to_all_services": false,
        "basic_commission_rule_type": {
          "id": 1,
          "name": "percentage",
          "display_name": "Percentage Commission"
        },
        "basic_service_types": [
          {
            "id": 1,
            "name": "consultation",
            "display_name": "Consultation"
          }
        ],
        "clinic_doctors": [
          {
            "id": 45,
            "name": "Dr. John Doe",
            "specialization": "General Medicine",
            "has_override": false,
            "override_percentage": null,
            "override_fixed_amount": null
          }
        ],
        "created_by": "Admin Name"
      }
    ]
  },
  "total_records": 5,
  "total_pages": 1
}

2. Show Commission Rule

Endpoint: GET /clinics/:clinic_id/commission_rules/:id

Parameters:

  • clinic_id: ID of the clinic
  • id: ID of the commission rule

Response:

{
  "success": true,
  "data": {
    "commission_rule": {
      "id": 1,
      "rule_name": "Standard Consultation",
      "rule_description": "Default commission for consultations",
      "commission_percentage": "30.0",
      "fixed_amount": null,
      "effective_from": "2024-01-01",
      "effective_to": null,
      "priority": 1,
      "active": true,
      "applies_to_all_services": false,
      "basic_commission_rule_type": {
        "id": 1,
        "name": "percentage",
        "display_name": "Percentage Commission"
      },
      "basic_service_types": [...],
      "clinic_doctors": [...],
      "created_by": "Admin Name"
    }
  }
}

3. Create Commission Rule

Endpoint: POST /clinics/:clinic_id/commission_rules

Request Body:

{
  "basic_commission_rule_type_id": 1,
  "rule_name": "Surgery Commission",
  "rule_description": "Commission for surgical procedures",
  "commission_percentage": 40.0,
  "effective_from": "2024-09-01",
  "priority": 2,
  "active": true,
  "applies_to_all_services": false,
  "basic_service_type_ids": [2, 3],
  "clinic_doctor_ids": [45, 46],
  "doctor_overrides": {
    "45": {
      "override_percentage": 45.0
    }
  },
  "tiers": [
    {
      "min_amount": 0,
      "max_amount": 50000,
      "commission_percentage": 40.0
    },
    {
      "min_amount": 50001,
      "max_amount": 100000,
      "commission_percentage": 35.0
    }
  ]
}

4. Update Commission Rule

Endpoint: PUT /clinics/:clinic_id/commission_rules/:id

Request Body: Same as create, with id parameter

Response: Same as show endpoint

Settlement APIs

1. List Settlements

Endpoint: GET /clinics/:clinic_id/settlements

Parameters:

  • clinic_id (required): ID of the clinic
  • period (optional): Settlement period (format: YYYY-MM)
  • settlement_status (optional): Filter by status
  • clinic_doctor_id (optional): Filter by doctor

Response:

{
  "success": true,
  "data": {
    "settlements": [
      {
        "id": 3,
        "settlement_period": "2025-09",
        "period_start": "2025-09-01",
        "period_end": "2025-09-30",
        "total_earnings": "3500.0",
        "total_deductions": "0.0",
        "net_amount": "3500.0",
        "status": "pending",
        "paid_on": null,
        "payment_reference": null,
        "notes": null,
        "approved_at": null,
        "created_at": "2025-09-04T06:22:45.026Z",
        "updated_at": "2025-09-04T06:22:45.026Z",
        "doctor_name": "Dr. Pinki",
        "clinic_doctor_id": 7,
        "clinic_name": "ABC Clinic",
        "approved_by": null,
        "can_be_paid": false,
        "calculation_count": 1
      }
    ],
    "total_pages": 1,
    "total_records": 2,
    "pending_amount": "3500.0",
    "approved_amount": "350.0"
  }
}

2. Generate Monthly Settlement

Endpoint: POST /clinics/:clinic_id/settlements/generate

Request Body:

{
  "period": "2024-09"
}

Response:

{
  "success": true,
  "message": "Monthly settlements generated successfully"
}

3. Approve Settlement

Endpoint: POST /clinics/:clinic_id/settlements/:settlement_id/approve

Request Body:

{
  "notes": "Approved for payment"
}

Response:

{
  "success": true,
  "data": {
    "settlement": {
            "status": "approved",
            "approved_at": "2025-09-04T06:37:34.829Z",
            "settlement_period": "2025-09",
            "total_earnings": "350.0",
            "net_amount": "350.0",
            "id": 2,
            "period_start": "2025-09-01",
            "period_end": "2025-09-30",
            "total_deductions": "0.0",
            "paid_on": null,
            "payment_reference": null,
            "notes": null,
            "created_at": "2025-09-04T06:22:20.307Z",
            "updated_at": "2025-09-04T06:37:34.866Z",
            "doctor_name": "Dr. Mini Clinic",
            "clinic_doctor_id": 2,
            "clinic_name": "ABC Clinic",
            "approved_by": "Meenakshi",
            "can_be_paid": true,
            "calculation_count": 1
        }
}

4. Process Settlement Payment

Endpoint: POST /clinics/:clinic_id/settlements/:settlement_id/process_payment

Request Body:

{
  "payment_method": "bank_transfer",
  "notes": "Payment processed via NEFT transfer"
}

Response:

{
  "success": true,
  "data": {
    "settlement": {
      "id": 2,
      "status": "paid",
      "paid_on": "2024-09-04",
      "payment_reference": "TXN123456789",
      "notes": "Payment processed via NEFT transfer",
      "total_earnings": "350.0",
      "net_amount": "350.0"
    }
  }
}

Revenue Distribution Queue APIs

1. List Revenue Distribution Queue

Endpoint: GET /clinics/:clinic_id/revenue_distribution_queue

Parameters:

  • clinic_id (required): ID of the clinic
  • status (optional): Filter by status
  • start_date (optional): Start date filter
  • end_date (optional): End date filter
  • page (optional): Page number
  • per_page (optional): Items per page

Response:

{
  "success": true,
  "data": {
    "entries": [
      {
        "id": 201,
        "source_type": "appointment",
        "source_id": 5001,
        "amount": 1500.0,
        "status": "pending",
        "created_at": "2024-09-03T14:30:00Z"
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 3,
      "total_entries": 45
    }
  }
}

2. Export Revenue Distribution Queue

Endpoint: GET /clinics/:clinic_id/revenue_distribution_queue/export

Parameters:

  • clinic_id (required): ID of the clinic
  • file_format (optional): Export format (csv, xlsx)
  • Other filters same as list endpoint

Response: File download with the specified format

Revenue Share Calculations

1. List Revenue Share Calculations

Endpoint: GET /clinics/:clinic_id/revenue_share_calculations

Parameters:

  • clinic_id (required): ID of the clinic
  • start_date (optional): Start date filter
  • end_date (optional): End date filter
  • page (optional): Page number
  • per_page (optional): Items per page
  • include_distributions (optional): Include distribution details

Response:

{
  "success": true,
  "data": {
    "calculations": [
      {
        "id": 301,
        "clinic_revenue_share_config_id": 1,
        "source_appointment_id": 5001,
        "source_billing_payment_id": 2001,
        "total_amount": 1500.0,
        "calculation_status": "calculated",
        "calculated_at": "2024-09-04T10:00:00Z",
        "distributed_at": null,
        "distribution_breakdown": {
          "platform": {
            "amount": 900.0,
            "percentage": 60.0
          },
          "owner": {
            "amount": 600.0,
            "percentage": 40.0
          }
        }
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 2,
      "total_entries": 25
    }
  }
}

2. Show Revenue Share Calculation Details

Endpoint: GET /clinics/:clinic_id/revenue_share_calculations/:id

Parameters:

  • clinic_id: ID of the clinic
  • id: ID of the calculation

Response:

{
  "success": true,
  "data": {
    "calculation": {
      "id": 301,
      "clinic_revenue_share_config_id": 1,
      "source_appointment_id": 5001,
      "total_amount": 1500.0,
      "calculation_status": "calculated",
      "appointment_details": {
        "patient_name": "John Patient",
        "doctor_name": "Dr. Jane Doe",
        "appointment_date": "2024-09-03",
        "service_type": "consultation"
      },
      "distribution_breakdown": {
        "platform": {
          "stakeholder_id": 2,
          "amount": 900.0,
          "percentage": 60.0
        },
        "owner": {
          "stakeholder_id": 3,
          "amount": 600.0,
          "percentage": 40.0
        }
      }
    }
  }
}

3. Export Revenue Share Calculations

Endpoint: GET /clinics/:clinic_id/revenue_share_calculations/export

Parameters:

  • Same as list endpoint
  • format (optional): Export format (csv, xlsx)

Response: File download with calculation data

Error Handling

All API endpoints return consistent error responses:

{
  "success": false,
  "error": {
    "message": "Error description",
    "details": {
      "field": ["validation error"]
    }
  }
}

Common HTTP status codes:

  • 200 OK: Successful request
  • 201 Created: Resource created successfully
  • 400 Bad Request: Invalid request parameters
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 422 Unprocessable Entity: Validation errors
  • 500 Internal Server Error: Server error

Frontend Integration Guidelines

1. Authentication Setup

// Configure API client with authentication
const apiClient = axios.create({
  baseURL: "https://api.kulcare.com",
  headers: {
    Authorization: `Bearer ${getAuthToken()}`,
    "Content-Type": "application/json",
  },
});

2. Error Handling

// Global error handler
apiClient.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401) {
      // Handle authentication error
      redirectToLogin();
    }
    return Promise.reject(error);
  }
);

3. Pagination Handling

// Example pagination component
const fetchPaginatedData = async (page = 1, perPage = 20) => {
  const response = await apiClient.get(
    `/clinics/${clinicId}/revenue_distribution_queue`,
    {
      params: {
        page,
        per_page: perPage,
      },
    }
  );

  return {
    data: response.data.data.entries,
    pagination: response.data.data.pagination,
  };
};

4. Date Formatting

All dates should be sent in ISO 8601 format or YYYY-MM-DD format:

  • Full datetime: 2024-09-04T12:00:00Z
  • Date only: 2024-09-04
  • Period: 2024-09 (for monthly periods)

5. File Downloads

For export endpoints, handle file downloads properly:

const exportData = async () => {
  const response = await apiClient.get(
    `/clinics/${clinicId}/revenue_distribution_queue/export`,
    {
      responseType: "blob",
      params: { file_format: "csv" },
    }
  );

  const url = window.URL.createObjectURL(new Blob([response.data]));
  const link = document.createElement("a");
  link.href = url;
  link.setAttribute("download", "revenue_distribution.csv");
  document.body.appendChild(link);
  link.click();
};

Best Practices

  1. Always include authentication: Never make API calls without proper authentication
  2. Handle loading states: Show loading indicators during API calls
  3. Implement proper error handling: Display user-friendly error messages
  4. Use pagination: Always paginate large data sets
  5. Cache when appropriate: Cache configuration data that doesn't change frequently
  6. Validate inputs: Validate data on frontend before sending to API
  7. Use proper date formats: Ensure dates are in the correct format
  8. Handle network errors: Implement retry logic for network failures

API Reference Overview

Previous Page

PLACEHOLDER - Documentation Needed

Next Page

On this page

Table of ContentsOverviewAuthenticationClinic Stakeholders APIs1. List Clinic Stakeholders2. Create Clinic Stakeholder3. Delete Clinic Stakeholder4. Reinvite StakeholderRevenue Sharing APIs1. Commission Dashboard2. Revenue Share ConfigurationsList ConfigurationsCreate ConfigurationShow ConfigurationActivate ConfigurationCommission Management APIs1. List Commission Rules2. Show Commission Rule3. Create Commission Rule4. Update Commission RuleSettlement APIs1. List Settlements2. Generate Monthly Settlement3. Approve Settlement4. Process Settlement PaymentRevenue Distribution Queue APIs1. List Revenue Distribution Queue2. Export Revenue Distribution QueueRevenue Share Calculations1. List Revenue Share Calculations2. Show Revenue Share Calculation Details3. Export Revenue Share CalculationsError HandlingFrontend Integration Guidelines1. Authentication Setup2. Error Handling3. Pagination Handling4. Date Formatting5. File DownloadsBest Practices