Katixo/API DocumentationBeta

Hospital Billing

Create and manage patient bills, record payments across multiple modes (cash, card, UPI, insurance), generate receipts, and configure billing packages for common procedures. Bills can be linked to OPD appointments or IPD admissions and support GST-compliant tax calculations.

Base URL

https://hospital.katixo.com/api/v1

Endpoints

POST/api/v1/billing/bills

GET/api/v1/billing/bills

GET/api/v1/billing/bills/{billId}

PUT/api/v1/billing/bills/{billId}/finalize

POST/api/v1/billing/bills/{billId}/payments

GET/api/v1/billing/bills/{billId}/receipt

POST/api/v1/billing/packages

Authentication: All endpoints require a valid JWT Bearer token in the Authorization header. All IDs are UUIDs.

The BillResponse object

{
  "success": true,
  "message": "Bill retrieved successfully",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "billNumber": "BIL-2026-00045",
    "patientName": "Rajesh Kumar Patel",
    "patientUhid": "UHID-2026-004510",
    "admissionId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "appointmentId": null,
    "lineItems": [
      {
        "id": "11111111-1111-1111-1111-111111111111",
        "serviceType": "CONSULTATION",
        "description": "Orthopaedic Consultation - Dr. Vikram Singh",
        "quantity": 1,
        "rate": 500.00,
        "amount": 500.00
      },
      {
        "id": "22222222-2222-2222-2222-222222222222",
        "serviceType": "LAB_TEST",
        "description": "CBC (Complete Blood Count)",
        "quantity": 1,
        "rate": 350.00,
        "amount": 350.00
      },
      {
        "id": "33333333-3333-3333-3333-333333333333",
        "serviceType": "LAB_TEST",
        "description": "Blood Grouping & Rh Typing",
        "quantity": 1,
        "rate": 200.00,
        "amount": 200.00
      },
      {
        "id": "44444444-4444-4444-4444-444444444444",
        "serviceType": "BED_CHARGE",
        "description": "Semi-Private Room (per day)",
        "quantity": 5,
        "rate": 2000.00,
        "amount": 10000.00
      },
      {
        "id": "55555555-5555-5555-5555-555555555555",
        "serviceType": "SURGERY",
        "description": "Total Knee Replacement - Right",
        "quantity": 1,
        "rate": 85000.00,
        "amount": 85000.00
      },
      {
        "id": "66666666-6666-6666-6666-666666666666",
        "serviceType": "PHARMACY",
        "description": "Medicines & consumables",
        "quantity": 1,
        "rate": 4520.00,
        "amount": 4520.00
      }
    ],
    "subtotal": 100570.00,
    "discountPercent": 5.00,
    "discountAmount": 5028.50,
    "taxAmount": 0.00,
    "totalAmount": 95541.50,
    "amountPaid": 50000.00,
    "balance": 45541.50,
    "status": "PARTIALLY_PAID",
    "payments": [
      {
        "id": "77777777-7777-7777-7777-777777777777",
        "amount": 50000.00,
        "paymentMode": "BANK_TRANSFER",
        "referenceNumber": "NEFT-UTR-2026061200012345",
        "paidAt": "2026-06-10T11:00:00Z"
      }
    ],
    "createdAt": "2026-06-10T09:30:00Z",
    "finalizedAt": "2026-06-10T10:45:00Z"
  },
  "errors": null
}

Bill statuses

Status	Description
`DRAFT`	Bill created but not yet finalized. Line items can still be added or modified.
`FINALIZED`	Bill has been finalized and is ready for payment. No further edits allowed.
`PAID`	Full payment received. Balance is zero.
`PARTIALLY_PAID`	Some payment received but balance is still outstanding.
`CANCELLED`	Bill has been cancelled. Remains in the system for audit purposes.

Service types

Type	Description
`CONSULTATION`	Doctor consultation fees (e.g. Orthopaedic Consultation: ₹500).
`LAB_TEST`	Laboratory investigations (e.g. CBC Test: ₹350, Blood Grouping: ₹200).
`PROCEDURE`	Medical procedures such as ECG, X-Ray, dressing changes.
`PHARMACY`	Medicines and consumables dispensed from the pharmacy.
`BED_CHARGE`	Room/bed charges per day (e.g. Semi-Private Room: ₹2,000/day).
`SURGERY`	Surgical procedure charges including surgeon and OT fees.
`OTHER`	Any other charges not covered by the categories above.

