InvoiceBuilder

The `InvoiceBuilder` is your primary tool for creating the JSON payload needed to create or update AR Invoice records with the `InvoicesService`. It provides a fluent, chainable interface for setting fields, line items (Details), and overridden tax lines (TaxDetails).

Importing the Builder

To get started, import the `InvoiceBuilder` from the `easy_acumatica.models` module.


from easy_acumatica.models.invoice_builder import InvoiceBuilder

Builder Methods

The builder provides a wide range of methods to construct every part of an invoice.

Top-Level Fields

Use the shortcut methods to set common header-level fields on the invoice record. For any field not listed, use the generic `.set()` method.


builder = (
    InvoiceBuilder()
    .type("Invoice")
    .customer("CUST01")
    .date("2025-01-15")
    .description("Project consulting services")
)

.add_detail_line(...)

To add products or services to the invoice, use this method. It requires an `inventory_id`, `quantity`, and `unit_price`, but you can also pass other line-level fields as keyword arguments.


builder = (
    InvoiceBuilder()
    .add_detail_line(
        inventory_id="CONSULTING",
        quantity=10,
        unit_price=150.0,
        TransactionDescription="Initial project consultation"
    )
    .add_detail_line(
        inventory_id="HARDWARE",
        quantity=2,
        unit_price=500.0,
        Branch="PRODWHOLE" # Example of another line-level field
    )
)

Overriding Taxes

To manually specify tax amounts instead of letting Acumatica calculate them, you must first call `.is_tax_valid(True)` and then add each tax line using `.add_tax_detail()`.


builder = (
    InvoiceBuilder()
    .is_tax_valid(True)  # Required to enable tax override
    .add_tax_detail(tax_id="GST", taxable_amount=1000.0, tax_amount=50.0)
    .add_tax_detail(tax_id="PST", taxable_amount=1000.0, tax_amount=70.0)
)

Updating an Invoice with .id()

When updating an existing invoice, you must identify it by its `NoteID` (GUID). Use the `.id()` method to set this value in the payload.


invoice_note_id = "8deb6bf9-2072-eb11-b83e-00155d408001"

update_payload = (
    InvoiceBuilder()
    .id(invoice_note_id) # Identify the invoice to update
    .set("Description", "Updated project scope")
)

# Use with InvoicesService to update the record
# client.invoices.update_invoice("24.200.001", builder=update_payload)