Activate Draft Orders

this guide provides comprehensive instructions for activating draft orders using the nue lifecycle management api learn how to convert draft orders into active orders, configure invoice generation, and implement efficient order activation workflows prerequisites before you begin, ensure you have a valid nue api key with order activation permissions draft order ids that are ready for activation understanding of invoice generation and activation options basic knowledge of rest apis and json familiarity with order lifecycle management authentication all order activation 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 order activation activate draft order with invoice generation try it now https //api docs nue io/activate draft order const myheaders = new headers(); myheaders append("nue api key", "your api key here"); myheaders append("content type", "application/json"); // activate a draft order with invoice generation const draftorderid = "draft order 123e4567 e89b 12d3 a456 426614174000"; const activationdata = { options { generateinvoice true, // generate invoice during activation activateinvoice false // keep invoice as draft for manual review } }; fetch(`https //api nue io/orders/${draftorderid}`, { method 'post', headers myheaders, body json stringify(activationdata) }) then(response => response json()) then(result => { console log('order activated 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}`); // should be "active" console log(`activation date ${order activateddate}`); // display created assets if (result data assets && result data assets length > 0) { console log(`\n📦 assets created ${result data assets length}`); result data assets foreach(asset => { console log(` ${asset productname} ${asset quantity} units`); console log(` asset id ${asset id}`); console log(` status ${asset status}`); console log(` period ${asset startdate} to ${asset enddate}`); }); } // display invoice information if (result data invoices && result data invoices length > 0) { const invoice = result data invoices\[0]; console log(`\n💰 invoice generated `); console log(`invoice id ${invoice id}`); console log(`amount $${invoice amount}`); console log(`status ${invoice status}`); // should be "draft" console log(`due date ${invoice duedate}`); } } }) catch(error => console log('error ', error)); activate order with immediate invoice activation activate both the order and generated invoice in one operation const immediateactivation = { options { generateinvoice true, activateinvoice true // immediately activate the generated invoice }, // optional add purchase order details ponumber "po 2025 67890", podate "2025 01 15" }; fetch(`https //api nue io/orders/${draftorderid}`, { method 'post', headers myheaders, body json stringify(immediateactivation) }) then(response => response json()) then(result => { if (result status === 'success') { const order = result data order; const invoice = result data invoices\[0]; console log('✅ order and invoice activated successfully'); console log(`order status ${order status}`); console log(`invoice status ${invoice status}`); // should be "posted" console log(`invoice balance $${invoice balance}`); console log(`payment due ${invoice duedate}`); // ready for customer billing console log('\n🎯 order fully activated and ready for billing'); } }) catch(error => console log('activation failed ', error)); advanced activation patterns synchronous payment processing when activating orders through self service flows (e g , a checkout page), you can confirm payment synchronously before committing the order to the database set processpayment true to enable this mode how it works the order is computed entirely in memory — no database writes yet an invoice is generated and payment is charged via stripe if payment succeeds, the order, subscriptions, and invoice are all committed atomically if payment fails, behavior depends on cancelonpaymentfail cancelonpaymentfail true — full rollback nothing is written to the database the order stays in draft status and can be retried with a corrected payment method returns http 400 cancelonpaymentfail false — commit anyway the order is activated and subscriptions are created even though payment failed returns http 207 with a payment failure warning you can retry collection later important notes generateinvoice and activateinvoice must both be true when processpayment true for change orders that produce a negative invoice (e g , cancellations), payment is automatically skipped regardless of these flags — the credit memo is committed normally paymentmethodobject is optional when a default payment method is already on file for the stripe customer // synchronous payment — full rollback on failure const syncpaymentactivation = { options { processpayment true, // enable synchronous payment mode cancelonpaymentfail true, // roll back everything if payment fails generateinvoice true, // required with processpayment activateinvoice true // required with processpayment }, transactionhub { externalsystem "stripe", externalid "cus rss1mzkcy2pmj7", // stripe customer id transactiontype "customer" }, paymentmethodobject { externalpaymentmethodid "pm 1rcqthrqbulxakcmlnnv6b1r", name "visa ending 4242", paymentmethodtype "credit card", paymentsystem "stripe", autochargeenabled true } }; const response = await fetch(`https //api nue io/orders/${draftorderid}`, { method 'post', headers myheaders, body json stringify(syncpaymentactivation) }); // http 201 — payment confirmed, everything committed if (response status === 201) { const result = await response json(); const invoice = result data invoices\[0] invoice; console log('✅ order activated and payment confirmed'); console log(`invoice ${invoice id} | status ${invoice paymentstatus}`); // paid } // http 207 — activated but payment failed (cancelonpaymentfail false only) if (response status === 207) { const result = await response json(); console log('⚠️ order activated but payment failed ', result errorcode); // result data contains the activated order — retry payment separately } // http 400 — payment failed, full rollback (cancelonpaymentfail true) if (response status === 400) { const result = await response json(); console log('❌ payment failed, order rolled back ', result message); // order is still draft — safe to retry with updated payment method } setting custom fields and revenuecontractid during activation when activating a draft order, you can set custom fields or revenuecontractid on specific order products in the same request this is useful for scenarios where field values need to be populated before the activation event triggers downstream syncs (e g , rightrev revenue contract grouping via sqs) the order product updates are applied before activation commits, so synced systems receive the updated field values immediately const activationwithcustomfields = { options { generateinvoice true, activateinvoice true }, // set custom fields and revenuecontractid on specific order products orderproducts \[ { id "2b0c1858 0706 403e a6fb 412fd5d161a3", // order product id (from draft order) revenuecontractid "ord 001234", // groups revenue contracts in rightrev technicalcontactid c "003xx000004c0000" // salesforce custom field }, { id "3c1d2969 1817 514f b7gc 523ge6e272b4", revenuecontractid "ord 001234", custom field c "value1" } ] }; fetch(`https //api nue io/orders/${draftorderid}`, { method 'post', headers myheaders, body json stringify(activationwithcustomfields) }) then(response => response json()) then(result => { if (result status === 'success') { console log('✅ order activated with custom fields set on order products'); } }) catch(error => console log('error ', error)); supported fields in the orderproducts activation array field category example supported standard nue field revenuecontractid yes salesforce custom fields custom field c , technicalcontactid c yes system fields id , createddate , lastmodifieddate no — read only billing fields quantity , effectiveprice , listprice no — use existing apis important custom fields must already exist on the order product object in salesforce, be added to the fields exposed to nue field set, and have been synced to nue before use see docid\ jefyrxk1ml0k1noooukik for setup instructions order activation with payment method integration for orders using nue collections (payment links), you can specify or override payment methods during activation const nuecollectionsactivation = { options { generateinvoice true, activateinvoice true }, // transaction hub (required for payment integration) transactionhub { externalsystem "stripe", externalid "cus rss1mzkcy2pmj7", // stripe customer id transactiontype "customer" }, // payment method for nue collections (overrides draft order payment method) paymentmethodobject { externalpaymentmethodid "pm 1rcqthrqbulxakcmlnnv6b1r", name "updated payment method", paymentmethodtype "credit card", paymentsystem "stripe", autochargeenabled true } }; fetch(`https //api nue io/orders/${draftorderid}`, { method 'post', headers myheaders, body json stringify(nuecollectionsactivation) }) then(response => response json()) then(result => { if (result status === 'success') { console log('✅ order activated with nue collections payment method'); // the created subscriptions will have defaultpaymentmethodid set const subscriptions = result data subscriptions || \[]; subscriptions foreach(sub => { console log(`subscription ${sub name} payment method ${sub defaultpaymentmethodid}`); }); } }) catch(error => console log('nue collections activation failed ', error)); order activation with external system integration for stripe invoicing integration (transaction hub only) const externalsystemactivation = { options { generateinvoice true, activateinvoice true }, // purchase order information ponumber "po 2025 enterprise 001", podate "2025 01 10", // external system tracking (required for stripe invoicing) transactionhub { externalsystem "stripe", // external payment system externalid "cus rss1mzkcy2pmj7", // stripe customer id transactiontype "customer" // transaction type } }; fetch(`https //api nue io/orders/${draftorderid}`, { method 'post', headers myheaders, body json stringify(externalsystemactivation) }) then(response => response json()) then(result => { if (result status === 'success') { console log('✅ order activated with external system integration'); console log(`external system ${result data order transactionhub? externalsystem}`); console log(`external transaction id ${result data order transactionhub? externalid}`); // update external system with nue order details updateexternalsystem(result data order); } }) catch(error => console log('external integration activation failed ', error)); function updateexternalsystem(order) { // integrate with your external payment/erp system console log(`updating external system with order ${order ordernumber}`); // example update stripe subscription with nue order details const externalupdate = { nueorderid order id, nueordernumber order ordernumber, activationdate order activateddate, totalamount order grandtotal }; console log('external system update payload ', externalupdate); } bulk order activation service implement a service to activate multiple draft orders efficiently class orderactivationservice { constructor(apikey) { this apikey = apikey; this headers = new headers(); this headers append("nue api key", apikey); this headers append("content type", "application/json"); } async activateorder(draftorderid, activationoptions = {}) { try { // default activation configuration const defaultoptions = { generateinvoice true, activateinvoice false, // conservative default validatebeforeactivation true }; const options = { defaultoptions, activationoptions }; // step 1 validate order before activation (optional) if (options validatebeforeactivation) { await this validateorderforactivation(draftorderid); } // step 2 prepare activation payload const activationpayload = this prepareactivationpayload(options); // step 3 activate the order const result = await this submitactivation(draftorderid, activationpayload); // step 4 process activation result const processedresult = this processactivationresult(result); // step 5 handle post activation tasks await this handlepostactivation(processedresult); return { success true, order processedresult order, assets processedresult assets, invoices processedresult invoices, summary this generateactivationsummary(processedresult) }; } catch (error) { console error(`order activation failed for ${draftorderid} `, error); return { success false, error error message, draftorderid }; } } async validateorderforactivation(draftorderid) { // in a real implementation, you might fetch the draft order // and validate business rules before activation console log(`validating order ${draftorderid} for activation `); // example validations // check customer payment status // verify product availability // confirm pricing is current // validate subscription terms return true; } prepareactivationpayload(options) { const payload = { options { generateinvoice options generateinvoice, activateinvoice options activateinvoice } }; // add po information if provided if (options ponumber) { payload ponumber = options ponumber; } if (options podate) { payload podate = options podate; } // add external system integration if provided if (options transactionhub) { payload transactionhub = options transactionhub; } return payload; } async submitactivation(draftorderid, payload) { const response = await fetch(`https //api nue io/orders/${draftorderid}`, { method 'post', headers this headers, body json stringify(payload) }); if (!response ok) { const errortext = await response text(); throw new error(`activation failed ${response status} ${errortext}`); } const result = await response json(); if (result status !== 'success') { throw new error(`activation failed ${result message || 'unknown error'}`); } return result; } processactivationresult(apiresult) { return { order apiresult data order, assets apiresult data assets || \[], invoices apiresult data invoices || \[], entitlements apiresult data entitlements || \[] }; } async handlepostactivation(result) { const order = result order; // example post activation tasks // 1 send activation notifications await this sendactivationnotifications(order); // 2 update customer records await this updatecustomerrecords(order); // 3 provision services await this provisionservices(result assets); // 4 setup monitoring/tracking await this setupordertracking(order); } async sendactivationnotifications(order) { console log(`📧 sending activation notifications for order ${order ordernumber} `); // notify customer const customernotification = { to order customeremail, subject `order ${order ordernumber} activated`, template 'order activation', data { ordernumber order ordernumber, activationdate order activateddate, nextbillingdate order nextbillingdate } }; // notify internal teams const internalnotification = { to 'orders\@company com', subject `order activated ${order ordernumber}`, template 'internal order activation', data { ordernumber order ordernumber, customername order customername, totalvalue order grandtotal } }; console log('✅ activation notifications queued'); } async updatecustomerrecords(order) { console log(`📝 updating customer records for ${order customername} `); // update customer lifecycle stage // update account values // record activation event console log('✅ customer records updated'); } async provisionservices(assets) { console log(`🚀 provisioning services for ${assets length} assets `); for (const asset of assets) { // provision each service/product console log(` provisioning ${asset productname} (${asset quantity} units)`); // integration points // create user accounts // setup service configurations // deploy infrastructure // configure access controls } console log('✅ service provisioning completed'); } async setupordertracking(order) { console log(`📊 setting up tracking for order ${order ordernumber} `); // setup monitoring and analytics const trackingdata = { orderid order id, ordernumber order ordernumber, activationdate order activateddate, customersegment order customersegment, ordervalue order grandtotal, subscriptionenddate order subscriptionenddate }; console log('✅ order tracking configured'); } generateactivationsummary(result) { const order = result order; const assets = result assets; const invoices = result invoices; return { orderid order id, ordernumber order ordernumber, customername order customername, activationdate order activateddate, status order status, totalassets assets length, activeassets assets filter(a => a status === 'active') length, totalinvoices invoices length, postedinvoices invoices filter(i => i status === 'posted') length, totalvalue order grandtotal, nextbillingdate order nextbillingdate }; } async activatemultipleorders(draftorderids, globaloptions = {}) { const results = \[]; const batchsize = 5; // process in batches to avoid rate limits console log(`🔄 activating ${draftorderids length} orders in batches of ${batchsize} `); for (let i = 0; i < draftorderids length; i += batchsize) { const batch = draftorderids slice(i, i + batchsize); console log(`processing batch ${math floor(i/batchsize) + 1} `); const batchpromises = batch map(orderid => this activateorder(orderid, globaloptions) ); const batchresults = await promise allsettled(batchpromises); results push( batchresults); // brief pause between batches if (i + batchsize < draftorderids length) { await new promise(resolve => settimeout(resolve, 1000)); } } // analyze results const successful = results filter(r => r status === 'fulfilled' && r value success); const failed = results filter(r => r status === 'rejected' || !r value success); console log(`\n📊 bulk activation results `); console log(`✅ successful ${successful length}`); console log(`❌ failed ${failed length}`); if (failed length > 0) { console log('\n❌ failed activations '); failed foreach(result => { const error = result status === 'rejected' ? result reason result value error; console log(` order ${result value? draftorderid || 'unknown'} ${error}`); }); } return { total draftorderids length, successful successful length, failed failed length, results results }; } } // usage examples const activationservice = new orderactivationservice("your api key here"); // single order activation const singleactivation = await activationservice activateorder( "draft order 123", { generateinvoice true, activateinvoice true, ponumber "po 2025 001", transactionhub { externalsystem "salesforce", externalid "006xx000004c0000", transactiontype "opportunity" } } ); if (singleactivation success) { console log(`✅ order ${singleactivation summary ordernumber} activated successfully`); console log(`assets created ${singleactivation summary totalassets}`); console log(`total value $${singleactivation summary totalvalue}`); } else { console error(`❌ activation failed ${singleactivation error}`); } // bulk order activation const bulkorderids = \[ "draft order 123", "draft order 456", "draft order 789" ]; const bulkresult = await activationservice activatemultipleorders( bulkorderids, { generateinvoice true, activateinvoice false, // keep invoices as draft for review validatebeforeactivation true } ); console log(`bulk activation completed ${bulkresult successful}/${bulkresult total} orders activated`); order activation workflows approval based activation implement approval workflows for high value orders class approvalbasedactivationservice extends orderactivationservice { async activateorderwithapproval(draftorderid, options = {}) { try { // step 1 check if order requires approval const requiresapproval = await this checkapprovalrequirement(draftorderid); if (requiresapproval) { // step 2 submit for approval const approvalresult = await this submitforapproval(draftorderid); if (!approvalresult approved) { return { success false, requiresapproval true, approvalid approvalresult approvalid, message 'order submitted for approval' }; } } // step 3 proceed with activation return await this activateorder(draftorderid, options); } catch (error) { return { success false, error error message, draftorderid }; } } async checkapprovalrequirement(draftorderid) { // business logic to determine if approval is needed // examples // order value > $10,000 // custom pricing applied // non standard terms // new customer console log(`checking approval requirements for order ${draftorderid} `); // mock approval check const ordervalue = 15000; // would fetch actual order value return ordervalue > 10000; } async submitforapproval(draftorderid) { console log(`submitting order ${draftorderid} for approval `); // integration with approval system const approvalrequest = { orderid draftorderid, approvaltype 'order activation', submittedby 'api user', submitteddate new date() toisostring(), urgency 'normal' }; // mock approval submission return { approved false, // would be determined by approval system approvalid `approval ${date now()}`, estimatedapprovaltime '2 4 hours' }; } } request body schema required fields field type description example options object activation configuration options see options schema below options generateinvoice boolean whether to generate invoice during activation true options activateinvoice boolean whether to activate the generated invoice false optional fields field type description example options processpayment boolean enable synchronous payment confirmation before committing order data true options cancelonpaymentfail boolean when processpayment true — if true , roll back everything on payment failure (http 400); if false , commit the order anyway and return http 207 with a warning requires processpayment true true ponumber string purchase order number "po 2025 67890" podate string purchase order date (yyyy mm dd) "2025 01 15" transactionhub object external system integration see transaction hub schema paymentmethodobject object payment method for nue collections optional when processpayment true if stripe customer has a default pm on file see payment method schema orderproducts array order products to update with custom fields or revenuecontractid before activation each entry requires an id (order product uuid from the draft order) plus the fields to set see supported fields table above payment method override behavior payment method provided during activation will override the payment method from draft order creation product level and add on level payment methods from draft creation are still respected if no payment method is provided during activation, the draft order payment methods are used transaction hub schema field type description example externalsystem string external system identifier "stripe" , "salesforce" externalid string external transaction/record id "cus rss1mzkcy2pmj7" transactiontype string type of external transaction "customer" , "opportunity" payment method object schema field type required description valid values externalpaymentmethodid string yes external payment method id (e g , stripe pm id) any string name string yes display name for the payment method any string paymentmethodtype string yes type of payment method "electronic" , "nonelectronic" , "ach" , "bank transfer" , "cash" , "check" , "credit card" , "debit card" , "paypal" , "wire transfer" , "other" paymentsystem string yes payment system identifier (e g , "stripe") any string autochargeenabled boolean yes whether automatic charging is enabled true or false id string yes existing nue payment method id uuid format required when creating a new payment method from external system required when referencing an existing nue payment method response structure http status codes http status when description 201 created standard activation or processpayment true with successful payment order activated, invoice generated 207 multi status processpayment true , payment failed, cancelonpaymentfail false order activated despite payment failure check errorcode for payment details 400 bad request validation error, or processpayment true + payment failed + cancelonpaymentfail true nothing committed order stays draft and can be retried success response (201 created) { "status" "success", "data" { "order" { "id" "order uuid", "ordernumber" "ord 000001", "status" "active", "activateddate" "2025 01 15t10 30 00z", "customername" "customer name", "grandtotal" 9720 00, "nextbillingdate" "2025 02 15" }, "assets" \[ { "id" "asset uuid", "productname" "enterprise license", "status" "active", "quantity" 100, "startdate" "2025 01 15", "enddate" "2026 01 14" } ], "invoices" \[ { "invoice" { "id" "invoice uuid", "amount" 9720 00, "balance" 0, "status" "active", "paymentstatus" "paid", "duedate" "2025 02 14" } } ], "entitlements" \[] } } payment failure response (207 multi status) returned when processpayment true , cancelonpaymentfail false , and payment fails the order and subscriptions are committed; payment must be retried separately { "status" "partial success", "errortype" "payment processing failed", "errorcode" "payment failed", "message" "payment processing failed ", "data" { "order" { "status" "active" }, "subscriptions" \[ ], "invoices" \[{ "invoice" { "paymentstatus" null } }] } } \## error handling \### common activation errors \| error | description | resolution | \| | | | \| `invalid draft order` | order not found or not in draft status | verify order id and status | \| `invoice generation failed` | invoice creation failed | check billing configuration | \| `asset provisioning failed` | asset creation failed | review product configuration | \| `activation validation failed` | pre activation validation failed | address validation issues | \| `sync payment requires invoice generation` | `processpayment true` but `generateinvoice` or `activateinvoice` is `false` | set both `generateinvoice true` and `activateinvoice true` | \| `cancel on payment fail requires sync payment` | `cancelonpaymentfail true` without `processpayment true` | only use `cancelonpaymentfail` when `processpayment true` | \| `payment failed` | stripe payment was declined or failed | check payment method validity and retry | \| `invalid order product id` | an order product id in the `orderproducts` array does not belong to this order | verify the order product ids from the draft order | \| `invalid order product field` | a field in the `orderproducts` array cannot be updated via the activation payload (e g , billing fields like `quantity`) | use billing specific apis for those fields instead | \### robust error handling ```javascript async function safeorderactivation(draftorderid, options) { try { const result = await activationservice activateorder(draftorderid, options); if (result success) { console log('✅ order activated successfully'); return result; } else { console error('❌ activation failed ', result error); // handle specific error scenarios if (result error includes('invalid draft order')) { console log('💡 check that order exists and is in draft status'); } else if (result error includes('invoice generation failed')) { console log('💡 review customer billing configuration'); } return result; } } catch (error) { console error('unexpected activation error ', error); return { success false, error error message, draftorderid }; } } best practices activation strategy validate before activation to prevent failures use conservative invoice settings (generate but don't activate) for manual review implement approval workflows for high value orders track activation events for audit and analytics post activation tasks send customer notifications about service activation provision services immediately after activation update external systems with activation details monitor asset status and usage error recovery implement retry logic for transient failures provide clear error messages to users log activation attempts for troubleshooting have rollback procedures for failed activations this comprehensive guide enables you to efficiently activate draft orders using the nue lifecycle management api, supporting everything from simple activations to complex approval based workflows with external system integrations