Create a bill

POST/api/v1/billing/bills

Creates a new patient bill in DRAFT status. The bill must be linked to either an IPD admission or an OPD appointment. Returns 201 Created on success.

Request body

Field	Type	Required	Description
`patientId`	UUID	Yes	ID of the patient.
`admissionId`	UUID	Conditional	IPD admission ID. Required if no appointmentId is provided.
`appointmentId`	UUID	Conditional	OPD appointment ID. Required if no admissionId is provided.
`lineItems`	LineItemRequest[]	Yes	At least one line item. See line item fields below.
`discountPercent`	BigDecimal	No	Overall discount percentage on the bill (e.g. 5.00 for 5%).
`discountAmount`	BigDecimal	No	Fixed discount amount. If both percent and amount are provided, amount takes precedence.

LineItemRequest fields

Field	Type	Required	Description
`serviceType`	String	Yes	`CONSULTATION`, `LAB_TEST`, `PROCEDURE`, `PHARMACY`, `BED_CHARGE`, `SURGERY`, or `OTHER`.
`description`	String	Yes	Description of the service or item.
`quantity`	int	Yes	Quantity (e.g. number of days for bed charge, number of tests).
`rate`	BigDecimal	Yes	Rate per unit in INR.

Example: create a bill for an IPD patient

curl -X POST https://hospital.katixo.com/api/v1/billing/bills \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "patientId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "admissionId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "lineItems": [
      {
        "serviceType": "CONSULTATION",
        "description": "Orthopaedic Consultation - Dr. Vikram Singh",
        "quantity": 1,
        "rate": 500.00
      },
      {
        "serviceType": "LAB_TEST",
        "description": "CBC (Complete Blood Count)",
        "quantity": 1,
        "rate": 350.00
      },
      {
        "serviceType": "LAB_TEST",
        "description": "Blood Grouping & Rh Typing",
        "quantity": 1,
        "rate": 200.00
      },
      {
        "serviceType": "BED_CHARGE",
        "description": "Semi-Private Room (per day)",
        "quantity": 5,
        "rate": 2000.00
      },
      {
        "serviceType": "SURGERY",
        "description": "Total Knee Replacement - Right",
        "quantity": 1,
        "rate": 85000.00
      },
      {
        "serviceType": "PHARMACY",
        "description": "Medicines & consumables",
        "quantity": 1,
        "rate": 4520.00
      }
    ],
    "discountPercent": 5.00
  }'

# Response (201 Created)
{
  "success": true,
  "message": "Bill created successfully",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "billNumber": "BIL-2026-00045",
    "patientName": "Rajesh Kumar Patel",
    "patientUhid": "UHID-2026-004510",
    "admissionId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "appointmentId": null,
    "lineItems": [
      {
        "id": "11111111-1111-1111-1111-111111111111",
        "serviceType": "CONSULTATION",
        "description": "Orthopaedic Consultation - Dr. Vikram Singh",
        "quantity": 1,
        "rate": 500.00,
        "amount": 500.00
      },
      {
        "id": "22222222-2222-2222-2222-222222222222",
        "serviceType": "LAB_TEST",
        "description": "CBC (Complete Blood Count)",
        "quantity": 1,
        "rate": 350.00,
        "amount": 350.00
      },
      {
        "id": "33333333-3333-3333-3333-333333333333",
        "serviceType": "LAB_TEST",
        "description": "Blood Grouping & Rh Typing",
        "quantity": 1,
        "rate": 200.00,
        "amount": 200.00
      },
      {
        "id": "44444444-4444-4444-4444-444444444444",
        "serviceType": "BED_CHARGE",
        "description": "Semi-Private Room (per day)",
        "quantity": 5,
        "rate": 2000.00,
        "amount": 10000.00
      },
      {
        "id": "55555555-5555-5555-5555-555555555555",
        "serviceType": "SURGERY",
        "description": "Total Knee Replacement - Right",
        "quantity": 1,
        "rate": 85000.00,
        "amount": 85000.00
      },
      {
        "id": "66666666-6666-6666-6666-666666666666",
        "serviceType": "PHARMACY",
        "description": "Medicines & consumables",
        "quantity": 1,
        "rate": 4520.00,
        "amount": 4520.00
      }
    ],
    "subtotal": 100570.00,
    "discountPercent": 5.00,
    "discountAmount": 5028.50,
    "taxAmount": 0.00,
    "totalAmount": 95541.50,
    "amountPaid": 0.00,
    "balance": 95541.50,
    "status": "DRAFT",
    "payments": [],
    "createdAt": "2026-06-10T09:30:00Z",
    "finalizedAt": null
  },
  "errors": null
}

