Skip to main content

invoices query — Healthcode submission and status filters

Summary​

The invoices query filters input now supports Healthcode reconciliation:

  • submittedToHealthcode — when true, return only invoices submitted to Healthcode (both healthcode.status and healthcode.providerReference are present on the invoice). When false, return only invoices that are not submitted (either field missing or empty).
  • healthcodeStatus — filter by Healthcode bill status using in and/or notIn. Status values use the HealthcodeBillStatus enum, mapped to the stored Healthcode status strings.

These filters compose with existing dateRange, pagination, options, filters.metadata, and filters.invoiceNumbers. Omitting healthcodeStatus applies no status filter.

This release is additive: existing invoices calls behave as before when the new filter fields are omitted.

Note: Healthcode fields are not yet exposed on the Invoice type; use these filters to list and reconcile submissions. Reading healthcode.status on individual invoices remains a separate change.

Examples​

# Submitted invoices only
query SubmittedHealthcodeInvoices {
  invoices(
    dateRange: { start: "2026-01-01", end: "2026-12-31" }
    pagination: { page: 1, pageSize: 50 }
    filters: { submittedToHealthcode: true }
  ) {
    data {
      id
      invoiceNumber
    }
    pageInfo {
      hasMore
    }
  }
}
# Submitted + specific statuses
query HealthcodeInvoicesByStatus {
  invoices(
    dateRange: { start: "2026-01-01", end: "2026-12-31" }
    pagination: { page: 1, pageSize: 50 }
    filters: {
      submittedToHealthcode: true
      healthcodeStatus: { in: [Validated, AwaitingCollection] }
    }
  ) {
    data {
      id
      invoiceNumber
    }
  }
}
# Exclude problematic statuses
query HealthcodeInvoicesExcludingStatuses {
  invoices(
    dateRange: { start: "2026-01-01", end: "2026-12-31" }
    pagination: { page: 1, pageSize: 50 }
    filters: {
      healthcodeStatus: { notIn: [AwaitingCorrection, Cancelled] }
    }
  ) {
    data {
      id
      invoiceNumber
    }
  }
}

Integration guidance​

  • submittedToHealthcode: Omit the field for no submission filter. Use true when polling or reconciling invoices that have been sent to Healthcode; use false to find invoices not yet submitted.
  • healthcodeStatus.in: Return invoices whose stored status matches any listed enum value.
  • healthcodeStatus.notIn: Exclude invoices with any listed status. You may combine in and notIn on the same request (both conditions apply).
  • Invalid status values: Unknown enum values are rejected at validation time with a 400-style GraphQL error.
  • Forward compatibility: Parse HealthcodeBillStatus defensively if you branch on status in client code; new enum values may be added in future releases.

See also​