--- title: "Convert a treatment plan to an estimate using the selected tier's quantities." method: POST path: "/Estimates/{id}/convert-to-invoice" tags: ["Estimates"] --- # Convert a treatment plan to an estimate using the selected tier's quantities. `POST /Estimates/{id}/convert-to-invoice` ## Path parameters - `id` string, required ## Request body - ConvertToInvoiceRequest - `selectedTier` string - `consentMethod` string — How consent was captured for this acceptance. Defaults to "InApp" (tap-accept, no signature). Send "Signature" together with string? ConvertToInvoiceRequest.SignatureData and string? ConvertToInvoiceRequest.SignedName to record a drawn-signature acceptance. - `signatureData` string, nullable — Base64-encoded PNG of the signature (required when ConsentMethod=Signature). - `signedName` string, nullable — Typed name the signer provided (required when ConsentMethod=Signature). - `overrideReadiness` boolean — Bypass the convert-readiness gate even when lines are unresolved or take-home labels are outstanding. Requires a non-empty string? ConvertToInvoiceRequest.OverrideReason. Billing-permission gated (the controller requires Billing) and recorded on the consent timeline as a ConsentEventType.ConvertReadinessOverridden event. - `overrideReason` string, nullable — Why the readiness gate was overridden (required when OverrideReadiness=true). - `replaceExistingInvoice` boolean — Confirm replacing the appointment's existing (unpaid) invoice. An appointment can hold only one live invoice (`estimates.appointment_id` is uniquely indexed). When one already exists, convert returns `409 INVOICE_ALREADY_EXISTS`; re-send with this set to archive the old bill (it becomes InvoiceStatus.Superseded, keeping its lines as a record) and create the new one. A paid/partially-paid existing invoice is never replaced — that returns `409 INVOICE_PAID` and must be refunded/voided first. ## Response `200` OK - InvoiceDto - `id` string - `invoiceNumber` string - `clientId` string, nullable - `clientName` string, nullable - `patientId` string, nullable - `patientName` string, nullable - `appointmentId` string, nullable - `providerMode` string - `invoiceProviderId` string, nullable - `invoiceProvider` UserSummaryDto - `id` string - `email` string - `firstName` string, nullable - `lastName` string, nullable - `displayName` string, nullable - `type` string - `roleId` string, nullable - `roleName` string, nullable - `status` string - `amountPaid` union — Money the clinic is actually holding on this bill — `PaymentLedger.TotalPaid` (originals positive, refund rows negative). Zero for a bill refunded to net zero and for one carrying only pending or failed attempts. This is what gates void / revert / delete server-side; the UI reads it so it can't drift from the guard. Note that `Status` is a stored column and can disagree — this is the money truth. - number, double - string, double - `hasUnresolvedPayment` boolean — A payment here is still open: either an unconfirmed gateway outcome (`RequiresReview` — the card MAY have been charged) or a gateway-accepted debit that hasn't settled yet (a Pending ACH with a TransactionId — money in flight). An unpaid Text2Pay link is NOT open; it holds nothing. Deliberately excluded from decimal InvoiceDto.AmountPaid so it never inflates a balance, but it still blocks void / revert / delete until the settlement sweep or a human resolves it. - `subTotal` union - number, double - string, double - `taxableSubTotal` union - number, double - string, double - `taxRate` union - number, double - string, double - `taxAmount` union - number, double - string, double - `taxMode` string — "us-sales-tax" or "vat" — snapshot at estimate creation. - `discountTotal` union - number, double - string, double - `orderDiscountAmount` union - number, double - string, double - `ruleOrderDiscountAmount` union — Order-level discount produced by the price rule engine (separate from discount codes). - number, double - string, double - `totalAmount` union - number, double - string, double - `notes` string, nullable - `mergedIntoInvoiceId` string, nullable — Set when this invoice was merged into a new combined invoice (it is then Superseded): the id of the successor bill. - `mergedIntoInvoiceNumber` string, nullable — Human-readable number of the successor combined invoice this one was merged into (set only on a Superseded source). Lets the UI link forward without a second fetch. - `mergedFromInvoices` MergedInvoiceRefDto[] — The source invoices this combined bill was assembled from (empty for a normal invoice). Drives the "Combined from …" provenance shown on the merged invoice. - `id` string - `invoiceNumber` string - `patientName` string, nullable - `signatureData` string, nullable - `signedAt` string, date-time, nullable - `issuedAt` string, date-time, nullable — When the bill was issued (Draft → Unpaid) and its totals frozen. Null for Drafts and legacy invoices issued before the issue boundary. - `items` InvoiceLineItemDto[] - `id` string - `invoiceId` string - `serviceCatalogItemId` string, nullable - `retailItemId` string, nullable - `retailItem` RetailItemSummaryDto - `id` string - `sku` string - `barcode` string, nullable - `name` string - `invoiceName` string, nullable - `category` string - `unitPrice` union - number, double - string, double - `isTaxable` boolean - `isActive` boolean - `quantityOnHand` union - number, double - string, double - `isLowStock` boolean - `vendorId` string, nullable - `vendorName` string, nullable - `inventoryItemId` string, nullable - `billableItemId` string, nullable — Source BillableItem ("Charge") when this line was added from the charge catalog. - `billableItemName` string, nullable — Display name of the source BillableItem (snapshot, response-only). - `isFulfilled` boolean — True when a BillableItem charge line has been fulfilled — its inventory components dispensed (derived from linked transactions, response-only). - `inventoryTransactionId` string, nullable - `unitCost` union - number, double - string, double - `code` string, nullable - `description` string - `unitPrice` union - number, double - string, double - `quantity` union - number, double - string, double - `discount` union - number, double - string, double - `appliedDiscountPolicyId` string, nullable - `appliedDiscountCode` string, nullable - `ruleDiscount` union — Discount produced by the price rule engine (separate from the manual `Discount`). - number, double - string, double - `dispenseFee` union - number, double - string, double - `lineTotal` union - number, double - string, double - `isTaxable` boolean - `vatCategory` string, nullable - `lineTaxAmount` union - number, double - string, double - `providerId` string, nullable - `provider` UserSummaryDto - `id` string - `email` string - `firstName` string, nullable - `lastName` string, nullable - `displayName` string, nullable - `type` string - `roleId` string, nullable - `roleName` string, nullable - `notes` string, nullable - `displayOrder` union - integer - string, int32 - `groupCodeId` string, nullable — Kit this line came from, when emitted via GroupCode expansion. - `groupCodeName` string, nullable — Snapshot of the kit's display name at time of add. - `appliedDiscounts` AppliedDiscountDto[] - `id` string - `invoiceId` string - `discountPolicyId` string - `invoiceLineItemId` string, nullable - `discountCode` string - `discountName` string - `discountType` string - `discountValue` union - number, double - string, double - `calculatedAmount` union - number, double - string, double - `appliedBy` UserSummaryDto - `id` string - `email` string - `firstName` string, nullable - `lastName` string, nullable - `displayName` string, nullable - `type` string - `roleId` string, nullable - `roleName` string, nullable - `appliedAt` string, date-time - `appliedPriceRules` AppliedPriceRuleDto[] — Audit records of price rules that produced discounts on this estimate. - `id` string - `priceRuleId` string - `invoiceLineItemId` string, nullable - `ruleName` string - `ruleType` string - `calculatedAmount` union - number, double - string, double - `evaluatedAt` string, date-time - `createdBy` UserSummaryDto - `id` string - `email` string - `firstName` string, nullable - `lastName` string, nullable - `displayName` string, nullable - `type` string - `roleId` string, nullable - `roleName` string, nullable - `createdAt` string, date-time - `updatedAt` string, date-time --- [API](https://skmtc.net/clinicos/apis/pawthosx-business-api-v1.md) · [All operations](https://skmtc.net/clinicos/apis/pawthosx-business-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/clinicos/pawthosx-business-api-v1/revisions/d8d7501dde48/schema)