Invoice-Related API Usage Guide

Overview

Aria offers an API to generate invoices, and several APIs for retrieving various types of invoice-related data. This article collates them and explains scenarios for using each, or choosing one over the other.

Quick Reference

For Understanding Invoice History Across an Account

get_invoice_history_m is your starting point when you need a broad view—use it to retrieve all invoices for an account or a specific master plan instance, optionally filtered by date range or voided status. A common use case is populating a billing history page or auditing past charges. It also supports filtering for rebilled invoices specifically, making it useful for identifying accounts that have had billing corrections.

get_pending_invoice_no_m is the narrower companion—use it when you specifically need to know if there's a pending invoice on an account or MPI. It answers "is there something waiting in the queue?" before you attempt to generate a new one, since generating a new invoice will fail if a pending one already exists.

get_invoices_to_writeoff_or_dispute_m returns invoices eligible for write-off or dispute based on your client's configured criteria. Use it upstream of any write-off or dispute action—it's the "show me what qualifies" call before committing to a financial adjustment. Common use cases include building a collections queue, feeding a write-off batch process, or auditing which accounts have invoices in a disputed state.

For Drilling Into a Specific Invoice's Contents

get_invoice_details_m is your primary call once you have an invoice number. It pulls all line items, tax details, proration info, service and plan associations, and payment plan schedules. It's the most information-dense read API in the group and is the right choice for rendering a full invoice view, debugging billing discrepancies, or feeding downstream reporting.

get_payments_on_invoice_m complements get_invoice_details_m by showing what has actually been collected rather than what was charged. It returns all payment records applied against a specific invoice—useful for payment reconciliation, auditing partial payments, verifying that a collection attempt posted correctly, and supporting customer service inquiries about payment status.

get_invoice_cm_details_m is a specialized pre-flight check used before issuing a credit memo. It tells you whether a credit memo can even be applied to a given invoice (flagging cases where the invoice is voided, pending, in dispute, fully paid, etc.) and returns the maximum creditable amount per line item. Use it before attempting to apply a credit, not as a general invoice lookup.

For Retrieving the Customer-Facing Statement

get_statement_for_invoice_m returns the rendered statement document—the formatted, human-readable output associated with an invoice—rather than raw data. Use this when you need to display or deliver the actual statement to a customer, or preview what they would receive. It supports alternate statement templates, making it useful for multi-brand scenarios.

For Creating or Generating Invoices

gen_invoice_m is the only write-path invoice generation API in the group. Use it when you need to proactively trigger invoicing outside of Aria's normal billing cycle. It supports advance invoicing, alternate bill days, and combining invoices when retroactive start dates would otherwise produce multiples. This is not a read API—it modifies data.

For Managing Invoices in a Pending State

manage_pending_invoice_m handles the lifecycle of pending invoices—approve, discard, or regenerate. It also allows you to trigger collection and statement sending at approval time. Use this in any workflow where invoices are reviewed before being finalized, or when you need to discard a bad invoice and optionally cancel its associated orders.

For Corrections and Writeoffs

void_invoice_m permanently voids an invoice and all associated transactions. This is irreversible—use it for clear-cut cases like test data, duplicate invoices, or invoices created in error. A reason code is required. It should not be confused with a credit memo; a void wipes the invoice entirely rather than offsetting it.

update_acct_invoice_m is a lightweight update for custom metadata fields only—<custom_status_label> and <client_notes>. No financial data is changed. Use it when your workflow needs to tag invoices with internal status markers or add free-text notes without touching billing data.