Invoices

AR invoices. Lines go in the same request - see Conventions on nested writes.

The object#

FieldTypeDescription
idread-onlyintegerNolaPro id.
invoicenumberstring(30)Invoice number. Auto-assigned from the company counter when not supplied.
ponumberstring(30)The customer's purchase order number.
wherefromintegerModule that raised the invoice: 2 = manual AR entry, 4 = billed from an order, fulfillment, or service order, 7 = billed from Estimating (print orders), 12 = generated by a payment-plan run, 44 = created by an RMA return.
orderidintegerOrderid. Id only.
orderbycompanyidintegerOrderbycompanyid. Id only.
shiptocompanyidintegerShiptocompanyid. Id only.
statusstringWhere the invoice is in its life. Labels are Arinvoice_model::$statuses. Stored as int -1/0/1/2/3/4; never exposed or accepted (D35). unposted means no GL voucher has been written yet, so lines can still be added; everything else means the ledger has been told. One of abandoned, unposted, open, paid, writeoff, refundedcredit.
customerbillcodestring(20)Customer Bill Code printed on the invoice.
shipcostmoneystring(4dp)Stored as decimal(19,4).
invoicetotalmoneystring(4dp)Stored as decimal(19,4).
invoicetermsidintegerInvoicetermsid. Id only.
invoicetermsstring(30)The verbal of the referenced invoiceterms, instead of the id. Send this or invoicetermsid, not both unless they agree.
salesmanidintegerSalesmanid. Id only.
salesmanstring(50)The name of the referenced salesmen, instead of the id. Send this or salesmanid, not both unless they agree.
invoicedatestringInvoice date - the accounting date the invoice posts under.
duedatestringDate payment is due.
discountdatestringLast date the early-payment discount applies.
discountamountmoneystring(4dp)Stored as decimal(19,4).
accruedinterestmoneystring(4dp)Stored as decimal(19,4).
datelastinterestcalcread-onlystringWhen finance-charge interest was last assessed on the invoice.
cancelbooleanCancelled. NolaPro cancels rather than deletes, so a cancelled row is still readable.
entrydatestringWhen the record was created.
lastchangedateread-onlystringLast modification. Drives modifiedsince.
pricelevelidintegerPricelevelid. Id only.
inventorylocationidintegerInventorylocationid. Id only.
inventorylocationstring(20)The locationcode of the referenced inventorylocations, instead of the id. Send this or inventorylocationid, not both unless they agree.
payment_methodstring(12)Payment method text carried in from the web store order the invoice came from.
shipping_methodstring(32)Shipping method text carried in from the web store order the invoice came from.
currencystring(10)Currency the invoice is raised in.
transaction_idstring(32)Gateway transaction id of the payment taken with the invoice (web store and POS sales).
customers_idintegerCustomers id. Id only.
customersstring(30)The customercode of the referenced customers, instead of the id. Send this or customers_id, not both unless they agree.
currency_valuenumberstring(6dp)Numeric string, 6 decimal places. Not money - do not apply currency rounding.
servicerepidintegerServicerepid. Id only.
servicerepstring(50)The name of the referenced salesmen, instead of the id. Send this or servicerepid, not both unless they agree.
discountappliedmoneystring(4dp)Stored as decimal(19,4).
payplanbooleanTrue when the invoice is a payment-plan template that generates recurring invoices.
payplan_periodintegerRecurrence period of the payment plan: 1 = daily, 2 = weekly, 3 = monthly, 4 = quarterly, 5 = yearly; anything else repeats every payplan_days days.
payplan_daysintegerInterval in days between generated invoices, when payplan_period does not name a standard period.
payplan_nextstringNext date the payment plan generates an invoice.
payplan_numtimesintegerRemaining number of invoices the plan will generate; -1 repeats indefinitely.
sales_categoriesidintegerSales categoriesid. Id only.
sales_categoriesstring(50)The description of the referenced salescategories, instead of the id. Send this or sales_categoriesid, not both unless they agree.
coverageinteger1 prints the coverage period - the date range the recurring invoice covers - on generated invoices.
formnumberstring(50)Form Number of the printed piece, for invoices billed from Estimating.
shiptoattnstring(100)Attention line printed with the ship-to address.
old_idread-onlystring(255)Invoice id in the system this record was imported from.
client_postring(30)The customer’s PO number for the invoice.
curratenumberstring(10dp)Numeric string, 10 decimal places. Not money - do not apply currency rounding.
arglaccountidintegerArglaccountid. Id only.
arglaccountstring(20)The name of the referenced glaccounts, instead of the id. Send this or arglaccountid, not both unless they agree.
leaseidintegerLeaseid. Id only.
costcodeidintegerCost code.
costcodestring(20)Code for the referenced costcode, instead of the id.
deliveredinteger1 once the invoiced goods are recorded as delivered.
carrierserviceid_preferredintegerCarrier service the customer prefers for this shipment.
b2bhiddenbooleanTrue hides the invoice from the customer’s B2B portal.
billtrustsentread-onlystringDate the invoice was sent to the Billtrust delivery service. Maintained by the send flow, so it cannot be written through the API.
contactnameidintegerContactnameid. Id only.
glcategoryidintegerGlcategoryid. Id only.
glcategorystring(20)The code of the referenced glcategories, instead of the id. Send this or glcategoryid, not both unless they agree.
interestforinvoiceidintegerInterestforinvoiceid. Id only.
interestforinvoicestring(30)The invoicenumber of the referenced invoices, instead of the id. Send this or interestforinvoiceid, not both unless they agree.
invoicenotificationmethodstring(1)How the customer wants this invoice delivered: E = email, M = mail, F = fax. Empty uses the customer default.
jobidintegerJobid. Id only.
taxclassidintegerTaxclassid. Id only.
taxclassstring(100)The name of the referenced taxclasses, instead of the id. Send this or taxclassid, not both unless they agree.
zlienidintegerZlienid. Id only.
emailsentread-onlystringDate the invoice was emailed. Maintained by the send flow, so it cannot be written through the API.
faxsentread-onlystringDate the invoice was faxed. Maintained by the send flow, so it cannot be written through the API.
isacustomerreturnstring(1)1 when the invoice is a credit raised for a customer return.
modifiedfromarinvoiceidintegerModifiedfromarinvoiceid. Id only.
modifiedfromarinvoicestring(30)The invoicenumber of the referenced invoices, instead of the id. Send this or modifiedfromarinvoiceid, not both unless they agree.
paiddateread-onlystringDate the invoice was fully paid.
paymethintegerPayment method: 1 = cash, 2 = check, 3 = credit card, 4 = ACH/EFT, 5 = card terminal; 0 = on account or unset.
priceadjustmentforinvoiceidintegerPriceadjustmentforinvoiceid. Id only.
priceadjustmentforinvoicestring(30)The invoicenumber of the referenced invoices, instead of the id. Send this or priceadjustmentforinvoiceid, not both unless they agree.
rentalinteger1 when the invoice bills a rental.
rentalconverttosalebooleanTrue when the invoice converts a rental into a sale.
taxadjustmentforinvoiceidintegerTaxadjustmentforinvoiceid. Id only.
taxadjustmentforinvoicestring(30)The invoicenumber of the referenced invoices, instead of the id. Send this or taxadjustmentforinvoiceid, not both unless they agree.
taxexemptidintegerTaxexemptid. Id only.
taxexemptstring(32)The exemptname of the referenced taxexempts, instead of the id. Send this or taxexemptid, not both unless they agree.
voucheridintegerVoucherid. Id only.
voucherstring(50)The voucher of the referenced gltransactions, instead of the id. Send this or voucherid, not both unless they agree.
billtoshiptoidintegerBilltoshiptoid. Id only.
defaultassetidintegerDefaultassetid. Id only.
passthruarinvoiceidintegerPassthruarinvoiceid. Id only.
passthruarinvoicestring(30)The invoicenumber of the referenced invoices, instead of the id. Send this or passthruarinvoiceid, not both unless they agree.
passthrucontactidintegerPassthrucontactid. Id only.
passthrucustomerbilltoshiptoidintegerPassthrucustomerbilltoshiptoid. Id only.
passthrucustomeridintegerPassthrucustomerid. Id only.
passthrucustomerstring(30)The customercode of the referenced customers, instead of the id. Send this or passthrucustomerid, not both unless they agree.
passthrufromarinvoiceidintegerPassthrufromarinvoiceid. Id only.
passthrufromarinvoicestring(30)The invoicenumber of the referenced invoices, instead of the id. Send this or passthrufromarinvoiceid, not both unless they agree.
specialpurposeread-onlystring(15)Marker on system-generated invoices with a special purpose - e.g. CCFEE for credit-card fee invoices - so sales reports can exclude them.
externalidstring(100)Your own key. Scoped to your company.
linesarray of InvoiceLine
_metaread-onlyobjectPresent only when the server has something to report, e.g. the invoice posted but the customer is now over their credit limit.
affectsinventorybooleanWhether this invoice withdraws stock. Leave it out. Omitted, it is derived, and derived is right in every normal case: - Invoice raised from an order or shipment - stock already left at the shipment, so the invoice moves nothing. Sending true here is rejected: it would withdraw the same units twice. - Direct invoice with stocked lines - it withdraws, because nothing else ever will. Send false only when importing history whose stock was already adjusted by another route. The response then carries an inventory_not_adjusted warning, because an invoice that sold goods and moved no stock is a discrepancy someone will chase later.

