New Balance Invoice

{ "version": "v1.0", "type": "NEW_BALANCE_INVOICE", "id": "ckx1i0000001", "total": 575, "tax": 75, "discount": 0, "subtotal": 500, "taxPercent": 15, "discountPercent": 0, "diagnostic_fee": 0, "diagnostic_fee_discount": 0, "diagnostic_fee_tax": 0, "diagnostic_fee_insurance": 0, "file_no": "INV-00231", "reference_no": 231, "insurance_after_tax": 0, "patient_tax_percent": 15, "insurance_tax_percent": 0, "pre_auth": null, "invoice_line_ids": [], "patient_id": "ckx1p0000001", "patient_data": { "id": "ckx1p0000001", "name": "Sara Ahmed", "file_no": "P-00017", "reference_no": 1017, "nationalId": "1098765432", "phone": "+966501234567", "mobile": "501234567" }, "branch_data": { "id": "ckx1br000001", "name": "Riyadh Branch" }, "doctor_data": { "id": "ckx1u0000001", "name": "Dr. Omar Khaled" }, "insurance_company_data": { "id": "ckx1ic000001", "name": "Bupa Arabia" }, "insurance_policy_data": { "id": "ckx1ip000001", "name": "Sara Ahmed" }, "policy_class_data": { "id": "ckx1pc000001", "name": "Class A" } }

When it’s sent

Money is added to a patient’s balance (credit) directly.

A patient pays more than what’s left on an invoice. The extra amount goes to the patient’s balance, and Dentolize sends NEW_PAYMENT for the invoice payment, then NEW_BALANCE_INVOICE and NEW_BALANCE_PAYMENT for the extra.

The request type is NEW_BALANCE_INVOICE. See the introduction to subscribe to this event and verify the X-Hub-Signature-256 signature.

The payload has the same fields as New invoice, with an empty invoice_line_ids list.

Headers

X-Hub-Signature-256

string

HMAC SHA-256 of the raw request body, keyed with your Verify Token, as sha256=<hex>. Sent only when a Verify Token is set.

Example:

"sha256=3f1c5e…"

Body

application/json

Sent when money is added to a patient's balance (credit). Same fields as a new invoice; invoice_line_ids is always empty.

version

enum<string>

required

Payload version.

Available options:

v1.0

Example:

"v1.0"

type

enum<string>

required

Event type.

Available options:

NEW_BALANCE_INVOICE

Example:

"NEW_BALANCE_INVOICE"

string

Invoice ID.

Example:

"ckx1i0000001"

total

number

Invoice total.

Example:

575

tax

number

Tax amount.

Example:

75

discount

number

Discount amount.

Example:

0

subtotal

number

Subtotal before tax.

Example:

500

taxPercent

number

Tax percentage.

Example:

15

discountPercent

number

Discount percentage.

Example:

0

diagnostic_fee

number

Diagnostic fee.

Example:

0

diagnostic_fee_discount

number

Discount on the diagnostic fee.

Example:

0

diagnostic_fee_tax

number

Tax on the diagnostic fee.

Example:

0

diagnostic_fee_insurance

number

Insurance share of the diagnostic fee.

Example:

0

file_no

string | null

Invoice number.

Example:

"INV-00231"

reference_no

number | null

Invoice reference number.

Example:

231

insurance_after_tax

number

Insurance share after tax (0 when there is no insurance).

Example:

0

patient_tax_percent

number

Tax percentage applied to the patient share.

Example:

15

insurance_tax_percent

number

Tax percentage applied to the insurance share.

Example:

0

pre_auth

string | null

Insurance pre-authorization number.

Example:

null

invoice_line_ids

object[]

Always empty for balance invoices.

Show child attributes

Example:

[]

patient_id

string

Patient ID.

Example:

"ckx1p0000001"

patient_data

object

Basic patient details. Empty object {} when there is no patient.

Show child attributes

branch_data

object

Branch.

Show child attributes

Example:

{
  "id": "ckx1br000001",
  "name": "Riyadh Branch"
}

doctor_data

object

Treating doctor.

Show child attributes

Example:

{
  "id": "ckx1u0000001",
  "name": "Dr. Omar Khaled"
}

insurance_company_data

object

Insurance company.

Show child attributes

Example:

{
  "id": "ckx1ic000001",
  "name": "Bupa Arabia"
}

insurance_policy_data

object

Insurance policy. name is the policy holder name.

Show child attributes

Example:

{
  "id": "ckx1ip000001",
  "name": "Sara Ahmed"
}

policy_class_data

object

Insurance policy class.

Show child attributes

Example:

{ "id": "ckx1pc000001", "name": "Class A" }

Response

200

Return any 2xx status within 5 seconds to acknowledge the event. Failed deliveries are not retried.

API documentation

Webhooks

When it’s sent

Headers

Body

Response