Creating Sales Invoices in Acumatica via API

The Acumatica contract-based REST API provides comprehensive capabilities for creating and managing sales invoices programmatically. Whether you're automating billing workflows, integrating with a point-of-sale system, or processing orders from an e-commerce platform, the API enables seamless invoice creation with full control over line items, tax details, and applications.

Understanding the SalesInvoice Entity

The SalesInvoice entity is the primary endpoint for creating and managing sales invoices via the Acumatica REST API. It corresponds to the Invoices (SO303000) form and supports a wide range of fields and nested objects.

The key components of a SalesInvoice entity include:

• Invoice Header: Customer ID, Type, Date, Hold status
• Details: Line items with InventoryID, Quantity, Unit Price, and UOM
• Applications: Payment applications and credit memos
• Addresses: Bill-to and ship-to address overrides

Creating a Sales Invoice from a Sales Order

You can create a sales invoice directly from a sales order by specifying the order details in the invoice request.

Request Example

PUT /entity/Default/25.200.001/SalesInvoice?$expand=Details HTTP/1.1
Host: https://my.acumatica.com/MyInstance
Accept: application/json
Content-Type: application/json

{
    "CustomerID": { "value": "CAKEADO" },
    "Type": { "value": "Invoice" },
    "Hold": { "value": false },
    "Details": [
        {
            "OrderType": { "value": "SO" },
            "OrderNbr": { "value": "000066" },
            "OrderLineNbr": { "value": 1 },
            "Branch": { "value": "RETAIL" },
            "InventoryID": { "value": "APJAM08" },
            "Qty": { "value": 1 },
            "UOM": { "value": "PIECE" }
        }
    ]
}

Creating a Direct Sales Invoice

Direct sales invoices are invoices for which neither a sales order nor a shipment has been created. This is a typical scenario for integration with point-of-sale (POS) systems or when creating invoices for services.

Request Example

PUT /entity/Default/24.200.001/SalesInvoice?$expand=ApplicationsInvoice,Details HTTP/1.1
Host: https://my.acumatica.com/MyInstance
Accept: application/json
Content-Type: application/json

{
    "CustomerID": { "value": "FRUITICO" },
    "Type": { "value": "Invoice" },
    "Hold": { "value": false },
    "BillToAddressOverride": { "value": true },
    "BillToAddress": {
        "AddressLine1": { "value": "123 Fillmore Str" },
        "City": { "value": "San Francisco" },
        "Country": { "value": "CA" }
    },
    "Details": [
        {
            "Branch": { "value": "HEADOFFICE" },
            "InventoryID": { "value": "CHERJAM32" },
            "Qty": { "value": 1 },
            "UOM": { "value": "PIECE" }
        },
        {
            "Branch": { "value": "HEADOFFICE" },
            "InventoryID": { "value": "ADVERT" },
            "Qty": { "value": 1000 },
            "UOM": { "value": "DAY" }
        }
    ],
    "ApplicationsInvoice": [
        {
            "DocType": { "value": "Payment" },
            "DocNbr": { "value": "000076" },
            "AppliedToOrderAmt": { "value": 1235.27 }
        }
    ]
}

Creating Invoices from Shipments

You can prepare a sales invoice directly from a confirmed shipment using the PrepareInvoice action. This is the most efficient way to create invoices for fulfilled orders.

POST /entity/Default/25.200.001/Shipment/PrepareInvoice HTTP/1.1
Host: https://my.acumatica.com/MyInstance
Accept: application/json
Content-Type: application/json

{
    "entity": {
        "ShipmentNbr": { "value": "000067" }
    }
}

If the shipment is outgoing, the system generates a sales invoice of the Invoice type. If it's a return (incoming shipment), it generates a Credit Memo.

Releasing Invoices

After creating an invoice, you can release it using the ReleaseInvoice action. This is a long-running operation that finalizes the invoice in the system.

Request Example

POST /entity/Default/25.200.001/Invoice/ReleaseInvoice HTTP/1.1
Host: https://my.acumatica.com/MyInstance
Accept: application/json
Content-Type: application/json

{
    "entity": {
        "id": "8beb2af9-fa58-ec11-9e16-9828a61840c3"
    }
}

Managing Invoice Lifecycle

Invoice Statuses

• Hold: Invoice is on hold and cannot be released
• Balanced: Invoice is ready for release
• Released: Invoice has been finalized in the system
• Closed: Invoice has been fully paid

Handling Invoice Holds

To place an invoice on hold during creation, set the Hold field to true. This prevents accidental release until the invoice is reviewed.

{
    "CustomerID": { "value": "FRUITICO" },
    "Type": { "value": "Invoice" },
    "Hold": { "value": true }
}

Best Practices

Common API Endpoints Summary

Conclusion

The Acumatica contract-based REST API provides flexible, powerful capabilities for creating and managing sales invoices programmatically. Whether you're automating billing workflows, integrating with a POS system, or processing orders from an e-commerce platform, the API supports:

• Creating invoices from sales orders with line item details
• Creating direct sales invoices for POS and other integrations
• Preparing invoices from confirmed shipments
• Releasing invoices with long-running operations
• Managing invoice holds and statuses