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 predicate logical operator ( and or or ) dynamic field filtering any field from the invoice metadata can be used as a query parameter except reserved fields ( customerids , customerid , includes , paymentstatus , page , limit , predicate ) examples amount>=1000 filter by amount invoicedate>=2024 01 01 filter by date balance>0 filter by balance 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 high value overdue invoices const today = new date() toisostring() split('t')\[0]; const response = await fetch(`https //api nue io/invoices?amount>=5000\&duedate<${today}\&balance>0& predicate=and`, { 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 ) 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 ) 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" } }' 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 ) 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 ) 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 }