Billing

The Billing API manages invoices, payments, and financial transactions across the Odento platform. Generate invoices for patients, record payments, and retrieve transaction history.

The Invoice Object

Field	Type	Description
id	string	Unique invoice ID (inv_*)
number	string	Human-readable invoice number
patient_id	string	Patient ID (pat_*)
items	array	Line items with description, quantity, unit_price, amount
subtotal	integer	Subtotal in paise (100 paise = 1 INR)
tax	integer	Tax amount in paise
total	integer	Total amount in paise
status	enum	draft, sent, paid, partially_paid, overdue, void
due_date	string	ISO 8601 date
created_at	string	ISO 8601 timestamp (UTC)

GET/billing/invoices

List all invoices

Returns a paginated list of invoices. Filter by patient, status, or date range.

Parameters

Parameter	Type	Required	Description
patient_id	string	Optional	Filter by patient ID
status	string	Optional	Filter by status: draft, sent, paid, partially_paid, overdue, void
start_date	string	Optional	Invoices created on or after this date
end_date	string	Optional	Invoices created on or before this date
limit	integer	Optional	Results per page (1-100). Default: 20
cursor	string	Optional	Pagination cursor

Example Request

Requestbash

curl -X GET "https://api.odento.app/api/v1/billing/invoices?status=overdue&limit=10" \
  -H "X-API-Key-ID: ok_live_abc123def456ghi789jkl012" \
  -H "X-API-Key-Secret: os_abc123def456ghi789jkl012mno345pqr678stu901vwx234yzab567"

Example Response

Response200json

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "inv_4a7b9c1d2e5f8a3b",
        "number": "INV-2025-0042",
        "patient_id": "pat_5f8d3a2b1c9e4a7b",
        "items": [
          {
            "description": "Dental consultation",
            "quantity": 1,
            "unit_price": 50000,
            "amount": 50000
          },
          {
            "description": "Scaling and polishing",
            "quantity": 1,
            "unit_price": 150000,
            "amount": 150000
          }
        ],
        "subtotal": 200000,
        "tax": 36000,
        "total": 236000,
        "status": "overdue",
        "due_date": "2025-01-10",
        "created_at": "2025-01-01T10:00:00Z"
      }
    ],
    "pagination": {
      "has_more": false,
      "next_cursor": null,
      "per_page": 10
    }
  }
}

Try It Out

API Playground— try it out

https://api.odento.app

Headers

This is a simulated response — no real API calls are made from the browser.

POST/billing/invoices

Create an invoice

Creates a new invoice for a patient. Line items define the services rendered. The invoice is created in 'draft' status — send it to the patient using the send endpoint.

Parameters

Parameter	Type	Required	Description
patient_id	string	Required	Patient ID (pat_*)
items	array	Required	Array of line items with description, quantity, unit_price
due_date	string	Optional	Due date (YYYY-MM-DD). Default: 15 days from creation
notes	string	Optional	Notes visible to the patient

Example Request

Requestbash

curl -X POST https://api.odento.app/api/v1/billing/invoices \
  -H "X-API-Key-ID: ok_live_abc123def456ghi789jkl012" \
  -H "X-API-Key-Secret: os_abc123def456ghi789jkl012mno345pqr678stu901vwx234yzab567" \
  -H "Content-Type: application/json" \
  -d '{
    "patient_id": "pat_5f8d3a2b1c9e4a7b",
    "items": [
      {
        "description": "Dental consultation",
        "quantity": 1,
        "unit_price": 50000
      },
      {
        "description": "Scaling and polishing",
        "quantity": 1,
        "unit_price": 150000
      }
    ],
    "due_date": "2025-02-01",
    "notes": "Payment due within 15 days. Thank you!"
  }'

Example Response

Response201json

