Change an invoice and claim it from your own system

This picks up after [Bill a visit and read back what it was paid](/help/security-and-integrations/bill-a-visit-and-read-back-what-it-was-paid). If you bill the visit with no body, the invoice stays a draft, and you can change it before the patient sees it. Every change here is made under the practitioner the invoice is for, through the same checks as the practice's own screens. ## Set a line to the price the insurer pays 1. `GET /api/v1/invoices/{invoiceId}/line-items/{lineItemId}/rates` lists the prices Practor knows for the line. 2. Pick one. Each rate says whose it is in `source`, its `amount`, and the `pricingSource` to send with it. The one the line has now has `current: true`. 3. `PUT /api/v1/invoices/{invoiceId}/line-items/{lineItemId}` with the whole line, and the price you chose in `unitPrice`. ```json { "code": "0190", "serviceDate": "2026-10-01", "quantity": 1, "unitPrice": 40000, "pricingSource": "medical_aid", "diagnoses": [{ "code": "J06.9", "primary": true }] } ``` You can send back the line as the invoice's `lineItems` gave it, with your changes in it. Practor works out the line's total, including any modifier that changes the price, and answers with the whole invoice. `POST /api/v1/invoices/{invoiceId}/line-items` adds a line, with an `Idempotency-Key`. `DELETE` on a line's address removes it. Lines change only while the invoice is a draft, or reopened for amending; otherwise the answer is a 422 that reads "This invoice cannot be edited in its current status". A code or modifier Practor doesn't know is a 422 that names it in `errors`. ## Issue the invoice `POST /api/v1/invoices/{invoiceId}/issue` issues it and tells the patient it's ready. These calls need the **Update** tick on **Invoices**. | Status | Message | What to do | | --- | --- | --- | | 422 | Only draft or amending invoices can be finalized | It's already issued | | 422 | Invoice must have at least one line item before finalizing | Add a line | | 422 | The codes that may not be billed together, each named | Remove or change one of them. The codes vary | ## Check the patient's cover with the insurer `POST /api/v1/coverages/{coverageId}/verification` asks the insurer whether the membership is valid. The answer is a 202 with the coverage, its `verificationStatus` now `pending`. The check runs after this answer comes back. Read the coverage again for `verificationStatus`, `verifiedAt` and `verificationMessage`, or listen for the `coverage.verified` webhook. A claim isn't sent until the cover is verified, so run this before the first claim on a cover. It needs the **Submit or verify** tick on **Medical insurance**. A practice is held to 30 checks a minute. | Status | Message | What to do | | --- | --- | --- | | 409 | This coverage is already being checked with the insurer. | Wait for the answer on the coverage | | 422 | Only medical insurance can be checked with an insurer. | Nothing to check: the patient pays for themselves | | 422 | Enrol for insurance claims before verifying eligibility. | The practice enrols in Practor first | | 422 | Insurance checks are not available to this practice yet. | Ask the practice to contact Practor support | ## Send the claim 1. `GET /api/v1/invoices/{invoiceId}/claim/readiness` lists every check the claim must pass. `ready` is `true` when all of them do. 2. `POST /api/v1/invoices/{invoiceId}/claim` sends it. To name the cover, send `{ "coverageId": "..." }`. Left out, it's the cover the invoice was last claimed against, or else the patient's first medical insurance. 3. The answer is a 202 with the claim. Read the outcome with `GET /api/v1/invoices/{invoiceId}/claim`, or from the `claim.status_changed` webhook. Claims need the **Submit or verify** tick on **Claims**, and a practice can send 30 a minute. | Status | Message | What to do | | --- | --- | --- | | 422 | The claim is not ready to send: ... | Fix each check it names. The list varies; the readiness request shows them all | | 422 | Issue the invoice before claiming for it. | Issue it first | | 422 | Insurance claims are not available to this practice yet. | Claims are switched on account by account. Ask Practor | ## Resubmit or reverse the claim The claim says what you can do next: `resubmittable` and `reversible`. | To | Send | When | | --- | --- | --- | | Send a corrected claim | `POST .../claim/resubmit` | The claim was rejected, or you reversed it | | Withdraw an accepted claim | `POST .../claim/reverse` | It was accepted, partly accepted, or a reversal failed | | Stop a request that never came back | `POST .../claim/cancel` | It still reads `submitting` or `reversing`. This doesn't contact the insurer | A partly accepted claim can't be resubmitted, because that would bill its accepted lines twice. Reverse it first. To change the invoice under an accepted claim: 1. Reverse the claim. 2. `POST /api/v1/invoices/{invoiceId}/amend` reopens the invoice. 3. Change its lines, then issue it again. 4. Resubmit the claim. | Message | What to do | | --- | --- | | Reverse the claim before amending | Reverse it first | | Past the 3-day amendment window | It can no longer be reopened. The practice can cancel it in Practor | | Invoice has recorded payments | It can't be reopened once anything was paid | | A claim cannot be resubmitted while it is accepted. Only a rejected or reversed claim can be resubmitted. | Reverse it first. The status in the message varies | The [submit a claim](https://developers.practor.app/reference/claims/claim-submit) page has the request and the answer in full, with the other claim requests beside it. ## Related - [Bill a visit and read back what it was paid](/help/security-and-integrations/bill-a-visit-and-read-back-what-it-was-paid) - [Get told when an invoice, claim or payment changes](/help/security-and-integrations/get-told-when-an-invoice-claim-or-payment-changes) - [Integration API errors and limits](/help/security-and-integrations/integration-api-errors-and-limits)