Invoice
Introduction #
The Invoice model represents a statement generated for a patient or their guarantor — who it was addressed to, what it totals, how it was sent, and where it stands.
Invoices are produced by Canvas billing workflows rather than by plugins: automated statement runs, batch runs, and one-off statements each record their origin in workflow.
Basic Usage #
from canvas_sdk.v1.data import Invoice
invoice = Invoice.objects.get(dbid=42)
If you have a Patient object, the statements addressed to them are available through the invoices reverse relation:
from canvas_sdk.v1.data import Patient
patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
invoices = patient.invoices.all()
A Claim points at the most recent statement it appeared on:
from canvas_sdk.v1.data import Claim
claim = Claim.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
invoice = claim.latest_invoice
Filtering #
from canvas_sdk.v1.data.invoice import Invoice, InvoiceStatus, InvoiceWorkflow
# Active statements only
active = Invoice.objects.filter(status=InvoiceStatus.ACTIVE)
# Statements a staff member generated one at a time, rather than by a batch or automated run
adhoc = Invoice.objects.filter(workflow=InvoiceWorkflow.ADHOC)
Invoice is addressed through recipient rather than a patient field, so filter on recipient to scope to one patient:
from canvas_sdk.v1.data import Invoice
invoices = Invoice.objects.filter(recipient__id="1eed3ea2a8d546a1b681a2a45de1d790")
Accessing the statement PDF #
The invoice_pdf_url property returns a presigned S3 URL for the statement’s PDF, or None when the invoice has no PDF. The URL is valid for one hour, so generate it when you need it rather than storing it.
from canvas_sdk.v1.data import Invoice
invoice = Invoice.objects.get(dbid=42)
# Presigned S3 URL to the statement PDF, or None if there is no PDF
url = invoice.invoice_pdf_url
The document reference #
Canvas also attaches the same PDF to a DocumentReference, which carries the statement’s document coding and status and represents it in the FHIR API. Use invoice_pdf_url to get the file itself, and the document reference when you want that metadata.
To find it, resolve the ContentType for the invoice and match object_id against the invoice’s dbid:
from canvas_sdk.v1.data import ContentType, DocumentReference, Invoice
invoice = Invoice.objects.get(dbid=42)
content_type = ContentType.objects.filter(
app_label="quality_and_revenue", model="invoicefull"
).first()
document = DocumentReference.objects.filter(
content_type=content_type, object_id=invoice.dbid
).first()
url = document.document_url if document else None
Attributes #
Invoice #
| Field Name | Type |
|---|---|
| dbid | Integer |
| created | DateTime |
| modified | DateTime |
| originator | CanvasUser |
| recipient | Patient |
| recipient_type | InvoiceRecipients |
| total_amount | Decimal |
| invoice_pdf | File (S3 key) |
| invoice_pdf_url | String (computed) |
| status | InvoiceStatus |
| workflow | InvoiceWorkflow |
| error_message | String |
| sent_mean | InvoiceSentMeans |
error_message carries the reason a statement failed to go out, and is empty for statements that did not fail.
Enumeration types #
InvoiceRecipients #
Who the statement was addressed to.
| Value | Label |
|---|---|
| patient | Patient |
| guarantor | Guarantor |
InvoiceStatus #
| Value | Label |
|---|---|
| active | Active |
| error | Error |
| archived | Archived |
InvoiceWorkflow #
How the statement was produced.
| Value | Label |
|---|---|
| automated | Automated |
| adhoc | Adhoc |
| batch | Batch |
InvoiceSentMeans #
| Value | Label |
|---|---|
Questions? Create an issue.