Getting Started with Order Management

this guide walks you through the complete order management lifecycle in the nue self service api you'll learn the essential workflows from creating draft orders through activation, retrieval, modifications, and salesforce synchronization prerequisites before you begin, ensure you have a valid nue api key at least one customer created in your system access to your product catalog and price book entries basic understanding of rest apis and json authentication all order operations 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"); complete order lifecycle workflow this section demonstrates the typical end to end order process that most businesses follow step 1 create a new order as draft the first step is creating a draft order to preview pricing and configuration before committing to the purchase try it now create draft order → https //api docs nue io/create draft order const myheaders = new headers(); myheaders append("nue api key", "your api key here"); myheaders append("content type", "application/json"); // create a draft order with preview options const draftorderdata = json stringify({ "customer" { "id" "d2e04653 ae90 49df a986 134cf64f6d03" }, "options" { "previewinvoice" true, "calculatetax" false }, "effectivedate" "2024 12 24", "orderproducts" \[ { "pricebookentryid" "01uea000008icdeiac", "quantity" 5, "subscriptionstartdate" "2025 01 01", "subscriptionterm" 12 } ], "name" "annual platform license", "description" "customer's annual subscription order" }); fetch("https //api nue io/orders", { method 'post', headers myheaders, body draftorderdata }) then(response => response json()) then(result => { console log('draft order created ', result); // save the order id for next steps const draftorderid = result data order id; localstorage setitem('draftorderid', draftorderid); // display order details console log(`order id ${draftorderid}`); console log(`total amount $${result data order totalamount}`); console log(`annual contract value $${result data order orderacv}`); // if preview invoice was requested if (result data previewinvoices) { console log('preview invoice ', result data previewinvoices\[0]); } }) catch(error => console log('error ', error)); what happens this creates a draft order showing exact pricing, terms, and future billing without any financial impact step 2 activate the draft order once the draft order is approved, activate it to create actual subscriptions and begin billing try it now activate draft order → https //api docs nue io/activate draft order // get the draft order id from step 1 const draftorderid = localstorage getitem('draftorderid'); const activationdata = json stringify({ "options" { "generateinvoice" true, "activateinvoice" false // keep invoice as draft for now }, "ponumber" "po 2025 001", "podate" "2025 01 01", "transactionhub" { "externalsystem" "stripe", "externalid" "cus dksiwd123", "transactiontype" "customer" } }); fetch(`https //api nue io/orders/${draftorderid}`, { method 'post', headers myheaders, body activationdata }) then(response => response json()) then(result => { console log('order activated successfully ', result); // store activated order details const activatedorder = result data order; console log(`order number ${activatedorder ordernumber}`); console log(`status ${activatedorder status}`); console log(`activated date ${activatedorder activateddate}`); // access created subscriptions if (result data subscriptions) { result data subscriptions foreach(subscription => { console log(`subscription created ${subscription name}`); console log(`subscription id ${subscription id}`); }); } // save the customer id for next steps localstorage setitem('customerid', activatedorder customerid); }) catch(error => console log('error ', error)); what happens the order status changes to "activated", subscriptions are created, and the order automatically syncs to salesforce step 3 coterm new order products (optional) for organizations with existing subscriptions, you can align new order products with existing subscription end dates using the coterm capability this eliminates the need to specify subscriptionterm when you want the new service to end at the same time as an existing asset try it now create coterm order → https //api docs nue io/create draft order // create a new order product that aligns with existing subscription const cotermorderdata = json stringify({ "customer" { "id" "d2e04653 ae90 49df a986 134cf64f6d03" }, "options" { "previewinvoice" true, "calculatetax" false }, "effectivedate" "2025 05 06", "billingperiod" "annual", "orderproducts" \[ { "pricebookentryid" "01uea000008icdeiac", "quantity" 1, "subscriptionstartdate" "2025 05 06", "cotermasset" "sub 00000270", // aligns with this existing subscription "addons" \[ { "productoptionid" "01uea000008icdgiac", "productoptionquantity" 2, "subscriptionstartdate" "2025 05 06", "cotermasset" "sub 00000270" // add ons can also use coterm } ] } ], "name" "additional services coterm alignment", "description" "new services aligned with existing subscription end date" }); fetch("https //api nue io/orders", { method 'post', headers myheaders, body cotermorderdata }) then(response => response json()) then(result => { console log('coterm order created ', result); const order = result data order; console log(`order id ${order id}`); console log(`aligned with asset sub 00000270`); // the new subscription will automatically end when sub 00000270 ends order orderproducts foreach(product => { if (product cotermasset) { console log(`product ${product productname} aligned with ${product cotermasset}`); } }); }) catch(error => { if (error message includes('asset not found')) { console error('coterm asset sub 00000270 not found for this customer'); } else if (error message includes('date mismatch')) { console error('start date conflicts with coterm asset schedule'); } else { console error('error ', error); } }); what happens the new subscription automatically inherits the end date from the specified asset (sub 00000270), ensuring synchronized renewal cycles the subscriptionterm field is not required when using cotermasset co term capability benefits synchronized renewals all services renew together, simplifying contract management simplified billing consolidated renewal dates reduce administrative overhead flexible alignment works for both main products and add ons automatic calculation system calculates appropriate term based on existing asset end date error handling common coterm errors include asset not found (verify the asset belongs to the customer) and date mismatches (ensure start date is compatible with the existing asset's schedule) step 4 retrieve customer orders after activation, retrieve the customer's order history to see the new order and any existing orders try it now fetch customer orders → https //api docs nue io/fetch customer orders // get customer id from previous step const customerid = localstorage getitem('customerid'); const customerids = \[customerid]; const encodedids = encodeuricomponent(json stringify(customerids)); fetch(`https //api nue io/orders?customerids=${encodedids}\&includes=orderproducts\&status=activated`, { method 'get', headers myheaders }) then(response => response json()) then(result => { console log('customer orders retrieved ', result); result data foreach(order => { console log(`\\\norder ${order ordernumber}`); console log(`status ${order status}`); console log(`total $${order totalamount}`); console log(`placed ${order orderplaceddate}`); // display products in this order if (order orderproducts) { console log('products '); order orderproducts foreach(product => { console log(` ${product productname} ${product quantity} x $${product listprice}`); // save subscription info for change orders if (product subscriptionstartdate) { localstorage setitem('assetnumber', product name || `sub ${product id slice( 6)}`); } }); } // check if pdf is available if (order orderpdf) { console log(`order pdf ${order orderpdf}`); } }); }) catch(error => console log('error ', error)); what happens you can see all activated orders for the customer, including the one just created step 5 create a change order (customer modification) later, when the customer wants to modify their subscription (increase quantity, upgrade, etc ), create a change order change orders support various modification types with specific behaviors try it now create change order preview → https //api docs nue io/create change order preview common change order types updatequantity delta increase/decrease adds to current quantity (5 users + quantity 3 = 8 users total) updateterm delta extension adds months to current term (12 months + term 6 = 18 months total) upgrade/downgrade switch to different product tier renew extend subscription for new term period cancel end subscription on specific date // use subscription info from step 4 const assetnumber = localstorage getitem('assetnumber') || 'sub 00000279'; const changeorderdata = json stringify({ "options" { "previewinvoice" true, "calculatetax" false }, "assetchanges" \[ { "changetype" "updatequantity", "assetnumber" assetnumber, "quantity" 8, // increase from 5 to 8 users "startdate" "2025 02 01" } ] }); fetch("https //api nue io/change orders", { method 'post', headers myheaders, body changeorderdata }) then(response => response json()) then(result => { console log('change order preview created ', result); // save change order id const changeorderid = result data order id; localstorage setitem('changeorderid', changeorderid); // display change impact console log(`change order id ${changeorderid}`); console log(`new total $${result data order totalamount}`); // show pricing impact if (result data previewinvoices) { const invoice = result data previewinvoices\[0]; console log(`next invoice amount $${invoice amount}`); } }) catch(error => console log('error ', error)); what happens creates a draft change order showing the pricing impact of the modification without making actual changes step 6 generate quote link for approval create a shareable magic link for the change order to get customer approval or signatures this generates a secure url that customers can use to view their order details and download formatted quotes try it now generate draft order pdf link → https //api docs nue io/generate draft order pdf link // get change order id from step 5 const changeorderid = localstorage getitem('changeorderid'); fetch(`https //api nue io/orders/magiclink/order/${changeorderid}`, { method 'get', headers myheaders }) then(response => response json()) then(result => { console log('quote magic link generated ', result); const quotelink = result magiclink; console log(`share this link for approval ${quotelink}`); // store the quote link localstorage setitem('changeorderquotelink', quotelink); // in a real application, you might // email this link to the customer for review // display it in your ui for easy access // include it in approval workflows // share with stakeholders who need to review the quote }) catch(error => console log('error ', error)); advanced generate quote link with custom template // for custom branding, use a specific template const templateid = "custom branded template"; fetch(`https //api nue io/orders/magiclink/order/${changeorderid}/template/${templateid}`, { method 'get', headers myheaders }) then(response => response json()) then(result => { console log('branded quote link generated ', result magiclink); }); what happens generates a secure, shareable magic link that allows customers to view their order details and download professionally formatted quotes via a web interface step 7 activate the change order after receiving approval, activate the change order to implement the modifications try it now activate draft order → https //api docs nue io/activate draft order // get change order id from step 5 const changeorderid = localstorage getitem('changeorderid'); const changeactivationdata = json stringify({ "options" { "generateinvoice" true, "activateinvoice" true // activate invoice immediately for billing }, "ponumber" "po 2025 002 change", "podate" "2025 02 01" }); fetch(`https //api nue io/orders/${changeorderid}`, { method 'post', headers myheaders, body changeactivationdata }) then(response => response json()) then(result => { console log('change order activated ', result); console log(`change order status ${result data order status}`); console log(`updated subscriptions `, result data subscriptions); // the subscription quantity is now updated if (result data subscriptions) { result data subscriptions foreach(sub => { console log(`subscription ${sub name} ${sub quantity} units`); }); } }) catch(error => console log('error ', error)); what happens the subscription is modified with the new quantity, billing is updated, and changes sync to salesforce step 8 fetch updated orders finally, retrieve the customer's orders again to see all changes and confirm the updates try it now fetch customer orders → https //api docs nue io/fetch customer orders // get customer id and fetch all their orders const customerid = localstorage getitem('customerid'); const customerids = \[customerid]; const encodedids = encodeuricomponent(json stringify(customerids)); fetch(`https //api nue io/orders?customerids=${encodedids}\&includes=orderproducts`, { method 'get', headers myheaders }) then(response => response json()) then(result => { console log('updated customer order history ', result); // display all orders chronologically const orders = result data sort((a, b) => new date(a orderplaceddate) new date(b orderplaceddate) ); orders foreach((order, index) => { console log(`\\\n order ${index + 1} ${order ordernumber} `); console log(`type ${order name}`); console log(`status ${order status}`); console log(`date ${order orderplaceddate}`); console log(`total $${order totalamount}`); if (order orderproducts) { console log('products '); order orderproducts foreach(product => { console log(` ${product productname} ${product quantity} units`); }); } }); // calculate total customer value const totalvalue = orders reduce((sum, order) => sum + order totalamount, 0); console log(`\\\ntotal customer value $${totalvalue}`); }) catch(error => console log('error ', error)); what happens you can see the complete order history including both the original order and the change order, showing the customer's full journey salesforce synchronization throughout this entire workflow, several automatic synchronizations occur with salesforce customer creation and updates when the first order is activated, the customer record automatically syncs to salesforce the externalid field populates with the salesforce account id customer type typically upgrades from "prospect" to "direct customer" order and subscription management activated orders create corresponding records in salesforce subscriptions appear as ongoing service agreements change orders update existing subscription records all financial data (acv, tcv, billing periods) syncs automatically monitoring sync status you can check if orders have synced by looking for the externalid field // check if order has synced to salesforce if (order externalid) { console log(`order synced to salesforce ${order externalid}`); } else { console log('order pending salesforce sync'); } next steps now that you understand the basic order management workflow, you can explore advanced order workflows for complex scenarios like bulk operations and sophisticated bundles learn order data reference to understand all available fields and relationships implement custom business logic around your specific approval and billing processes set up webhooks for real time notifications of order status changes move on to advanced order workflows to learn about complex scenarios like multi product bundles, approval workflows, and enterprise integrations