Invoices Service

The `InvoicesService` is your primary tool for creating, retrieving, updating, and releasing AR Invoice records. It handles the full lifecycle of an invoice, from creation to final posting in the General Ledger.

Importing Helpers

Before using the service, import the necessary builders and query helpers from the `easy_acumatica.models` module.


from easy_acumatica.models.invoice_builder import InvoiceBuilder  
from easy_acumatica.models.query_builder import QueryOptions, CustomField  
from easy_acumatica.models.filter_builder import F

Core Methods

get_invoices(api_version, options=None)

This is the main method for fetching a list of invoice records. It can be used to get all invoices or a filtered, specific list by using `QueryOptions`.


# Create a filter for invoices with an 'Open' status
my_filter = (F.Status == 'Open')

# Use QueryOptions to select specific fields and page the results
opts = QueryOptions(
    filter=my_filter,
    select=["ReferenceNbr", "Type", "Customer", "Amount"],
    top=25
)

# Fetch the invoices
open_invoices = client.invoices.get_invoices("24.200.001", options=opts)

create_invoice(api_version, builder, options=None)

Use this method to create a new invoice. You must provide an `InvoiceBuilder` object containing the new invoice's details. This is also the method used to override tax details by setting `is_tax_valid(True)` and providing your own `TaxDetails`.


# Build the invoice payload with a tax override
invoice_payload = (
    InvoiceBuilder()
    .type("Invoice")
    .customer("AACUSTOMER")
    .description("Invoice with custom tax override")
    .is_tax_valid(True)  # Required to override taxes
    .add_detail_line("CONSULTING", 10, 100.0)
    .add_tax_detail("GST", 1000.0, 50.0)  # Manually specify tax
)

# Create the invoice
new_invoice = client.invoices.create_invoice("24.200.001", invoice_payload)

update_invoice(api_version, builder, options=None)

Use this method to update an existing invoice. You must identify the invoice by calling the `.id()` method on the `InvoiceBuilder` with the invoice's `NoteID` (GUID).


# The NoteID (GUID) of the invoice to update
invoice_note_id = "8deb6bf9-2072-eb11-b83e-00155d408001"

# Define the fields to update
update_payload = (
    InvoiceBuilder()
    .id(invoice_note_id)
    .set("Description", "Updated description for the invoice.")
)

# Perform the update
updated_invoice = client.invoices.update_invoice("24.200.001", update_payload)

Actions

release_invoice(api_version, note_id, ...)

This invokes the `ReleaseInvoice` action, which posts the invoice to the General Ledger, changing its status from `Balanced` to `Open`. This is a critical financial step that cannot be easily undone. The method handles asynchronous polling automatically, waiting for the action to complete on the server.


# The NoteID (GUID) of the invoice to release
invoice_note_id_to_release = "8beb2af9-fa58-ec11-9e16-9828a61840c3"

print(f"Releasing invoice {invoice_note_id_to_release}...")
client.invoices.release_invoice(
    "24.200.001",
    note_id=invoice_note_id_to_release
)
print("Invoice released successfully.")