Manage Invoices

manage invoices this guide provides comprehensive instructions for retrieving, updating, and deleting invoice data using the nue api retrieve invoices rest endpoints (recommended) nue provides rest endpoints for retrieving invoices with flexible filtering, pagination, and data enrichment 1\ global invoice listing get https //api nue io/invoices 2\ customer scoped invoices get https //api nue io/customers/{customerid}/invoices 3\ individual invoice get https //api nue io/invoices/{invoiceid} 4\ customer individual invoice get https //api nue io/customers/{customerid}/invoices/{invoiceid} query parameters pagination page page number (1 based, default 1) limit records per page (1 500, default 100) filtering paymentstatus filter by payment status status filter by invoice status customerid filter by customer id data enrichment includes=assets,orders,paymentapplications include related data example fetch customer invoices const response = await fetch('https //api nue io/customers/001ks00000dvz1ayad/invoices?status=active\&includes=assets', { headers { 'nue api key' 'your api key here', 'content type' 'application/json' } }); const result = await response json(); console log(`found ${result pagination total} invoices`); example advanced filtering // get invoices by payment status const response = await fetch('https //api nue io/invoices?paymentstatus=open', { headers { 'nue api key' 'your api key here' } }); legacy customerids support the legacy customerids parameter is still supported for backwards compatibility const customerids = '\["001ks00000dvz1ayad","002ks00000dvz1byad"]'; const response = await fetch(`https //api nue io/invoices?customerids=${encodeuricomponent(customerids)}`, { headers { 'nue api key' 'your api key here' } }); graphql endpoint (advanced) for advanced users who need direct graphql access, you can still use the graphql endpoint endpoint post https //api nue io/orders/async/graphql query query { invoice( where { and \[{customer {id { eq "001ks00000dvz1ayad"}}}, {status { eq "active"}}]} ) { amount amountwithouttax balance createddate customerid duedate enddate invoicedate name invoicepdf paymentstatus startdate status taxamount } } activate invoices activating an invoice moves it from a "draft" status to "active", making it payable and visible for collection workflows ( activate invoices https //api docs nue io/activate invoices ) for example, you can activate a list of invoices by providing the invoice ids in the api request curl x post "https //api nue io/billing/invoices\ activate" \\ h "nue api key {yourapikey}" \\ h "accept application/json" \\ h "content type application/json" \\ d '{ "invoiceids" \["5622f52c c234 4981 8ea3 aa58dc578604"] }' you can use a graphql filter in the api request to activate invoices that match the filter conditions, such as activating all draft invoices curl x post "https //api nue io/billing/invoices\ activate" \\ h "nue api key {yourapikey}" \\ h "accept application/json" \\ h "content type application/json" \\ d '{ "graphqlfilter" "{status { eq \\"draft\\"}}" }' additionally, you are allowed to change the invoice date or add a comment when activating an invoice curl x post "https //api nue io/billing/invoices\ activate" \\ h "nue api key {yourapikey}" \\ h "accept application/json" \\ h "content type application/json" \\ d '{ "invoiceids" \["5622f52c c234 4981 8ea3 aa58dc578604"], "invoicedate" "2025 07 01", "invoicecomment" { "comment" "approve and activate the invoice" } }' please note that if you change the invoice date when activating an invoice, the invoice due date will be recalculated automatically cancel invoices for invoices with incorrect data or if you want to regenerate new invoices for a specific billing period, you can cancel the invoices through the nue api ( cancel invoices https //api docs nue io/cancel invoices ) curl x post "https //api nue io/billing/invoices\ cancel" \\ h "nue api key {yourapikey}" \\ h "accept application/json" \\ h "content type application/json" \\ d '{ "invoiceids" \["5622f52c c234 4981 8ea3 aa58dc578604"], "invoicecomment" { "comment" "cancel the invoice due to incorrect billing info" } }' reverse invoices in certain regions (such as parts of europe), canceling an active invoice is not permitted by law in these cases, use the reverse invoices api to permanently negate an active invoice while keeping it historically visible in the system as reversed status unlike cancellation, reversal is only available for invoices in active status reverse a list of invoices synchronously curl x post "https //api nue io/billing/invoices\ reverse" \\ h "nue api key {yourapikey}" \\ h "accept application/json" \\ h "content type application/json" \\ d '{ "invoiceids" \["c055be5b 8185 4289 9856 098b88dd7049"], "invoicecomment" { "comment" "reverse the invoice" } }' for large batches, use the asynchronous endpoint to avoid timeouts curl x post "https //api nue io/billing/invoices\ async reverse" \\ h "nue api key {yourapikey}" \\ h "accept application/json" \\ h "content type application/json" \\ d '{ "invoiceids" \["c055be5b 8185 4289 9856 098b88dd7049"], "invoicecomment" { "comment" "reverse the invoice" } }' key behaviors when reversing an invoice if the invoice has been fully or partially paid, the payment is refunded and a credit back credit memo is generated if credit memos have been applied to the invoice, they are unapplied before reversal if a debit memo is associated with the invoice, it is reversed together with the invoice if newer billings exist on the same order products, reversal is blocked with an error once reversed, the billing state rolls back so the related order products can be billed again in a later billing run by default, reversed invoices cannot be deleted enable the allow deleting reversed invoices setting in nue system settings → invoices to allow deletion of reversed invoices via ui or api delete invoices once an invoice is in 'canceled' status and there are no payment actions applied to this invoice, you are allowed to delete it ( delete invoices https //api docs nue io/delete invoices ) curl x delete "https //api nue io/billing/invoices" \\ h "nue api key {yourapikey}" \\ h "accept application/json" \\ h "content type application/json" \\ d '{ "invoiceids" \["5622f52c c234 4981 8ea3 aa58dc578604"], "graphqlfilter" "{status { eq \\"canceled\\"}}" }' update an invoice for invoices with 'draft', 'pending activation', and 'active' statuses, you can make changes to certain fields and custom fields please note that this api ( update invoice https //api docs nue io/update invoice fields ) only supports updating one invoice at a time for example, you can change an invoice's bill to contact and the due date using the below api curl x patch "https //api nue io/billing/invoices/{invoiceid}" \\ h "nue api key {yourapikey}" \\ h "accept application/json" \\ h "content type application/json" \\ d '{ "duedate" "2025 08 30", "billtocontactid" "003ks000005imuiyao" }' the updated invoice will be returned { "activatedbyid" "424cb15f da63 4d6a b397 c15142058084", "salesaccountid" "001ks00000dvz1ayad", "enddate" "2025 06 30", "duedate" "2025 08 30", "source" "billing", "taxstatus" "not calculated", "shippingandhandling" 0, "balance" 226 330000000, "vatmessages" null, "id" "c52f7158 b164 44fa 93c5 e4b16420c371", "billtocontactid" "003ks000005imuiyao", "einvoicingmandateid" null, "createdbyid" "424cb15f da63 4d6a b397 c15142058084", "taxcompanycode" null, "einvoicingdocstatus" null, "appliedbyobject" null, "targetdate" "2025 06 30", "name" "inv 00000311", "externaltaxid" null, "currencyisocode" null, "taxamount" 0, "iscatchup" false, "startdate" "2025 01 01", "status" "active", "synctime" "2025 06 30t09 58 13 844+00 00", "ponumbers" null, "customfields" null, "taxerrormessage" null, "podates" null, "appliedbyid" null, "lastmodifiedbyid" "424cb15f da63 4d6a b397 c15142058084", "customerid" "001ks00000dvz1ayad", "paymentdetails" null, "paymentstatus" "nottransferred", "einvoicingmessage" null, "cancellationdate" null, "amountwithouttax" 226 330000000, "amount" 226 330000000, "comments" "\[{\\"comment\\" \\"approve and activate the invoice\\", \\"createtime\\" \\"2025 06 30t09 39 21z\\", \\"createusername\\" \\"jq test administrator\\"}]", "lastmodifieddate" "2025 06 30t09 58 12 870+00 00", "recordtype" "invoice", "einvoicingmandatecode" null, "entityid" null, "invoicedate" "2025 07 01", "accountingstatus" "not started", "invoicepdf" "https //app perftest nue io/view invoice/bpq4jwqgmawid1siznno8jzxz0xipknvwj7ivn0rmc8l1wxqmxqbwosrpdadn3u9wgwugodhlk8nm0khyakssbhd5qelbha8hkg0dxoawok 0gmpxplr1fxfdxglyissa0nbfwwzv7jive2kexcoatm2t8os2qr", "paymenthostedurl" null, "createddate" "2025 06 30t09 33 52 471+00 00", "activatedtime" "2025 06 30t09 39 21 165+00 00", "tenantid" "b5919513 9625 48d1 9954 8e2998ec0592", "externalinvoiceid" null, "einvoicingdocid" null }