{
  "success": true,
  "data": {
    "id": "inv_4a7b9c1d2e5f8a3b",
    "number": "INV-2025-0042",
    "patient_id": "pat_5f8d3a2b1c9e4a7b",
    "items": [
      {
        "description": "Dental consultation",
        "quantity": 1,
        "unit_price": 50000,
        "amount": 50000
      },
      {
        "description": "Scaling and polishing",
        "quantity": 1,
        "unit_price": 150000,
        "amount": 150000
      }
    ],
    "subtotal": 200000,
    "tax": 36000,
    "total": 236000,
    "status": "draft",
    "due_date": "2025-02-01",
    "notes": "Payment due within 15 days. Thank you!",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

GET/billing/invoices/{id}

Retrieve an invoice

Retrieves a single invoice by ID, including all line items and payment history.

Parameters

Parameter	Type	Required	Description
id	string	Required	The invoice ID (inv_*)

Example Request

Requestbash

curl -X GET https://api.odento.app/api/v1/billing/invoices/inv_4a7b9c1d2e5f8a3b \
  -H "X-API-Key-ID: ok_live_abc123def456ghi789jkl012" \
  -H "X-API-Key-Secret: os_abc123def456ghi789jkl012mno345pqr678stu901vwx234yzab567"

Example Response

Response200json

{
  "success": true,
  "data": {
    "id": "inv_4a7b9c1d2e5f8a3b",
    "number": "INV-2025-0042",
    "patient_id": "pat_5f8d3a2b1c9e4a7b",
    "items": [
      {
        "description": "Dental consultation",
        "quantity": 1,
        "unit_price": 50000,
        "amount": 50000
      }
    ],
    "subtotal": 50000,
    "tax": 9000,
    "total": 59000,
    "amount_paid": 59000,
    "amount_due": 0,
    "status": "paid",
    "due_date": "2025-02-01",
    "payments": [
      {
        "id": "pay_abc123",
        "amount": 59000,
        "method": "upi",
        "reference": "UPI-987654321",
        "paid_at": "2025-01-16T14:20:00Z"
      }
    ],
    "created_at": "2025-01-15T10:30:00Z"
  }
}

POST/billing/invoices/{id}/payments

Record a payment

Records a payment against an invoice. Supports multiple payment methods. When the total paid equals or exceeds the invoice total, the invoice status automatically changes to 'paid'.

Parameters

Parameter	Type	Required	Description
id	string	Required	The invoice ID (inv_*)
amount	integer	Required	Payment amount in paise
method	string	Required	Payment method: cash, card, upi, bank_transfer, cheque
reference	string	Optional	Payment reference number (transaction ID, cheque number, etc.)
paid_at	string	Optional	Payment date (ISO 8601). Default: current time

Example Request

Requestbash

curl -X POST https://api.odento.app/api/v1/billing/invoices/inv_4a7b9c1d2e5f8a3b/payments \
  -H "X-API-Key-ID: ok_live_abc123def456ghi789jkl012" \
  -H "X-API-Key-Secret: os_abc123def456ghi789jkl012mno345pqr678stu901vwx234yzab567" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 59000,
    "method": "upi",
    "reference": "UPI-987654321",
    "paid_at": "2025-01-16T14:20:00Z"
  }'

Example Response

Response201json

{
  "success": true,
  "data": {
    "id": "pay_abc123",
    "invoice_id": "inv_4a7b9c1d2e5f8a3b",
    "amount": 59000,
    "method": "upi",
    "reference": "UPI-987654321",
    "paid_at": "2025-01-16T14:20:00Z",
    "invoice_status": "paid"
  }
}

GET/billing/transactions

List transactions

Returns a paginated list of all financial transactions across the organization. Useful for reconciliation and reporting.

Parameters

Parameter	Type	Required	Description
patient_id	string	Optional	Filter by patient ID
method	string	Optional	Filter by payment method: cash, card, upi, bank_transfer, cheque
start_date	string	Optional	Transactions on or after this date
end_date	string	Optional	Transactions on or before this date
limit	integer	Optional	Results per page (1-100). Default: 20
cursor	string	Optional	Pagination cursor

Example Request

Requestbash

curl -X GET "https://api.odento.app/api/v1/billing/transactions?start_date=2025-01-01T00:00:00Z&end_date=2025-01-31T23:59:59Z" \
  -H "X-API-Key-ID: ok_live_abc123def456ghi789jkl012" \
  -H "X-API-Key-Secret: os_abc123def456ghi789jkl012mno345pqr678stu901vwx234yzab567"

Example Response

Response200json

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "txn_xyz789",
        "invoice_id": "inv_4a7b9c1d2e5f8a3b",
        "patient_id": "pat_5f8d3a2b1c9e4a7b",
        "amount": 59000,
        "method": "upi",
        "reference": "UPI-987654321",
        "type": "payment",
        "paid_at": "2025-01-16T14:20:00Z"
      },
      {
        "id": "txn_abc456",
        "invoice_id": "inv_3b8c1d2e5f9a7b4c",
        "patient_id": "pat_3a7b9c1d2e5f8a4b",
        "amount": 120000,
        "method": "cash",
        "reference": null,
        "type": "payment",
        "paid_at": "2025-01-14T11:00:00Z"
      }
    ],
    "pagination": {
      "has_more": true,
      "next_cursor": "eyJwYWlkX2F0IjoiMjAyNS0wMS0xNFQxMTowMDowMFoifQ==",
      "per_page": 20
    }
  }
}

POST/billing/invoices/{id}/void

Void an invoice

Voids an invoice. This is only allowed for invoices in 'draft' or 'sent' status with no recorded payments. Voided invoices cannot be reactivated.

Parameters

Parameter	Type	Required	Description
id	string	Required	The invoice ID (inv_*)
reason	string	Optional	Reason for voiding (logged for audit)

Example Request

Requestbash

curl -X POST https://api.odento.app/api/v1/billing/invoices/inv_4a7b9c1d2e5f8a3b/void \
  -H "X-API-Key-ID: ok_live_abc123def456ghi789jkl012" \
  -H "X-API-Key-Secret: os_abc123def456ghi789jkl012mno345pqr678stu901vwx234yzab567" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Duplicate invoice created in error"
  }'

Example Response

Response200json

{
  "success": true,
  "data": {
    "id": "inv_4a7b9c1d2e5f8a3b",
    "status": "void",
    "voided_at": "2025-01-17T09:00:00Z"
  }
}

The Invoice Object

List all invoices

Parameters

Example Request

Example Response

Try It Out

Create an invoice

Parameters

Example Request

Example Response

Retrieve an invoice

Parameters

Example Request

Example Response

Record a payment

Parameters

Example Request

Example Response

List transactions

Parameters

Example Request

Example Response

Void an invoice

Parameters

Example Request

Example Response

Was this page helpful?