Where charges come from
Outcome
You know which upstream sources feed the Charges worklist, what each one looks like in the UI, and which questions to ask when a charge looks wrong.
The shape of ingestion
There are four supported source types, all flowing into the same
service.charge table:
| Source | Typical shape | Where it shows in the app |
|---|---|---|
| Push API (real-time) | A POST from the source system per service event | Charges list — usually the freshest. |
| SFTP file feed | Nightly drop of CSV / X12 / fixed-width / HL7 | Charges list — same row shape as push, just batched. |
| HL7 v2 listener | TCP/MLLP feed of ADT / DFT messages | Charges list. |
| FHIR R4 | Encounter / ServiceRequest resources via push | Charges list. |
What ingestion did to your charge
Each charge keeps a thread back to the inbound batch and the raw record:
| Field on the charge detail | Meaning |
|---|---|
| Source feed | The named feed (e.g. KipuEMR-prod, PointClickCare-CSV). |
| Ingestion batch | The inbound batch this charge came from. |
| Source record ID | The natural key the EMR used (so dedupe can find it next time). |
| Mapped at | Timestamp of the mapping run. |
| Validation issues | Any pre-billing failures the validator raised. |
Click Source record to see the raw fields the platform parsed. This is essential when a charge looks wrong and you suspect upstream data is the problem.
Your charge worklist
Open /charges. The default view filters to active statuses:
| Status | What it means | Your move |
|---|---|---|
RECEIVED | Just arrived; mapper hasn't run yet | Wait. |
MAPPED | Mapper ran cleanly; validator queued | Wait. |
NEEDS_FIX | Validation failed on at least one rule | See 2.3 — Fix validation issues. |
VALIDATED | Ready to bill | See 2.2 — Charges worklist. |
BILLED | A claim has consumed this charge | Read-only. |
VOIDED | Cancelled (by upstream or by you) | Read-only. |
A charge can move backward (e.g. BILLED → VALIDATED if you reverse
the claim) — that's normal.
When upstream is the problem
A charge that looks structurally wrong (member ID off, date of service in the future, units = 0) is almost always an upstream issue. The order of fixes:
Confirm the raw. Open the Source record tab on the charge. Does the wrong value live in the raw record? If yes — fix in the EMR, then let the next ingestion overwrite (the platform supports
is_currentupserts on natural-key collision).Confirm the mapping. If the raw is right but the charge is wrong, the mapping is. Tag the charge with
mapping-suspectand route to the tenant admin (chapter 5 of the Tenant Manual).Override in-app — last resort. If neither upstream fix is possible in time (e.g. timely-filing pressure),
Edit chargelets you correct the charge directly. The audit row stays. See 2.6 — Edit or correct a charge.
Validation
| Check | Expected |
|---|---|
| Every charge carries a Source feed | Yes; if blank, the feed wasn't tagged in ingestion. |
| Source record opens | Yes; if not, the raw was purged (rare) or the user lacks audit.read. |
NEEDS_FIX charges show issues inline | Yes; the validator writes one issue per failing rule. |
VOIDED charges cannot be re-billed | Correct. Re-ingest under a new natural key if the EMR voided in error. |
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| New charges aren't showing | Feed paused, batch failed, or your facility filter excludes them | Check /admin/ingestion/feeds (admin) for last-run status. |
| Same charge appears twice | Natural-key collision from upstream | Open both — the duplicate carries is_current=false; only the current is billable. |
| Charge has no member | Member match failed in mapping (no MRN→member match) | Tag and route; do not edit blindly. |
| Charge has wrong DOS | Upstream sent it | Fix at source; let ingestion overwrite. |
Where to next
- 2.2 — Charges worklist — the daily view.
- 2.3 — Fix validation issues — repair
the
NEEDS_FIXqueue.