Getting Started with Subscription Management

this guide walks you through essential subscription management operations in the nue self service api you'll learn how to retrieve subscription data, understand different view types, update subscription settings, and implement client side pricing for dynamic subscription changes prerequisites before you begin, ensure you have a valid nue api key customer accounts with active subscriptions basic understanding of rest apis and json familiarity with subscription lifecycle concepts authentication all subscription 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"); understanding subscription views the nue api provides two primary ways to view subscription data, each optimized for different use cases current contract view shows the complete subscription with all changes (past, present, and future) in a single timeline view best for customer service dashboards complete subscription management planning future modifications understanding full contract terms snapshot view shows exactly what the subscription looked like at a specific point in time best for historical billing analysis audit and compliance reporting change impact analysis point in time financial reporting retrieving customer subscriptions fetch all subscriptions for customers try it now fetch customer subscriptions → https //api docs nue io/fetch customer subscriptions const myheaders = new headers(); myheaders append("nue api key", "your api key here"); myheaders append("content type", "application/json"); // fetch subscriptions for multiple customers const customerids = \[ "d2e04653 ae90 49df a986 134cf64f6d03", "cc5e1f0f 5e14 48cc ab98 9e5b191aa46f" ]; const encodedcustomerids = encodeuricomponent(json stringify(customerids)); fetch(`https //api nue io/subscriptions?customerids=${encodedcustomerids}`, { method 'get', headers myheaders }) then(response => response json()) then(result => { console log('customer subscriptions retrieved ', result); if (result status === 'success' && result data) { result data foreach(subscription => { console log(`\nsubscription ${subscription name}`); console log(`customer ${subscription customerid}`); console log(`status ${subscription status}`); console log(`product ${subscription productid}`); console log(`quantity ${subscription quantity}`); console log(`start date ${subscription subscriptionstartdate}`); console log(`end date ${subscription subscriptionenddate}`); console log(`total amount $${subscription totalamount || 'n/a'}`); }); } }) catch(error => console log('error ', error)); fetch subscriptions with related data include additional information using the includes parameter // include product and pricing tag information const includes = "product,pricetags"; const url = `https //api nue io/subscriptions?customerids=${encodedcustomerids}\&includes=${includes}`; fetch(url, { method 'get', headers myheaders }) then(response => response json()) then(result => { console log('subscriptions with related data ', result); if (result status === 'success' && result data) { result data foreach(subscription => { console log(`\nsubscription ${subscription name}`); // access product information if (subscription product) { console log(`product details `); console log(` name ${subscription product name}`); console log(` sku ${subscription product sku}`); console log(` description ${subscription product description}`); } // access pricing tag information if (subscription pricetags && subscription pricetags length > 0) { console log(`applied price tags `); subscription pricetags foreach(tag => { console log(` ${tag name} (${tag code})`); }); } }); } }) catch(error => console log('error ', error)); filter subscriptions by status retrieve only subscriptions in specific states // get only active subscriptions const activeurl = `https //api nue io/subscriptions?customerids=${encodedcustomerids}\&status=active`; fetch(activeurl, { method 'get', headers myheaders }) then(response => response json()) then(result => { if (result status === 'success' && result data) { console log(`found ${result data length} active subscriptions`); result data foreach(subscription => { console log(`active ${subscription name} $${subscription totalamount || 0}`); }); } }) catch(error => console log('error ', error)); // available status filters active, expired, canceled retrieving specific subscriptions fetch by subscription name try it now fetch customer subscriptions → https //api docs nue io/fetch customer subscriptions // fetch a specific subscription by name const subscriptionname = "sub 00000279"; fetch(`https //api nue io/subscriptions?name=${subscriptionname}`, { method 'get', headers myheaders }) then(response => response json()) then(result => { if (result status === 'success' && result data && result data length > 0) { const subscription = result data\[0]; console log('subscription details ', subscription); console log(`name ${subscription name}`); console log(`product ${subscription productid}`); console log(`customer ${subscription customerid}`); console log(`term ${subscription subscriptionterm} months`); console log(`auto renew ${subscription autorenew}`); console log(`current period ${subscription subscriptionstartdate} to ${subscription subscriptionenddate}`); // display financial information console log(`\nfinancial summary `); console log(` total amount $${subscription totalamount || 0}`); console log(` total acv $${subscription totalacv || 0}`); console log(` total tcv $${subscription tcv || 0}`); } else { console log('subscription not found'); } }) catch(error => console log('error ', error)); include subscription history for detailed change tracking, include the subscription's modification history const subscriptionname = "sub 00000279"; fetch(`https //api nue io/subscriptions?name=${subscriptionname}\&history=true`, { method 'get', headers myheaders }) then(response => response json()) then(result => { if (result status === 'success' && result data && result data length > 0) { const subscription = result data\[0]; console log('subscription with history ', subscription); // access historical changes if (subscription subscriptionhistory) { console log('\nsubscription change history '); subscription subscriptionhistory foreach((change, index) => { console log(`${index + 1} ${change changedate} ${change changetype}`); console log(` quantity ${change oldquantity} → ${change newquantity}`); console log(` amount $${change oldamount} → $${change newamount}`); }); } } }) catch(error => console log('error ', error)); creating subscription snapshots point in time subscription analysis generate snapshots to see exactly what subscriptions looked like on specific dates // create a snapshot for a specific date const snapshotdate = "2025 01 15"; // yyyy mm dd format fetch(`https //api nue io/subscriptions?customerids=${encodedcustomerids}\&snapshotdate=${snapshotdate}`, { method 'get', headers myheaders }) then(response => response json()) then(result => { console log(`subscription snapshot for ${snapshotdate} `, result); if (result status === 'success' && result data) { result data foreach(subscription => { console log(`\nsnapshot ${subscription name}`); console log(`status on ${snapshotdate} ${subscription status}`); console log(`quantity on ${snapshotdate} ${subscription quantity}`); console log(`total amount on ${snapshotdate} $${subscription totalamount || 'n/a'}`); // upcoming changes from that date if (subscription upcomingchanges) { console log('upcoming changes from this date '); subscription upcomingchanges foreach(change => { console log(` ${change startdate} ${change changetype} ${change description}`); }); } }); } }) catch(error => console log('error ', error)); updating subscription settings update auto renewal settings try it now update subscription → https //api docs nue io/update subscription // update a subscription's auto renewal setting const subscriptionid = "7c8a3e45 1d2f 4a5b 9c7e 3f4a5b6c7d8e"; const updatedata = json stringify({ "autorenew" true }); fetch(`https //api nue io/subscriptions/${subscriptionid}`, { method 'patch', headers myheaders, body updatedata }) then(response => response json()) then(result => { console log('subscription updated ', result); if (result status === 'success') { console log('auto renewal successfully enabled'); console log('updated subscription ', result data); } }) catch(error => console log('error ', error)); update custom fields modify custom subscription attributes // update custom fields const subscriptionid = "7c8a3e45 1d2f 4a5b 9c7e 3f4a5b6c7d8e"; const customfieldupdate = json stringify({ "ruby custom field c" "updated value", "servicetier c" "premium", "accountmanager c" "john smith" }); fetch(`https //api nue io/subscriptions/${subscriptionid}`, { method 'patch', headers myheaders, body customfieldupdate }) then(response => response json()) then(result => { console log('custom fields updated ', result); if (result status === 'success') { console log('custom fields successfully updated'); } }) catch(error => console log('error ', error)); client side pricing engine integration retrieve pricing data for dynamic quotes try it now fetch pricing data → https //api docs nue io/fetch pricing data for subscriptions for client side pricing engine // get pricing data for client side calculations const customerids = \["d2e04653 ae90 49df a986 134cf64f6d03"]; const encodedids = encodeuricomponent(json stringify(customerids)); fetch(`https //api nue io/subscriptions/pricing engine input?customerids=${encodedids}`, { method 'get', headers myheaders }) then(response => response json()) then(result => { console log('pricing engine data ', result); if (result status === 'success' && result data) { // this data can be used with nue ui components for real time pricing const pricingdata = result data; // example display available subscriptions for modification object keys(pricingdata) foreach(customerid => { const customerdata = pricingdata\[customerid]; if (customerdata changes) { console log(`pricing data for customer ${customerid} `); customerdata changes foreach(change => { console log(` change type ${change changetype}`); console log(` quantity ${change quantity}`); console log(` total price $${change totalprice}`); }); } }); } }) catch(error => console log('error ', error)); building a subscription dashboard here's a comprehensive example of building a customer subscription dashboard async function buildsubscriptiondashboard(customerid) { const myheaders = new headers(); myheaders append("nue api key", "your api key here"); myheaders append("content type", "application/json"); try { // fetch all customer subscriptions with product details const customerids = \[customerid]; const encodedids = encodeuricomponent(json stringify(customerids)); const response = await fetch( `https //api nue io/subscriptions?customerids=${encodedids}\&includes=product,pricetags`, { method 'get', headers myheaders } ); const result = await response json(); if (result status !== 'success' || !result data) { throw new error('failed to fetch subscriptions'); } const subscriptions = result data; // organize subscriptions by status const dashboard = { active \[], expired \[], canceled \[], summary { totalsubscriptions subscriptions length, totalmonthlyvalue 0, totalannualvalue 0, nextrenewal null } }; subscriptions foreach(subscription => { const subdata = { id subscription id, name subscription name, productid subscription productid, quantity subscription quantity, status subscription status, startdate subscription subscriptionstartdate, enddate subscription subscriptionenddate, totalamount subscription totalamount || 0, totalacv subscription totalacv || 0, autorenew subscription autorenew, pricetags subscription pricetags || \[] }; // categorize by status if (subscription status === 'active') { dashboard active push(subdata); dashboard summary totalannualvalue += subdata totalacv; // track next renewal const enddate = new date(subscription subscriptionenddate); if (!dashboard summary nextrenewal || enddate < new date(dashboard summary nextrenewal)) { dashboard summary nextrenewal = subscription subscriptionenddate; } } else if (subscription status === 'expired') { dashboard expired push(subdata); } else if (subscription status === 'canceled') { dashboard canceled push(subdata); } }); // display dashboard console log('\n🏢 customer subscription dashboard'); console log('====================================='); console log(`\n📊 summary `); console log(` total subscriptions ${dashboard summary totalsubscriptions}`); console log(` annual contract value $${dashboard summary totalannualvalue tofixed(2)}`); console log(` next renewal ${dashboard summary nextrenewal || 'none scheduled'}`); console log(`\n✅ active subscriptions (${dashboard active length}) `); dashboard active foreach(sub => { console log(` 📋 ${sub name}`); console log(` product ${sub productid}`); console log(` quantity ${sub quantity}`); console log(` value $${sub totalamount}`); console log(` ends ${sub enddate}`); console log(` auto renew ${sub autorenew ? '✅' '❌'}`); if (sub pricetags length > 0) { console log(` applied discounts ${sub pricetags map(t => t name) join(', ')}`); } console log(''); }); if (dashboard expired length > 0) { console log(`\n⏰ expired subscriptions (${dashboard expired length}) `); dashboard expired foreach(sub => { console log(` 📋 ${sub name} expired ${sub enddate}`); }); } if (dashboard canceled length > 0) { console log(`\n❌ canceled subscriptions (${dashboard canceled length}) `); dashboard canceled foreach(sub => { console log(` 📋 ${sub name} canceled ${sub enddate}`); }); } return dashboard; } catch (error) { console error('failed to build subscription dashboard ', error); throw error; } } // usage buildsubscriptiondashboard('d2e04653 ae90 49df a986 134cf64f6d03') then(dashboard => { console log('dashboard data ready for ui rendering'); // use dashboard data to render ui components }); common patterns and best practices error handling always implement robust error handling for subscription operations async function safesubscriptionfetch(customerids, options = {}) { try { const encodedids = encodeuricomponent(json stringify(customerids)); let url = `https //api nue io/subscriptions?customerids=${encodedids}`; // add optional parameters if (options status) url += `\&status=${options status}`; if (options includes) url += `\&includes=${options includes}`; if (options snapshotdate) url += `\&snapshotdate=${options snapshotdate}`; const response = await fetch(url, { method 'get', headers myheaders }); if (!response ok) { throw new error(`http error! status ${response status}`); } const result = await response json(); if (result status !== 'success' || !result data) { throw new error('unexpected response format'); } return result data; } catch (error) { console error('subscription fetch error ', error); // return empty array for graceful degradation return \[]; } } caching strategy implement appropriate caching for subscription data class subscriptioncache { constructor(ttlminutes = 30) { this cache = new map(); this ttl = ttlminutes 60 1000; } set(key, data) { this cache set(key, { data, timestamp date now() }); } get(key) { const cached = this cache get(key); if (!cached) return null; if (date now() cached timestamp > this ttl) { this cache delete(key); return null; } return cached data; } async getsubscriptions(customerids, options = {}) { const cachekey = `${customerids join(',')} ${json stringify(options)}`; const cached = this get(cachekey); if (cached) { console log('using cached subscription data'); return cached; } console log('fetching fresh subscription data'); const subscriptions = await safesubscriptionfetch(customerids, options); this set(cachekey, subscriptions); return subscriptions; } } // usage const subscriptioncache = new subscriptioncache(30); // 30 minute cache const subscriptions = await subscriptioncache getsubscriptions(\['customer id']); next steps now that you understand basic subscription operations, you can explore the subscription data reference for complete field documentation learn advanced subscription workflows for complex scenarios and integrations implement client side pricing for real time subscription modifications build comprehensive dashboards with subscription analytics move on to subscription data reference to understand all available fields and data structures, or advanced subscription workflows for complex integration scenarios