Endpoints#

GET/invoices/{id}/notes 200422

Notes on an invoice.

Operational context that lives with the document - why a price was changed, what a customer asked for, what to tell the driver. hide keeps a note off the printed invoice. A note with linenumber set belongs to that line rather than the document as a whole.

Requires scope invoices:read.

Parameters
NameInTypeNotes
idrequiredpathintegerThe invoice id.
When it fails
StatusCodeMeaning
422unknown_valueNo such parent record in this company.
curl \
  'https://acme.nolapro.com/!/api/v2/invoices/104/notes' \
  -H 'Authorization: Bearer $NP_TOKEN'
GET/invoices 200403

List invoices.

Requires scope invoices:read.

Parameters
NameInTypeNotes
statusquerystringRestrict to one status.
orderbycompanyidquerystringRestrict to one orderbycompanyid.
shiptocompanyidquerystringRestrict to one shiptocompanyid.
inventorylocationidquerystringRestrict to one inventorylocationid.
salesmanidquerystringRestrict to one salesmanid.
jobidquerystringRestrict to one jobid.
orderidquerystringRestrict to one orderid.
ponumberquerystringponumber. Partial match, case-insensitive.
invoicenumberquerystringPartial match, case insensitive.
cancelquerystringDefaults to false. Pass true or any.
modifiedsincequerystringRFC 3339 UTC timestamp. Returns only records changed since then, including cancelled ones - so cancel defaults to any rather than false when this is used. The response carries _meta.synced_through; store it and send it back next time.
externalidquerystringExact match on your own key.
includequerystringComma-separated extras to embed. Only custom_fields is available: the extra fields this install has defined on the record. Off by default, and an unrecognised value is refused rather than ignored. See Conventions.
When it fails
StatusCodeMeaning
403insufficient_scopeToken lacks read scope.
curl \
  'https://acme.nolapro.com/!/api/v2/invoices' \
  -H 'Authorization: Bearer $NP_TOKEN'