List bills

GET/api/v1/billing/bills

Returns a paginated list of bills. The response is wrapped in ApiResponse<PagedResponse<BillResponse>>.

Query parameters

Parameter	Type	Description
`patientId`	UUID	Filter by patient.
`status`	String	Filter by status: `DRAFT`, `FINALIZED`, `PAID`, `PARTIALLY_PAID`, `CANCELLED`.
`dateFrom`	LocalDate	Bills created on or after this date (YYYY-MM-DD).
`dateTo`	LocalDate	Bills created on or before this date.
`page`	int	Page number (zero-based, default: 0).
`size`	int	Results per page (default: 20).

curl "https://hospital.katixo.com/api/v1/billing/bills?status=PARTIALLY_PAID&dateFrom=2026-06-01&page=0&size=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

# Response
{
  "success": true,
  "message": "Bills retrieved successfully",
  "data": {
    "content": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "billNumber": "BIL-2026-00045",
        "patientName": "Rajesh Kumar Patel",
        "patientUhid": "UHID-2026-004510",
        "status": "PARTIALLY_PAID",
        "subtotal": 100570.00,
        "discountAmount": 5028.50,
        "taxAmount": 0.00,
        "totalAmount": 95541.50,
        "amountPaid": 50000.00,
        "balance": 45541.50,
        "createdAt": "2026-06-10T09:30:00Z"
      }
    ],
    "page": 0,
    "size": 10,
    "totalElements": 1,
    "totalPages": 1,
    "last": true
  },
  "errors": null
}

Get bill details

GET/api/v1/billing/bills/{billId}

Retrieves the full details of a bill including all line items, payment history, and computed totals. Returns ApiResponse<BillResponse>.

curl https://hospital.katixo.com/api/v1/billing/bills/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Finalize a bill

PUT/api/v1/billing/bills/{billId}/finalize

Transitions a bill from DRAFT to FINALIZED. Once finalized, line items cannot be added or modified. The bill is now ready to accept payments.

curl -X PUT https://hospital.katixo.com/api/v1/billing/bills/a1b2c3d4-e5f6-7890-abcd-ef1234567890/finalize \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

# Response
{
  "success": true,
  "message": "Bill finalized successfully",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "billNumber": "BIL-2026-00045",
    "status": "FINALIZED",
    "totalAmount": 95541.50,
    "finalizedAt": "2026-06-10T10:45:00Z"
  },
  "errors": null
}

Record a payment

POST/api/v1/billing/bills/{billId}/payments

Records a payment against a finalized bill. When total payments equal the bill total, the status automatically transitions to PAID. The bill must be in FINALIZED or PARTIALLY_PAID status.

Request body

Field	Type	Required	Description
`amount`	BigDecimal	Yes	Payment amount in INR.
`paymentMode`	String	Yes	`CASH`, `CARD`, `UPI`, `INSURANCE`, or `BANK_TRANSFER`.
`referenceNumber`	String	No	Transaction reference (UPI ref, card approval code, NEFT UTR, insurance claim number).

Example: record a UPI payment

curl -X POST https://hospital.katixo.com/api/v1/billing/bills/a1b2c3d4-e5f6-7890-abcd-ef1234567890/payments \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 45541.50,
    "paymentMode": "UPI",
    "referenceNumber": "426198374512"
  }'

