Create Draft Orders

this guide provides comprehensive instructions for creating draft orders using the nue lifecycle management api learn how to create simple orders, configure complex bundles with add ons, and implement efficient order management workflows prerequisites before you begin, ensure you have a valid nue api key with order creation permissions valid customer ids for order creation price book entry ids for products you want to order basic knowledge of rest apis and json understanding of subscription and pricing concepts authentication all order creation 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"); basic draft order creation create simple draft order 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 simple draft order const orderdata = { customer { id "d2e04653 ae90 49df a986 134cf64f6d03" }, effectivedate "2025 01 01", orderproducts \[ { pricebookentryid "pbe 123e4567 e89b 12d3 a456 426614174000", quantity 1, subscriptionstartdate "2025 01 01", subscriptionterm 12 // 12 months } ] }; fetch('https //api nue io/orders', { method 'post', headers myheaders, body json stringify(orderdata) }) then(response => response json()) then(result => { console log('draft order created successfully ', result); if (result status === 'success') { const order = result data order; console log(`order id ${order id}`); console log(`order number ${order ordernumber}`); console log(`status ${order status}`); console log(`list total $${order listtotal}`); console log(`discount $${order discountamount}`); // display invoice preview if (result data invoices && result data invoices length > 0) { const invoice = result data invoices\[0]; console log(`\ninvoice preview `); console log(`amount $${invoice amount}`); console log(`due date ${invoice duedate}`); } } }) catch(error => console log('error ', error)); create draft order with complete configuration create a draft order with comprehensive configuration including billing details const comprehensiveorder = { // customer information customer { id "d2e04653 ae90 49df a986 134cf64f6d03" }, // order details effectivedate "2025 01 01", name "q1 2025 software license order", description "annual software license renewal with additional users", orderreferencenumber "ord 2025 001", ordertype "new", // purchase order information ponumber "po 2025 12345", podate "2024 12 20", // billing configuration billtocontact { id "123e4567 e89b 12d3 a456 426614174000" }, shiptocontact "456e7890 e89b 12d3 a456 426614174000", paymentmethod "credit card", // products being ordered orderproducts \[ { pricebookentryid "pbe software license standard", quantity 50, subscriptionstartdate "2025 01 01", subscriptionterm 12, // apply pricing tags pricetagcodes \["enterprise2025"] }, { pricebookentryid "pbe professional services", quantity 40, subscriptionstartdate "2025 01 15", subscriptionterm 6 } ], // options for order processing options { previewinvoice true, calculatetax true } }; fetch('https //api nue io/orders', { method 'post', headers myheaders, body json stringify(comprehensiveorder) }) then(response => response json()) then(result => { console log('comprehensive draft order created ', result); const order = result data order; console log(`\n✅ draft order created successfully`); console log(`order id ${order id}`); console log(`order number ${order ordernumber}`); console log(`customer ${order customername}`); console log(`effective date ${order orderstartdate}`); console log(`total products ${order orderproducts? length || 0}`); console log(`list total $${order listtotal}`); console log(`net total $${order nettotal}`); // display assets preview if (result data assets && result data assets length > 0) { console log(`\n📦 assets to be created ${result data assets length}`); result data assets foreach(asset => { console log(` ${asset productname} ${asset quantity} units`); console log(` duration ${asset startdate} to ${asset enddate}`); }); } }) catch(error => console log('error ', error)); advanced bundle configuration create order with bundle products configure complex bundle products with multiple add ons const bundleorder = { customer { id "d2e04653 ae90 49df a986 134cf64f6d03" }, effectivedate "2025 01 01", name "enterprise software bundle order", orderproducts \[ { // main bundle product pricebookentryid "pbe enterprise bundle base", quantity 1, subscriptionstartdate "2025 01 01", subscriptionterm 12, // configure bundle add ons (level 1) addons \[ { productoptionid "opt additional users", productoptionquantity 25, // 25 additional user licenses subscriptionstartdate "2025 01 01", subscriptionterm 12, pricetagids \["volume discount users"] }, { productoptionid "opt premium support", // no quantity needed for fixed add ons subscriptionstartdate "2025 01 01", subscriptionterm 12 }, { productoptionid "opt integration pack", subscriptionstartdate "2025 02 01", // later start date subscriptionterm 10, // co terminate with main bundle // level 2 add ons within integration pack addons \[ { productoptionid "opt salesforce connector", subscriptionstartdate "2025 02 01", subscriptionterm 10 }, { productoptionid "opt custom apis", productoptionquantity 5, // 5 custom api endpoints subscriptionstartdate "2025 03 01", subscriptionterm 9 } ] } ] } ], options { previewinvoice true, calculatetax true } }; fetch('https //api nue io/orders', { method 'post', headers myheaders, body json stringify(bundleorder) }) then(response => response json()) then(result => { if (result status === 'success') { const order = result data order; console log(`\n🎯 bundle order created successfully`); console log(`order id ${order id}`); console log(`bundle components ${order orderproducts? length || 0} main products`); // display bundle breakdown if (result data assets) { console log(`\n📦 bundle components (${result data assets length} assets) `); result data assets foreach(asset => { console log(` ${asset productname}`); console log(` quantity ${asset quantity}`); console log(` period ${asset startdate} to ${asset enddate}`); console log(` status ${asset status}`); }); } // display pricing breakdown console log(`\n💰 pricing breakdown `); console log(`list total $${order listtotal}`); console log(`discount $${order discountamount}`); console log(`net total $${order nettotal}`); console log(`tax $${order taxamount || 0}`); console log(`grand total $${order grandtotal}`); } }) catch(error => { if (error message includes('invalid addon hierarchy')) { console error('bundle configuration error invalid add on hierarchy'); } else if (error message includes('missing addon quantity')) { console error('bundle configuration error missing required add on quantity'); } else { console error('order creation failed ', error); } }); co termination with existing assets create orders that co terminate with existing customer assets const cotermorder = { customer { id "d2e04653 ae90 49df a986 134cf64f6d03" }, effectivedate "2025 01 01", name "mid term license addition", description "adding licenses to co terminate with existing subscription", orderproducts \[ { pricebookentryid "pbe additional licenses", quantity 10, subscriptionstartdate "2025 01 01", // co terminate with existing asset instead of fixed term cotermasset "asset 123e4567 e89b 12d3 a456 426614174000", pricetagcodes \["prorated2025"] } ], options { previewinvoice true, calculatetax true } }; fetch('https //api nue io/orders', { method 'post', headers myheaders, body json stringify(cotermorder) }) then(response => response json()) then(result => { if (result status === 'success') { console log(`✅ co termination order created`); const assets = result data assets; if (assets && assets length > 0) { const asset = assets\[0]; console log(`new asset end date ${asset enddate}`); console log(`co terminated with ${asset cotermasset}`); console log(`prorated amount $${asset proratedamount || 'n/a'}`); } } }) catch(error => console log('co termination order failed ', error)); order management workflows draft order creation service implement a comprehensive order creation service with validation class draftorderservice { constructor(apikey) { this apikey = apikey; this headers = new headers(); this headers append("nue api key", apikey); this headers append("content type", "application/json"); } async createdraftorder(orderinput) { try { // step 1 validate order data const validatedorder = this validateorderdata(orderinput); // step 2 enrich with business defaults const enrichedorder = this enrichorderdata(validatedorder); // step 3 create draft order const draftorder = await this submitdraftorder(enrichedorder); // step 4 process creation result const processedresult = this processdraftorderresult(draftorder); return { success true, order processedresult order, assets processedresult assets, invoices processedresult invoices, warnings processedresult warnings, summary this generateordersummary(processedresult) }; } catch (error) { console error('draft order creation failed ', error); return { success false, error error message, orderinput }; } } validateorderdata(orderinput) { const errors = \[]; // required field validation if (!orderinput customer? id) { errors push('customer id is required'); } if (!orderinput effectivedate) { errors push('effective date is required'); } if (!orderinput orderproducts || orderinput orderproducts length === 0) { errors push('at least one order product is required'); } // product validation orderinput orderproducts? foreach((product, index) => { if (!product pricebookentryid) { errors push(`product ${index + 1} price book entry id is required`); } if (!product quantity || product quantity <= 0) { errors push(`product ${index + 1} quantity must be greater than 0`); } if (!product subscriptionstartdate) { errors push(`product ${index + 1} subscription start date is required`); } if (!product subscriptionterm && !product cotermasset) { errors push(`product ${index + 1} either subscription term or co term asset is required`); } // validate bundle add ons if (product addons) { this validateaddons(product addons, `product ${index + 1}`, errors); } }); // date validation if (orderinput effectivedate) { const effectivedate = new date(orderinput effectivedate); const today = new date(); if (effectivedate < today sethours(0, 0, 0, 0)) { errors push('effective date cannot be in the past'); } } if (errors length > 0) { throw new error(`validation failed \n${errors join('\n')}`); } return orderinput; } validateaddons(addons, parentpath, errors) { addons foreach((addon, index) => { const addonpath = `${parentpath} add on ${index + 1}`; if (!addon productoptionid) { errors push(`${addonpath} product option id is required`); } // if it's a quantity based add on, quantity is required if (addon productoptionquantity !== undefined && addon productoptionquantity <= 0) { errors push(`${addonpath} quantity must be greater than 0`); } // validate nested add ons (up to 3 levels deep) if (addon addons && addon addons length > 0) { this validateaddons(addon addons, addonpath, errors); } }); } enrichorderdata(orderinput) { const enriched = { orderinput, // set default options if not provided options { previewinvoice true, calculatetax false, orderinput options }, // generate order name if not provided name orderinput name || `order for ${orderinput customer id}`, // set order type default ordertype orderinput ordertype || "new" }; // enrich product data enriched orderproducts = orderinput orderproducts map(product => ({ product, // ensure subscription start date is not before effective date subscriptionstartdate this adjuststartdate( product subscriptionstartdate, orderinput effectivedate ) })); return enriched; } adjuststartdate(startdate, effectivedate) { const start = new date(startdate); const effective = new date(effectivedate); // if start date is before effective date, use effective date return start < effective ? effectivedate startdate; } async submitdraftorder(orderdata) { const response = await fetch('https //api nue io/orders', { method 'post', headers this headers, body json stringify(orderdata) }); if (!response ok) { const errortext = await response text(); throw new error(`api error ${response status} ${errortext}`); } const result = await response json(); if (result status !== 'success') { throw new error(`order creation failed ${result message || 'unknown error'}`); } return result; } processdraftorderresult(apiresult) { return { order apiresult data order, assets apiresult data assets || \[], invoices apiresult data invoices || \[], entitlements apiresult data entitlements || \[], warnings apiresult warnings || \[] }; } generateordersummary(result) { const order = result order; const assets = result assets; const invoices = result invoices; return { orderid order id, ordernumber order ordernumber, customername order customername, totalproducts order orderproducts? length || 0, totalassets assets length, totalinvoices invoices length, listtotal order listtotal, nettotal order nettotal, grandtotal order grandtotal, status order status, effectivedate order orderstartdate, haswarnings result warnings length > 0 }; } } // usage example const orderservice = new draftorderservice("your api key here"); const neworder = { customer { id "d2e04653 ae90 49df a986 134cf64f6d03" }, effectivedate "2025 02 01", name "q1 2025 license expansion", orderproducts \[ { pricebookentryid "pbe enterprise license", quantity 100, subscriptionstartdate "2025 02 01", subscriptionterm 12, addons \[ { productoptionid "opt premium support", subscriptionstartdate "2025 02 01", subscriptionterm 12 } ] } ], options { previewinvoice true, calculatetax true } }; orderservice createdraftorder(neworder) then(result => { if (result success) { console log('\n🎉 draft order created successfully!'); console log(`order number ${result summary ordernumber}`); console log(`total assets ${result summary totalassets}`); console log(`grand total $${result summary grandtotal}`); if (result summary haswarnings) { console log('\n⚠️ warnings '); result warnings foreach(warning => { console log(` ${warning message}`); }); } } else { console error('❌ order creation failed ', result error); } }); request body schema required fields field type description example customer id string customer identifier (uuid) "d2e04653 ae90 49df a986 134cf64f6d03" effectivedate string order effective date (iso 8601) "2025 01 01" orderproducts array list of products to order see product schema below order product schema field type required description pricebookentryid string yes price book entry identifier quantity number yes product quantity (must be > 0) subscriptionstartdate string yes subscription start date (iso 8601) subscriptionterm number subscription term in months cotermasset string asset id to co terminate with addons array no bundle add on configurations pricetagids array no price tag identifiers for discounts pricetagcodes array no price tag codes for discounts either subscriptionterm or cotermasset is required bundle add on schema field type required description productoptionid string yes product option identifier productoptionquantity number quantity (required for editable options) subscriptionstartdate string no override start date subscriptionterm number no override subscription term addons array no nested add ons (up to 3 levels) response structure success response (201 created) { "status" "success", "data" { "order" { "id" "order uuid", "ordernumber" "ord 000001", "customerid" "customer uuid", "customername" "customer name", "status" "draft", "orderstartdate" "2025 01 01", "listtotal" 10000 00, "discountamount" 1000 00, "nettotal" 9000 00, "taxamount" 720 00, "grandtotal" 9720 00 }, "assets" \[ { "id" "asset uuid", "productid" "product uuid", "productname" "product name", "quantity" 1, "startdate" "2025 01 01", "enddate" "2025 12 31", "status" "pendingactivation" } ], "invoices" \[ { "id" "invoice uuid", "amount" 9720 00, "balance" 9720 00, "status" "draft", "duedate" "2025 01 31" } ] }, "warnings" \[] } error handling common error scenarios error code description resolution invalid addon hierarchy invalid add on configuration check product option availability missing addon quantity required add on quantity missing provide quantity for editable options invalid addon start date add on start date invalid ensure start date is before parent end date subscription term not allowed invalid subscription term check if term is allowed for product bundle configuration errors // handle bundle specific errors try { const result = await orderservice createdraftorder(bundleorder); } catch (error) { if (error message includes('invalid addon hierarchy')) { console error('bundle error product option not available at this level'); // guide user to correct bundle configuration } else if (error message includes('insufficient feature options')) { console error('bundle error minimum required options not met'); // show minimum requirements for product group } else if (error message includes('excessive feature options')) { console error('bundle error too many options selected'); // show maximum allowed options for product group } } best practices order design validate bundle configurations before submission use co termination for mid term additions apply appropriate pricing tags for discounts set realistic start dates considering processing time performance batch product lines efficiently in single orders use preview invoices to validate pricing implement proper error handling for validation failures cache price book entries to reduce api calls business logic validate customer eligibility before order creation check product availability and prerequisites implement approval workflows for high value orders generate order references for tracking this comprehensive guide enables you to efficiently create and manage draft orders using the nue lifecycle management api, supporting everything from simple product orders to complex bundle configurations with multiple add on levels