POST/invoices 201400422

Create.

Requires scope invoices:write.

Parameters
NameInTypeNotes
Body
FieldTypeDescription
customeridrequiredintegerWho is being invoiced.
datestringInvoice date. Defaults to today.
postbooleanPost the invoice to the general ledger. Defaults to true. Send false to create it as a DRAFT: no GL voucher is written, so lines can still be added with POST /invoicelines or changed with PATCH /invoicelines/{id}. Post it later by cancelling and re-raising, or build it fully before posting. Once an invoice carries a voucher its lines are closed to further change.
duedatestringPayment due date. Defaults to the invoice date.
ponumberstring(30)The customer's PO number.
shiptoidintegerShip-to company, if different from the customer.
numberstring(30)Invoice number. Leave it out and NolaPro allocates the next one.
externalidstring(100)Your own identifier for this record. Stored verbatim and returned on reads; GET /<resource>?externalid=... finds it again.
linesrequiredarray of objectAt least one line. The tax and the total are derived by NolaPro - do not send them.
When it fails
StatusCodeMeaning
400invalid_requestA required field was missing.
422period_closedThe GL period containing the date is closed.
422rule_violationNolaPro refused the document. message carries its reason.
422shipto_mismatchThe shiptoid belongs to a different customer.
422unknown_valueA reference did not resolve in this company.
curl -X POST \
  'https://acme.nolapro.com/!/api/v2/invoices' \
  -H 'Authorization: Bearer $NP_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: your-unique-key' \
  -d '{
    "customerid": 104,
    "date": "2026-08-02",
    "post": false,
    "duedate": "2026-08-02",
    "externalid": "crm-8842",
    "lines": [
        {
            "quantity": "3.000000",
            "price": "125.0000"
        }
    ]
}'
Response 201
{
    "invoicenumber": "INV-88421",
    "total": "125.0000",
    "posted": false,
    "voucherid": 104
}
POST/invoices/batch 207400422

