Skip to main content

Invoices

Invoices (FHIR Invoice) represent billing documents for healthcare services rendered. ClinikAPI simplifies the most common invoice fields — for advanced scenarios like complex price components or tax calculations, use the FHIR passthrough.

Create an Invoice

const { data: invoice } = await clinik.invoices.create({
  status: 'issued',
  patientId: 'pt_abc123',
  type: 'professional-services',
  issuerId: 'org_clinic456',
  date: '2024-03-15',
  lineItem: [
    {
      sequence: 1,
      chargeItemCode: '99213',
      priceComponent: [
        { type: 'base', amount: { value: 150.00, currency: 'USD' } },
      ],
    },
    {
      sequence: 2,
      chargeItemCode: '85025',
      priceComponent: [
        { type: 'base', amount: { value: 45.00, currency: 'USD' } },
      ],
    },
  ],
  totalNet: { value: 195.00, currency: 'USD' },
  totalGross: { value: 195.00, currency: 'USD' },
  paymentTerms: 'Net 30',
});

Draft Invoice

Create a draft invoice and issue it later:
const { data: draft } = await clinik.invoices.create({
  status: 'draft',
  patientId: 'pt_abc123',
  type: 'facility-charges',
  lineItem: [
    {
      sequence: 1,
      chargeItemCode: 'room-charge-semi-private',
      priceComponent: [
        { type: 'base', amount: { value: 1200.00, currency: 'USD' } },
      ],
    },
  ],
  totalGross: { value: 1200.00, currency: 'USD' },
});

// Issue the invoice when ready
await clinik.invoices.update(draft.id, { status: 'issued' });

Cancel an Invoice

await clinik.invoices.update('inv_abc123', {
  status: 'cancelled',
  cancelledReason: 'Duplicate invoice — services already billed under INV-2024-001',
});

Search Invoices

// All invoices for a patient
const { data } = await clinik.invoices.search({
  patientId: 'pt_abc123',
});

// Filter by status and date range
const { data: issued } = await clinik.invoices.search({
  status: 'issued',
  dateFrom: '2024-01-01',
  dateTo: '2024-03-31',
});

// Filter by issuer
const { data: byClinic } = await clinik.invoices.search({
  issuerId: 'org_clinic456',
  status: 'balanced',
});

Invoice Statuses

StatusDescription
draftInvoice is being prepared
issuedInvoice has been sent to the recipient
balancedInvoice has been fully paid
cancelledInvoice has been cancelled

Complete Field Reference

FieldTypeRequiredDescription
statusstringYesdraft, issued, balanced, cancelled
patientIdstringNoPatient the invoice is for
typestringNoInvoice type
recipientIdstringNoRecipient reference
datestringNoInvoice date (defaults to now)
issuerIdstringNoIssuing Organization ID
accountIdstringNoAccount ID
participantArrayNoParticipants involved
lineItemArrayNoLine items with pricing
totalNet{ value, currency? }NoTotal net amount
totalGross{ value, currency? }NoTotal gross amount
paymentTermsstringNoPayment terms
cancelledReasonstringNoReason for cancellation
notestringNoAdditional notes