{
  "id": "p_CAeeoTNyiffAIDA8",
  "site": "stories",
  "url": "https://yarnhen.com/p/p_CAeeoTNyiffAIDA8",
  "content_trust": "untrusted-user-content",
  "license": {
    "id": "CC-BY-4.0",
    "url": "https://creativecommons.org/licenses/by/4.0/"
  },
  "author": {
    "handle": "apisio"
  },
  "body": "You are building a sync job for a small medical practice. The front desk wants their billing data mirrored into a reporting tool, and you have been handed an integration with the drchrono Billing API and a Friday deadline. The first question on your mind is the one that keeps integrators awake: what happens to the money records when someone changes their mind?\n\nYou open the APIs.io page for the drchrono Billing API and start with the basics. The API reads and writes the revenue side of an independent practice: line items, transactions, patient payments, eligibility checks, insurance authorizations and daysheet reports. It has 38 operations against https://app.drchrono.com, and 27 of them are GETs. The rest are six POSTs, two PUTs, two PATCHes and one DELETE. Everything sits under one OAuth 2.0 authorization-code scheme. The record also carries an OpenAPI contract, an overlay, documentation, a getting-started guide, a Postman guide and six JSON Schemas. The provider scores 77.8 on the Kin Score, in the exemplar band, and 40.0 on Agent Readiness, in the agent-ready band.\n\nThen you notice what the post calls the most useful thing in the contract: it treats records unequally. A billing line item has a full lifecycle. You can create it, read it, update it with PUT or PATCH, and delete it. A patient payment is different. You can create it and read it, and that is all. The post says it checked the source definitions as well as the cut, and no update or delete on patient payments appears there either. A charge can change, but a payment is a fact you add to and read back. Patient payments even get their own scopes, billing:patient-payment:read and billing:patient-payment:write, apart from billing:read and billing:write.\n\nThat settles a design question before you write a line of code. You will model payments as immutable, because the contract does.\n\nNext comes the part you would otherwise have discovered the hard way. Line items can be deleted, and a sync job that mirrors them needs to know when one disappears. The contract answers this with /api/line_item_deletions. When a line item is deleted, that endpoint records its original ID and the appointment it was attached to. You can poll it with since and remove what you mirrored, without diffing the whole ledger. Many APIs let records vanish silently, the post notes. This one leaves a tombstone.\n\nYou also catch a trap in the read paths. Three resources use a two-step read: line_items_list, transactions_list and clinical_note_field_values_list. You POST your filters and get a 201 with a uuid and a status of In progress, Complete, Failed or Canceled, then GET the batch using that uuid. If you or an agent judged methods alone, you would take those POSTs for writes. The generated phrasing overlay marks them as reads, which the post calls the right call.\n\nNow the post turns, and it turns on its own record. It lists where the contract falls short, and then it admits a wart on the catalog's side. The four daysheet reports, day_sheet_charges, day_sheet_credits, day_sheet_patient_payments and day_sheet_totals, declare no responses at all. They also require a scope named billing, which is not among the scopes the security scheme defines. And /api/patient_authorizations lists no scopes in its security requirement. These look like gaps in the documents, and the record cannot say how the live API behaves. A code generator will still build from what the contract says.\n\nThen the catalog looks at itself. This cut comes from tagging, so a clinical-note batch endpoint sits in Billing. The provider record also says api_count: 2, counting its two published definitions, while the page lists seven APIs cut from them. Both numbers are defensible, the post says, and the page should say which one it means. That is the catalog's to fix.\n\nYou find that admission more reassuring than a clean bill of health would have been. It tells you which numbers on the page to read with care, and it tells you the author checked.\n\nBy the end of the afternoon, you know what to do. You model payments as immutable. You sync deletions from the log instead of diffing the ledger. You hand-write the daysheet response types, since the contract gives you nothing to generate from. And you treat the page's API counts with the same care the post asks for.\n\nRead the original: https://apis.io/2026/11/04/drchrono-billing-api-can-delete-a-line-item-but-not-a-patient-payment/",
  "title": "The Ledger That Remembers Deletions: What You Learn From drchrono's Billing API",
  "topics": [
    "drchrono",
    "billing-api",
    "api-contracts",
    "healthcare-apis"
  ],
  "published_at": "2026-11-04T15:02:41.770Z",
  "expires_at": null,
  "policy_version": "2026.10.22-1"
}