Create many.

Requires scope invoices:write.

Parameters
NameInTypeNotes
Body array
FieldTypeDescription
customeridrequiredintegerWho is being invoiced.
datestringInvoice date. Defaults to today.
postbooleanPost the invoice to the general ledger. Defaults to true. Send false to create it as a DRAFT: no GL voucher is written, so lines can still be added with POST /invoicelines or changed with PATCH /invoicelines/{id}. Post it later by cancelling and re-raising, or build it fully before posting. Once an invoice carries a voucher its lines are closed to further change.
duedatestringPayment due date. Defaults to the invoice date.
ponumberstring(30)The customer's PO number.
shiptoidintegerShip-to company, if different from the customer.
numberstring(30)Invoice number. Leave it out and NolaPro allocates the next one.
externalidstring(100)Your own identifier for this record. Stored verbatim and returned on reads; GET /<resource>?externalid=... finds it again.
linesrequiredarray of objectAt least one line. The tax and the total are derived by NolaPro - do not send them.
When it fails
StatusCodeMeaning
400invalid_requestThe request was malformed.
422period_closedThe GL period containing the date is closed.
422rule_violationNolaPro refused the document. message carries its reason.
422shipto_mismatchThe shiptoid belongs to a different customer.
422unknown_valueA reference did not resolve in this company.
curl -X POST \
  'https://acme.nolapro.com/!/api/v2/invoices/batch' \
  -H 'Authorization: Bearer $NP_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: your-unique-key' \
  -d '[
    {
        "customerid": 104,
        "date": "2026-08-02",
        "post": false,
        "duedate": "2026-08-02",
        "externalid": "crm-8842",
        "lines": [
            {
                "quantity": "3.000000",
                "price": "125.0000"
            }
        ]
    }
]'
Response 207
{
    "results": [
        {
            "index": 1,
            "status": 1
        }
    ]
}
GET/invoices/{id} 200404

Retrieve one record.

Requires scope invoices:read.

