Invoice Preview

this guide covers the invoice preview endpoint ( post /orders/invoice preview ), which computes invoice data for both initial orders and change orders without persisting any data use it to show customers what they will be billed before committing to an order prerequisites before you begin, ensure you have a valid nue api key with order permissions for initial order previews a customer id and price book entry ids for change order previews asset numbers (sub xxxxxx format) for existing subscriptions basic knowledge of rest apis and json single endpoint, two modes the invoice preview endpoint handles both initial orders and change orders through a single post /orders/invoice preview call the request body determines which mode is used include orderproducts for an initial order preview include assetchanges for a change order preview you cannot include both in the same request authentication all invoice preview requests require authentication using your nue api key in the nue api key header const myheaders = new headers(); myheaders append("nue api key", "your api key here"); myheaders append("content type", "application/json"); key behaviors behavior details zero persistence the endpoint computes invoices entirely in memory no orders, subscriptions, or invoices are written to the database initial order preview provide orderproducts to preview invoices for a new order uses the same pricing engine as post /orders change order preview provide assetchanges to preview invoices for modifications to existing subscriptions uses the same pricing engine as post /change orders mutual exclusivity exactly one of orderproducts or assetchanges must be present sending both returns a validation error tax tax calculation is not supported on invoice previews to obtain tax amounts, create a draft order via post /orders instead forbidden options the options generateinvoice , activateinvoice , and asyncpayment are rejected with an error if set to true these are execution time flags that do not apply to previews initial order invoice preview preview invoices for a new order by providing orderproducts the request body accepts the same product fields as post /orders (see docid\ ikvnhfxqfd1r5zoti u7y ) basic example preview the invoice for a single product subscription const myheaders = new headers(); myheaders append("nue api key", "your api key here"); myheaders append("content type", "application/json"); const previewrequest = { customer { id "d2e04653 ae90 49df a986 134cf64f6d03" }, effectivedate "2025 07 01", orderproducts \[ { pricebookentryid "01uql000009tsn7yac", quantity 10, subscriptionstartdate "2025 07 01", subscriptionterm 12 } ] }; fetch('https //api nue io/orders/invoice preview', { method 'post', headers myheaders, body json stringify(previewrequest) }) then(response => response json()) then(result => { console log('invoice preview ', result); if (result previewinvoices && result previewinvoices length > 0) { const invoice = result previewinvoices\[0]; console log(`invoice amount $${invoice amount}`); console log(`start date ${invoice startdate}`); console log(`end date ${invoice enddate}`); // iterate invoice line items invoice items foreach(item => { console log(` ${item productname} $${item amount}`); }); } }) catch(error => console log('error ', error)); multiple products preview invoices for multiple products const previewrequest = { customer { id "d2e04653 ae90 49df a986 134cf64f6d03" }, effectivedate "2025 07 01", orderproducts \[ { pricebookentryid "01uql000009tsn7yac", quantity 10, subscriptionstartdate "2025 07 01", subscriptionterm 12 }, { pricebookentryid "01uql000009tsn8yac", quantity 5, subscriptionstartdate "2025 07 01", subscriptionterm 12 } ] }; fetch('https //api nue io/orders/invoice preview', { method 'post', headers myheaders, body json stringify(previewrequest) }) then(response => response json()) then(result => { if (result previewinvoices) { result previewinvoices foreach(invoice => { console log(`amount $${invoice amount}`); console log(`start ${invoice startdate}`); console log(`end ${invoice enddate}`); }); } }) catch(error => console log('error ', error)); bundle products bundles work the same as in post /orders — specify add ons for optional bundle components const previewrequest = { customer { id "d2e04653 ae90 49df a986 134cf64f6d03" }, effectivedate "2025 07 01", orderproducts \[ { pricebookentryid "01uql000009bundleabc", quantity 10, subscriptionstartdate "2025 07 01", subscriptionterm 12, addons \[ { productoptionid "opt impl service", productoptionquantity 20 } ] } ] }; fetch('https //api nue io/orders/invoice preview', { method 'post', headers myheaders, body json stringify(previewrequest) }) then(response => response json()) then(result => { console log('bundle invoice preview ', result previewinvoices); }) catch(error => console log('error ', error)); change order invoice preview preview invoices for changes to existing subscriptions by providing assetchanges the request body accepts the same change fields as post /change orders (see docid\ zsxm12tfkla93eqzgigm9 ) quantity update preview the billing impact of adding seats to an existing subscription const previewrequest = { assetchanges \[ { changetype "updatequantity", assetnumber "sub 00003725", quantity 25, startdate "2025 07 15" } ] }; fetch('https //api nue io/orders/invoice preview', { method 'post', headers myheaders, body json stringify(previewrequest) }) then(response => response json()) then(result => { if (result previews && result previews length > 0) { const preview = result previews\[0]; console log(`asset ${preview\ assetnumber}`); const summary = preview\ pricesummary; console log(`today's charge $${summary todaychargeprice}`); console log(`next billing period $${summary nextbillingperiodprice}`); console log(`next billing date ${summary nextbillingdate}`); const asset = preview\ previewresult; console log(`new quantity ${asset quantity}`); console log(`start date ${asset startdate}`); console log(`end date ${asset enddate}`); } }) catch(error => console log('error ', error)); renewal preview the invoice for renewing a subscription const previewrequest = { assetchanges \[ { changetype "renew", assetnumber "sub 00003725", renewalterm 12 } ] }; fetch('https //api nue io/orders/invoice preview', { method 'post', headers myheaders, body json stringify(previewrequest) }) then(response => response json()) then(result => { if (result previews) { const preview = result previews\[0]; console log(`total price $${preview\ pricesummary totalprice}`); console log(`new end date ${preview\ previewresult enddate}`); } }) catch(error => console log('error ', error)); upgrade preview the cost of upgrading to a higher tier product const previewrequest = { assetchanges \[ { changetype "upgrade", assetnumber "sub 00003725", targetpricebookentryid "01uem00000cnoaxiat", startdate "2025 07 15" } ] }; fetch('https //api nue io/orders/invoice preview', { method 'post', headers myheaders, body json stringify(previewrequest) }) then(response => response json()) then(result => { if (result previews) { const preview = result previews\[0]; console log(`today's charge $${preview\ pricesummary todaychargeprice}`); console log(`next period $${preview\ pricesummary nextbillingperiodprice}`); } }) catch(error => console log('error ', error)); cancellation preview any remaining charges or credits for cancelling a subscription const previewrequest = { assetchanges \[ { changetype "cancel", assetnumber "sub 00003725", cancellationdate "2025 08 01" } ] }; fetch('https //api nue io/orders/invoice preview', { method 'post', headers myheaders, body json stringify(previewrequest) }) then(response => response json()) then(result => { if (result previews) { const preview = result previews\[0]; console log(`cancellation date ${preview\ previewresult cancellationdate}`); console log(`today's charge $${preview\ pricesummary todaychargeprice}`); } }) catch(error => console log('error ', error)); cross sell (new products on change order) add new products alongside changes to existing subscriptions the products array requires at least one accompanying entry in assetchanges const previewrequest = { assetchanges \[ { changetype "renew", assetnumber "sub 00003725", renewalterm 12 } ], products \[ { pricebookentryid "01uql000009tsn8yac", quantity 5, subscriptionstartdate "2025 07 01", subscriptionterm 12 } ] }; fetch('https //api nue io/orders/invoice preview', { method 'post', headers myheaders, body json stringify(previewrequest) }) then(response => response json()) then(result => { console log('change order + cross sell preview ', result previews); }) catch(error => console log('error ', error)); request reference top level fields field type required description customer object yes (initial order) customer placing the order must contain an id field effectivedate string no effective date in yyyy mm dd format used for initial order previews orderproducts array yes (initial order) product lines for an initial order preview same schema as post /orders assetchanges array yes (change order) asset changes for a change order preview same schema as post /change orders products array no new products to add alongside a change order (cross sell) requires assetchanges billingperiod string no billing period for the order billingaccountid string no billing account id description string no order description customfields object no custom fields for the order timezone string no time zone for date calculations (change orders) ponumber string no purchase order number podate string no purchase order date in yyyy mm dd format forbidden options the following options are rejected with an error if set to true generateinvoice , activateinvoice , asyncpayment these are execution time flags that do not apply to previews validation rules rule error both orderproducts and assetchanges provided invoice preview invalid payload both orderproducts and products provided invoice preview invalid payload products provided without assetchanges change type combination required neither orderproducts nor assetchanges provided invoice preview missing body response reference the response shape depends on whether you submitted an initial order or change order preview initial order response for orderproducts requests, the response contains previewinvoices field type description previewinvoices array list of computed invoice objects previewinvoices\[] amount number total invoice amount previewinvoices\[] amountwithouttax number invoice subtotal amount previewinvoices\[] invoicedate string invoice date previewinvoices\[] duedate string payment due date previewinvoices\[] startdate string billing period start date previewinvoices\[] enddate string billing period end date previewinvoices\[] currencyisocode string iso currency code previewinvoices\[] items array invoice line items with per product billing detail change order response for assetchanges requests, the response contains previews field type description previews array list of per asset preview objects previews\[] assetnumber string the subscription asset number previews\[] pricesummary object aggregated billing summary (see below) previews\[] previewresult object updated asset state after the change (see below) previews\[] previewrequest object echo of the original change request for this asset price summary field type description totalprice number total price across all billing periods totalamount number total amount across all periods todaychargeprice number immediate charge price (prorated for mid cycle changes) todaychargeamount number immediate charge amount nextbillingperiodprice number price for the next full billing period nextbillingperiodamount number amount for the next billing period nextbillingdate string date of the next billing cycle preview result field type description assetnumber string subscription asset number quantity number quantity after the change term number term after the change startdate string subscription start date enddate string subscription end date after the change cancellationdate string cancellation effective date (cancel changes only) orderprice object order level pricing detail billingprice object billing level pricing detail changes array itemized list of changes applied childrenassets array child asset previews for bundle subscriptions