07 · Bill
The claim grows as you bill. It is not assembled afterwards from memory.
Everything below elaborates this sentence.
Why this stop exists
Everything done to the patient becomes a line under the visit. The claim is built server-side as you go, so a line can be refused at the moment it is added rather than at submission.
This is an interchange. The eTIMS branch leaves the rail here, carrying the tax invoice and the patient's own share.
Add a bill line
Charge under an authorized service line. Name the line via service_line_ref; the payer
answers with what it covers and the patient's copay. Send the facility headers, as on every v2
visit call.
bill_line_refA bill line is payer-first: the rail sets the charge on the payer's system, and the
payer's answer — the covered amount and the patient's copay — is what gets persisted. The
line names a service_line_ref (from 04 · Visit), and through it the
cover, so the charge and the authorization it draws down cannot be paired inconsistently.
Code
code, quantity (above zero) and amount are required. practitioner_ref is required whenever a
service line is named, and must be a practitioner already added to the visit. invoice_number names
the invoice the charge belongs to, and is required on a Slade cover: see which invoice a charge
belongs to. The code is checked against the Terminology
Service, across every code system. The answer:
Code
status is billable once the payer has accepted the charge onto its claim. A line with no
service_line_ref is self pay and comes back billable with no cover.
code + nameamountthe payer's answerThe covered and owed amounts are the payer's, never computed here. A line the payer refuses is
recorded not-billable for the audit trail, but the call answers 400 BILL_LINE_REFUSED with the
payer's verdict as the message; there is no 200 body to read a status from. An unreachable payer
keeps the charge planned and answers PAYER_UNREACHABLE (502), safe to retry.
One item, several covers
A visit can draw on more than one cover. To apportion a single item, send splits instead of
service_line_ref. Each split posts its share to its own cover's claim, and whatever amount
leaves over is the patient's declared copay, recorded as a self-pay share.
Code
Split amounts cannot be negative or total more than amount, a service line can appear once, and
practitioner_ref is required as soon as one split names a line. The answer groups the shares under
one bill_item_ref: splits[] carries each cover's charge_ref, service_line_ref, cover,
split_amount, status, covered, patient_owes, claim_ref and refusal, and
patient_copay is the patient's total, the self-pay remainder plus every cover's copay. A payer
refusing any one share fails the whole item, so re-apportion against one consistent picture.
Which invoice a charge belongs to
A provider often holds more than one invoice for a single visit: one from the ward, one from the
pharmacy, one from the lab. The bill item says which one it belongs to by naming its
invoice_number. What the rail does with that number depends on who pays.
| Call | What it does | What you keep |
|---|---|---|
Slade cover | Payers on this rail pay per invoice, so each invoice number is its own claim. `invoice_number` is required: the first charge to name a new number opens that claim under the cover's authorization, and later charges naming it join it. The number sent when the visit opened is the cover's first claim. | claim_ref |
SHA cover | SHA pays per intervention, not per invoice, so the visit goes as one comprehensive claim. A charge may carry any invoice number, or none, and it still joins that one claim, under the invoice number you sent when the visit opened. | — |
A split item | Name `invoice_number` on each share rather than on the item, because each share joins its own cover's claim. A self-pay share has no claim and takes none. | — |
Code
An invoice number belongs to one cover's claim on the visit. Naming one that another cover's claim
already holds is 409 INVOICE_NUMBER_IN_USE, and a charge on a Slade cover with no invoice number
is 400 INVOICE_NUMBER_REQUIRED.
Close sends every claim on the visit, and there is no per-claim submit. Run the claim
pre-flight first: it names a Slade claim that has
no bill line yet (CLAIM_EMPTY), which the payer would refuse. The reason SHA gets one claim and
Slade gets one per invoice is in Why SHA gets one claim.
Lines that need preauthorisation
There is no held line. If the item's intervention needs a preauthorisation, the add is refused with
409 PREAUTH_REQUIRED until the service line's preauth is approved or partially approved, and
502 PREAUTH_VERIFY_FAILED if that could not be checked. Submit and await the decision at
06 · Preauthorize, then add the line.
What is checked on each add
The check runs on every add-line call, so the biller finds out at once. In order: the body, the
code against the Terminology Service (BILL_LINE_CODE_INVALID, 400), that the service line exists
and is authorized (SERVICE_LINE_MISSING, SERVICE_LINE_NOT_AUTHORIZED), the preauth above, that the
practitioner is on the visit (PRACTITIONER_NOT_ON_VISIT), and the cover's balance and remaining
uses (COVER_BALANCE_INSUFFICIENT, SERVICE_LINE_USES_EXHAUSTED, both 409). A tariff excess is not
a refusal: the line bills and the member owes the difference.
Documents travel with the line
Attach documents as they are captured rather than in a scramble at the end. The payer requires them before it accepts the claim at close.
Attach a supporting document to one cover's claim. Multipart, with the file in the attachment
field. cover names which of the visit's claims it belongs to, and document_type is the
payer's code, such as CLAIM_FORM or INVOICE. Add intervention_code only to tie the
document to one intervention; leave it off for claim-level documents. 409 CLAIM_MISSING_FOR_COVER
if no covered line has started that cover's claim yet.
claim_refAttach a document to a preauth that has already been submitted. Multipart, per service line
rather than per cover: send service_line_ref and document_type (such as DISCHARGE_SUMMARY
or LOU). 409 PREAUTH_NOT_SUBMITTED if the line has no preauth yet.
preauth_referenceGET /api/v2/visits/{visit_ref}/documents lists the documents the visit's claims and preauths
still require. It does not show what has been uploaded.
Accommodation and level changes
The payer computes the per-diem accrual, the days multiplied by the daily rate, and the visit's
claim read returns it as per_diem (days, daily_rate, amount) under
GET /api/v2/visits/{visit_ref}/claims. Your own day count is a cross-check rather than the source.
The day of admission is day one whatever the hour, and the counter increments at midnight.
When a patient moves between levels of care, the old line is retired and a new one starts, rather than being edited in place. That is a service-line switch, not a bill-line call:
POST /api/v2/visits/{visit_ref}/service-lines/{service_line_ref}/switch takes new_code (the
intervention to move to) and reason, which is CARE_LEVEL_CHANGED for this case (the others are
PROCEDURE_CHANGED, WRONG_SERVICE_SELECTED, CODING_CORRECTION and OTHER, the default). The old
line is superseded and a new one authorized in its place atomically. retain_bill_items asks the
payer to carry the captured items over, and bill_from and bill_to bound the switch for a payer
that accounts per diem; both are payer-honoured. The reason is kept for audit and not sent to the
payer.
Nothing is ever deleted. A wrong line is retired with a reason and a fresh one created, so the audit trail behind a benefit's balance survives every correction.
The price is not always the gazetted tariff
The level tariff you read at eligibility is only the default. Where a facility has a negotiated contract with a payer, the negotiated rate applies instead. It is the largest pricing error an integrator can make today without noticing, because a wrongly priced line looks no different from a correct one.
Read source before you read the number. It takes three values, and each one means something
different for your pricing:
| Call | What it does | What you keep |
|---|---|---|
GAZETTED | The published level tariff applies. What you read on the procedure is what you bill. | applicable_tariff |
NEGOTIATED | This facility has a contract for this scheme, and the level rule does not apply. Quoting the gazetted figure underbills or overbills every line. | applicable_tariff, contract_reference |
BILL_TO_BALANCE | Public-officer covers can be billed above the tariff, against the member's balance. The tariff is not a ceiling here. | applicable_tariff, balance |
What a facility level may bill at all
Level decides more than price. Some work cannot be billed at some levels at all, and the refusal arrives at the line rather than when the item is chosen.
| Call | What it does | What you keep |
|---|---|---|
Level 2 | Primary care, basic laboratory, maternity and outpatient public-officer services only. No per diem, no dialysis, no major surgery. | — |
Level 3 and above | Per diem becomes billable. | — |
Level 4 and above | Dialysis becomes billable. | — |
Levels 5 and 6 | Emergency-fund claims can only be started here. | — |
Level 6 | Everything except primary care. | — |
Read the level from the facility registry rather than storing it, and filter what you offer by it. A picker that lists dialysis at a level 3 site produces a rejection, after a clinician has already spent time on it.
Per diem counts days, and the rules are strict
Per diem has its own arithmetic rather than being a daily version of fee-for-service, and most of the mistakes are in the counting.
- 01Day of admission is day oneRegardless of the time of day. A patient admitted at 23:40 has used a day.
- 02The counter increments at midnightNot on a rolling 24 hours. Two calendar days is two days even if it is ten hours.
- 03Same-day admission and discharge is rejectedThere is no zero-night per-diem claim. If the stay did not cross midnight, it is not this payment mechanism.
- 04Per diem cannot be mixed with a surgical packageChoose one. The combination is refused, and the refusal names codes rather than mechanisms.
- 05A per-diem line cannot be removed once addedCorrecting it means correcting the visit, not deleting the line. Add it deliberately.
Length-of-stay caps are per benefit, and some are per household per year rather than per visit, so a relative's admission can shorten what this patient may claim.
Surgery carries a global period
A surgical claim covers a window of care rather than a single act, and inside that window some rebates cannot be billed at all.
| Call | What it does | What you keep |
|---|---|---|
Minor surgery | One night | global period |
Major surgery | Three nights | global period |
Specialised surgery | Seven nights | global period |
Inside the global period, medical inpatient, critical care, mental health and palliative rebates cannot be billed. Beyond it, further nights are billed at the gazetted rebate rate and the admission has to be updated to a complication. Admission, procedure and discharge dates are all required on a surgical claim.
Two things can still be claimed separately: an unplanned return to theatre, and care unrelated to the original procedure. The claim has to be able to tell them apart, so do not fold either one into the original line.
Money is checked as you bill
The rail does not hold a reservation you can read. The balance is the payer's own figure, read live, and each covered add is checked against it before the payer is asked.
| Call | What it does | What you keep |
|---|---|---|
balance on the service line | uses_left and amount_left, with known: false when neither could be established. Null means not established, which is different from zero | balance |
coverage-check | POST /api/v2/visits/{visit_ref}/service-lines/{service_line_ref}/coverage-check with an amount previews the verdict (covered amount, patient share, limiting factor) with no side effects | coverage |
refusal on add | Zero uses left or a cover that cannot fund the line refuses the add, 409 | reason code |
An unknown balance soft-allows, so a payer that cannot answer does not stop the charge.
Every line carries its scheme code
A claim line is billed against a fund, and the scheme code on the line is what routes it there. Lines on one visit can legitimately carry different scheme codes, because a member's covers differ by benefit and the cover can be chosen per item.
Treat it as required on every line rather than as an override you occasionally set. A missing or wrong scheme code routes the line to the wrong fund, and comes back looking like an assessment dispute rather than a routing mistake.
Diagnoses, prescriptions and switching
These three rules reject claims and are easy to miss.
| Call | What it does | What you keep |
|---|---|---|
One primary diagnosis per procedure | Not one per claim. A standard claim needs at least one primary diagnosis against each procedure, and duplicate codes on the same claim are rejected. | the diagnosis per line |
Primary care takes exactly one | Two primary diagnoses on a primary care claim is a rejection, and the diagnosis catalogue is filtered to primary-care-applicable codes for those claims. | — |
Prescriptions come from the national catalogue | Dispensed quantity cannot exceed prescribed quantity, and some visit types exclude prescriptions entirely. | the catalogue code |
Switching between levels of care is priced per period. Moving a patient from inpatient to critical care and back, or inpatient to palliative, is allowed, and each period is priced at its own tariff rather than the whole stay at the higher one.
What breaks here
| Where it surfaces | What the desk sees | What actually went wrong |
|---|---|---|
| Bill | "The line was refused and the codes look fine individually" | The payer refused it. The call answered 400 BILL_LINE_REFUSED and the message is the payer's own verdict. |
| Bill | "The price came back different from our price list" | The rail resolves pricing from tariff, facility level and cover rather than from what you sent. Your price list is for your own invoice, not this one. |
| Bill | "We cannot edit the accommodation line" | Per-diem lines are retired through a service-line switch (reason CARE_LEVEL_CHANGED), never edited. Editing is not a supported operation. |
| Bill | "BILL_LINE_CODE_INVALID" | The code is not in the Terminology Service under any code system. Pick it from the terminology rather than typing it. |
| Where it surfaces | What the desk sees | What actually went wrong |
|---|---|---|
| Reconciliation | "Every line at this facility is paid at a different amount than we billed" | A negotiated contract exists and the gazetted level tariff was used. Read source from the tariff call before pricing anything. |
| Reconciliation | "We under-recovered on the public-officer covers" | Lines were clamped to the tariff. On those covers the balance is the ceiling, not the tariff. |
| Bill | "Dialysis was refused and the code is right" | Facility level. Dialysis is level 4 and above; per diem is level 3 and above. The picker offered something the site cannot bill. |
| Bill | "The per-diem claim was rejected for a same-day discharge" | There is no zero-night per diem. The day of admission is day one and the counter moves at midnight. |
| Bill | "We cannot bill the ICU days inside the surgical window" | Global period. Critical care, medical inpatient, mental health and palliative rebates are excluded for one, three or seven nights depending on the surgery. |
Errors
| HTTP | error | When |
|---|---|---|
| 400 | BILL_LINE_CODE_INVALID | The code is not a known terminology code. |
| 400 | BILL_LINE_REFUSED | The payer refused the line; its verdict is the message. |
| 400 | INVOICE_NUMBER_REQUIRED | A charge on a Slade cover named no invoice number, so there is no claim to put it on. |
| 404 | VISIT_NOT_FOUND | No visit under that reference. |
| 409 | VISIT_NOT_OPEN | The visit is closed. |
| 409 | INVOICE_NUMBER_IN_USE | The invoice number already names a claim on another cover of this visit. |
| 409 | SERVICE_LINE_MISSING | No service line under that reference on this visit. |
| 409 | SERVICE_LINE_NOT_AUTHORIZED | The line is pending, refused or consent_required, so there is nothing to draw down. |
| 409 | PREAUTH_REQUIRED | The intervention needs a preauthorisation that is not approved yet. |
| 409 | PRACTITIONER_NOT_ON_VISIT | practitioner_ref names nobody on the visit. |
| 409 | COVER_BALANCE_INSUFFICIENT | The cover cannot fund the line. |
| 409 | SERVICE_LINE_USES_EXHAUSTED | The service line has no billing submission left. |
| 502 | PREAUTH_VERIFY_FAILED | Whether the intervention needs preauth could not be checked. Retry. |
| 502 | PAYER_UNREACHABLE | The payer did not answer. The charge stays planned. Retry. |
A body that fails validation is a 400 whose error is the validation sentence rather than a stable
code.
The branch leaves here
Billing produces obligations the payer never sees: the tax invoice, and whatever the patient pays themselves. Those leave the rail at this stop:
- Invoice · eTIMS, for sending the tax invoice to KRA
- Collect · Slade Advantage, for taking the patient's share
Next
Next: 08 · Submit