Parameters
NameInTypeNotes
idrequiredpathintegerThe record id.
includequerystringComma-separated extras to embed. Only custom_fields is available: the extra fields this install has defined on the record. Off by default, and an unrecognised value is refused rather than ignored. See Conventions.
When it fails
StatusCodeMeaning
404not_foundNo record with that id.
curl \
  'https://acme.nolapro.com/!/api/v2/invoices/104' \
  -H 'Authorization: Bearer $NP_TOKEN'
Response 200
{
    "status": "abandoned",
    "lines": [
        {
            "itemid": 3391,
            "item": "WIDGET-1",
            "description": "Bracket, 4in galvanised",
            "quantity": "24.000000",
            "price": "14.2500",
            "taxable": true
        }
    ]
}
PATCH/invoices/{id} 200400404409422

Update.

Requires scope invoices:write.

Parameters
NameInTypeNotes
idrequiredpathintegerThe record id.
Body
FieldTypeDescription
ponumberstring(30)The customer's own PO reference. Amendable whatever the invoice has done.
duedatestringWhen payment is expected. Unposted invoices only - returns 422 once posted.
externalidstring(100)Your own identifier for this record.
When it fails
StatusCodeMeaning
400invalid_requestThe request was malformed.
404not_foundNo such record, or it belongs to another company.
409stale_recordIf-Match did not match; someone else changed it first.
422rule_violationNolaPro refused the change. message carries its reason.
curl -X PATCH \
  'https://acme.nolapro.com/!/api/v2/invoices/104' \
  -H 'Authorization: Bearer $NP_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: your-unique-key' \
  -d '{
    "ponumber": "INV-88421",
    "duedate": "2026-08-01"
}'
DELETE/invoices/{id} 200400409422

Cancel.

Requires scope invoices:cancel.

Parameters
NameInTypeNotes
idrequiredpathintegerThe record id.
When it fails
StatusCodeMeaning
400invalid_requestThe request was malformed.
409cannot_cancelSomething already depends on this document - a payment, a shipment, an invoice.
422period_closedThe current GL period is closed, so a reversal has nowhere to post.
422unknown_valueNo such record in this company.
curl -X DELETE \
  'https://acme.nolapro.com/!/api/v2/invoices/104' \
  -H 'Authorization: Bearer $NP_TOKEN'
POST/invoices/{id}/post 200404409422

Post this invoice to the general ledger.

Writes the GL voucher for a DRAFT invoice - one created with post: false. Until it is posted an invoice has no voucher, which is exactly what lets POST /invoicelines and PATCH /invoicelines/{id} change it. Posting closes it: the ledger has been told what the invoice is worth, so its lines stop being amendable. An already-posted invoice answers 409 rather than writing a second voucher.

Requires scope invoices:write.

Parameters
NameInTypeNotes
idrequiredpathinteger
When it fails
StatusCodeMeaning
404not_foundNo invoice with that id in this company.
409invoice_already_postedAlready posted. Nothing was written a second time.
422rule_violationNolaPro refused the document. message carries its reason.
422unknown_valueA reference did not resolve in this company.
422period_closedThe GL period the document posts into is closed, so the voucher has nowhere to go.
curl -X POST \
  'https://acme.nolapro.com/!/api/v2/invoices/104/post' \
  -H 'Authorization: Bearer $NP_TOKEN'
GET/invoices/{id}/pdf 200409

Printed invoice as a PDF

The invoice exactly as NolaPro prints it, including any attachments the Document Center is set to combine. Answers application/pdf, not JSON. Because the body is binary it cannot be carried inside a /batch results array; asking for it there returns 415 not_batchable. A draft is refused with 409 not_posted: the totals on an unposted invoice can still change, so there is no document to print yet. The screens do not offer it either.

Requires scope invoices:read.

Parameters
NameInTypeNotes
idrequiredpathintegerThe invoice id.
When it fails
StatusCodeMeaning
409The invoice is still a draft.
curl \
  'https://acme.nolapro.com/!/api/v2/invoices/104/pdf' \
  -H 'Authorization: Bearer $NP_TOKEN'