Skip to main content

Payments on account on the public API

Summary​

Two new queries are available for integrations that need payment-on-account balances and allocation history (for example GetPaid sync):

  • paymentsOnAccount — lists payments on account that still have an unallocated or partially allocated balance. Requires dateRange.start (ISO 8601) for incremental sync: records created or updated on or after that timestamp are returned. Supports pagination and options (same patterns as other list queries). Fully allocated payments are not included in the list.
  • paymentOnAccount — returns a single payment on account by id, including allocation history on the payments field and the original credit on originalPayment.

Both queries require the seeInvoices right (same as invoice / invoices).

Response fields​

At minimum, callers can use:

  • id, invoiceNumber
  • accountId, accountHolderName, patientId, patientName, and live patient / account for the holder
  • outstandingAmount — remaining unallocated balance as a positive number
  • originalPayment — amount, method, and related payment metadata from creation
  • payments — allocation lines, including invoiceId and invoiceNumber when known
  • createdAt, updatedAt

Example​

query PaymentsOnAccount($dateRange: DateRange!) {
  paymentsOnAccount(dateRange: $dateRange, pagination: { page: 1, pageSize: 50 }) {
    data {
      id
      accountId
      accountHolderName
      outstandingAmount
      updatedAt
    }
    pageInfo {
      hasMore
    }
  }
}
query PaymentOnAccount($id: ID!) {
  paymentOnAccount(id: $id) {
    id
    invoiceNumber
    outstandingAmount
    originalPayment {
      paymentAmount
      paymentSource
      paymentType
    }
    payments {
      paymentAmount
      paymentType
      invoiceId
      invoiceNumber
    }
    createdAt
    updatedAt
  }
}

Integration guidance​

  • Incremental sync: Pass the last successful watermark as dateRange.start. The list matches records where createdAt or updatedAt is on or after that time.
  • Outstanding filter: The list only returns records with remaining balance. Use paymentOnAccount(id: …) to fetch a fully allocated record by id when you need its history.
  • Not found: paymentOnAccount returns a standard not-found error when the id does not exist, is not visible to the token, or is not a payment on account.

Migration​

This release is additive. Existing invoice queries are unchanged.