# Response
{
  "success": true,
  "message": "Payment recorded successfully",
  "data": {
    "id": "88888888-8888-8888-8888-888888888888",
    "billId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "amount": 45541.50,
    "paymentMode": "UPI",
    "referenceNumber": "426198374512",
    "paidAt": "2026-06-12T16:30:00Z",
    "billStatus": "PAID",
    "billBalance": 0.00
  },
  "errors": null
}

Get payment receipt

GET/api/v1/billing/bills/{billId}/receipt

Returns the payment receipt as a PDF file. The response has Content-Type: application/pdf and the body is the raw PDF bytes. The receipt includes patient details, bill summary, all payments received, and the hospital's logo and address.

curl https://hospital.katixo.com/api/v1/billing/bills/a1b2c3d4-e5f6-7890-abcd-ef1234567890/receipt \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -o receipt_BIL-2026-00045.pdf

Billing packages

Billing packages bundle multiple services into a single predefined price. They are commonly used for standard procedures such as normal delivery, caesarean section, or cataract surgery. When a package is applied to a bill, all included services are added as line items at the package rate.

Create a billing package

POST/api/v1/billing/packages

Request body

Field	Type	Required	Description
`packageName`	String	Yes	Name of the billing package.
`departmentId`	UUID	Yes	Department this package belongs to (e.g. Obstetrics, Ophthalmology).
`services`	String[]	Yes	List of services included in the package.
`totalPrice`	BigDecimal	Yes	Total package price in INR.
`validityDays`	int	Yes	Number of days the package is valid from the date of admission.

Example: create a Normal Delivery Package

curl -X POST https://hospital.katixo.com/api/v1/billing/packages \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "packageName": "Normal Delivery Package",
    "departmentId": "c3d4e5f6-a7b8-9012-cdef-234567890123",
    "services": [
      "OB/GYN Consultation",
      "Labour Room Charges",
      "Delivery Charges",
      "Semi-Private Room (3 days)",
      "Neonatologist Visit",
      "Routine Lab Tests (CBC, Blood Group, Urine R/M)",
      "Medicines & Consumables",
      "Nursing Charges"
    ],
    "totalPrice": 25000.00,
    "validityDays": 5
  }'

# Response (201 Created)
{
  "success": true,
  "message": "Billing package created successfully",
  "data": {
    "id": "99999999-9999-9999-9999-999999999999",
    "packageName": "Normal Delivery Package",
    "departmentName": "Obstetrics & Gynaecology",
    "services": [
      "OB/GYN Consultation",
      "Labour Room Charges",
      "Delivery Charges",
      "Semi-Private Room (3 days)",
      "Neonatologist Visit",
      "Routine Lab Tests (CBC, Blood Group, Urine R/M)",
      "Medicines & Consumables",
      "Nursing Charges"
    ],
    "totalPrice": 25000.00,
    "validityDays": 5,
    "isActive": true,
    "createdAt": "2026-06-12T08:00:00Z"
  },
  "errors": null
}

Common packages: Normal Delivery Package ₹25,000 · Caesarean Section Package ₹55,000 · Cataract Surgery Package ₹18,000 · Appendectomy Package ₹35,000 · Master Health Checkup ₹2,500.

Error handling

All error responses follow the standard ApiResponse wrapper with success: false and details in the errors array.

# 400 Bad Request — validation error
{
  "success": false,
  "message": "Validation failed",
  "data": null,
  "errors": [
    "patientId: must not be null",
    "lineItems: must not be empty",
    "Either admissionId or appointmentId must be provided"
  ]
}

# 409 Conflict — payment exceeds balance
{
  "success": false,
  "message": "Payment amount exceeds balance",
  "data": null,
  "errors": ["Payment of \u20b950,000.00 exceeds remaining balance of \u20b945,541.50"]
}

# 422 Unprocessable Entity — invalid state transition
{
  "success": false,
  "message": "Cannot record payment",
  "data": null,
  "errors": ["Bill BIL-2026-00045 is in DRAFT status. Finalize the bill before recording payments."]
}