Skip to main content

InvoicePayment — new fields sourceInvoiceId and relatedPaymentId

Summary​

The GraphQL type InvoicePayment (returned under Invoice.payments) now exposes two read-only linkage fields:

  • sourceInvoiceId — the invoice this payment draws from or applies to (a payment-on-account invoice or a credit note). null when the payment is not linked.
  • relatedPaymentId — the paired payment on the linked invoice, so both sides of the same transaction stay linked. null when not linked.

These mirror the existing relatedPayment field on InvoiceRefund, giving partners a symmetric way to trace payment-on-account drawdowns and credit-note applications without internal API access.

This release is additive: existing invoice and invoices calls behave as before. If you do not request the new fields, behaviour and performance are unchanged.

Population rules:

  • sourceInvoiceId and relatedPaymentId are both null for unlinked payments (e.g. cash, card via payInvoice, manual payments).
  • For payment-on-account drawdowns, sourceInvoiceId points to the POA invoice (type: paymentOnAccount) and relatedPaymentId points to the matching payment on that POA invoice.
  • For credit-note applications, sourceInvoiceId points to the credit note invoice (type: creditNote) and relatedPaymentId points to the matching payment on that credit note.

Query example​

query InvoicePaymentLinkage($id: ID!) {
  invoice(id: $id) {
    id
    payments {
      id
      paymentSource
      paymentAmount
      sourceInvoiceId
      relatedPaymentId
    }
  }
}

The invoices connection supports the same nested selection on each item in data.

Integration guidance​

  • Optional fields: Add sourceInvoiceId and relatedPaymentId only when your integration needs to trace POA or credit-note relationships; omit them otherwise.
  • Handle nulls: Expect both fields to be null for most payments.
  • Follow the link: Use sourceInvoiceId to fetch the source invoice (check its type to distinguish POA from credit note), and relatedPaymentId to identify the paired payment on that invoice.

If something breaks after this change​

Problems are unlikely unless you use strict schema validation that rejects unknown fields on InvoicePayment. Refresh your schema snapshot, regenerate clients, and extend your InvoicePayment types to include optional sourceInvoiceId and relatedPaymentId.

See also​