Fetching Subscription Data

this guide provides comprehensive instructions for retrieving subscription data using the nue lifecycle management api learn how to fetch customer subscriptions, create point in time snapshots, analyze upcoming changes, and implement efficient subscription data retrieval patterns prerequisites before you begin, ensure you have a valid nue api key with subscription read permissions customer ids for the subscriptions you want to retrieve basic understanding of rest apis and json familiarity with subscription data structures and lifecycle authentication all subscription retrieval 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"); rest endpoints the nue api provides rest endpoints for flexible subscription data access // global subscription endpoints get https //api nue io/subscriptions // get all subscriptions with pagination get https //api nue io/subscriptions/{subscriptionname} // get a specific subscription by name // customer scoped subscription endpoints get https //api nue io/customers/{customerid}/subscriptions // get subscriptions for a customer get https //api nue io/customers/{customerid}/subscriptions/{subscriptionname} // get a specific subscription for a customer advanced filtering subscription endpoints support advanced filtering using query parameters you can filter by any subscription field except reserved parameters reserved parameters (cannot be used for filtering) customerids , name , includes , page , limit , predicate , history , version , snapshotdate dynamic filtering examples // filter by status and customer get https //api nue io/subscriptions?status=active\&customerid=001ks00000dvz1ayad // filter with date ranges and logic operators get https //api nue io/subscriptions?startdate>=2024 01 01\&status=active& predicate=and // customer scoped filtering get https //api nue io/customers/001ks00000dvz1ayad/subscriptions?status=active\&autorenew=true supported operators equality field=value comparison field>=value , field<=value , field>value , field\<value inequality field!=value , field<>value common status values active , expired , canceled , draft basic subscription retrieval fetch all subscriptions for customer try it now fetch subscriptions → https //api docs nue io/fetch subscriptions const myheaders = new headers(); myheaders append("nue api key", "your api key here"); myheaders append("content type", "application/json"); // fetch all subscriptions for a customer const customerids = \["d2e04653 ae90 49df a986 134cf64f6d03"]; 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('subscriptions retrieved successfully ', result); if (result status === 'success' && result data) { console log(`found ${result data length} subscriptions for customer`); // display subscription summary result data foreach((subscription, index) => { console log(`\n${index + 1} ${subscription name || subscription id}`); 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(` auto renew ${subscription autorenew}`); console log(` total value $${subscription totalamount || subscription tcv}`); console log(` list price $${subscription listprice}`); console log(` sales price $${subscription salesprice}`); // display term information if (subscription subscriptionterm) { console log(` term ${subscription subscriptionterm} months`); } // display billing information if (subscription billingperiod) { console log(` billing period ${subscription billingperiod}`); } if (subscription billingtiming) { console log(` billing timing ${subscription billingtiming}`); } if (subscription nextbillingdate) { console log(` next billing ${subscription nextbillingdate}`); } }); } }) catch(error => console log('error ', error)); fetch subscriptions for multiple customers retrieve subscriptions for multiple customers in a single api call // fetch subscriptions for multiple customers const customerids = \[ "d2e04653 ae90 49df a986 134cf64f6d03", "cc5e1f0f 5e14 48cc ab98 9e5b191aa46f", "f1b2c3d4 e5f6 7890 abcd ef1234567890" ]; const encodedcustomerids = encodeuricomponent(json stringify(customerids)); fetch(`https //api nue io/subscriptions?customerids=${encodedcustomerids}`, { method 'get', headers myheaders }) then(response => response json()) then(result => { if (result status === 'success') { console log(`retrieved subscriptions for ${customerids length} customers`); // group subscriptions by customer const subscriptionsbycustomer = {}; result data foreach(subscription => { const customerid = subscription customerid; if (!subscriptionsbycustomer\[customerid]) { subscriptionsbycustomer\[customerid] = \[]; } subscriptionsbycustomer\[customerid] push(subscription); }); // display grouped results object keys(subscriptionsbycustomer) foreach(customerid => { const subscriptions = subscriptionsbycustomer\[customerid]; console log(`\n customer ${customerid} `); console log(`subscriptions ${subscriptions length}`); // calculate totals const totalvalue = subscriptions reduce((sum, sub) => sum + (sub totalamount || 0), 0); const activecount = subscriptions filter(s => s status === 'active') length; console log(`active ${activecount}/${subscriptions length}`); console log(`total value $${totalvalue tolocalestring()}`); subscriptions foreach(subscription => { console log(` • ${subscription name || subscription id} ${subscription status} $${subscription totalamount || 0}`); }); }); } }) catch(error => console log('error ', error)); filtered subscription retrieval fetch active subscriptions only filter subscriptions by status to retrieve only active subscriptions const customerids = \["d2e04653 ae90 49df a986 134cf64f6d03"]; const encodedcustomerids = encodeuricomponent(json stringify(customerids)); // fetch only active subscriptions const url = `https //api nue io/subscriptions?customerids=${encodedcustomerids}\&status=active`; fetch(url, { method 'get', headers myheaders }) then(response => response json()) then(result => { if (result status === 'success') { console log('🟢 active subscriptions retrieved'); if (result data && result data length > 0) { result data foreach(subscription => { console log(`\n📦 ${subscription name || subscription id}`); console log(` product ${subscription productid}`); console log(` status ${subscription status}`); console log(` quantity ${subscription quantity}`); console log(` current period ${subscription subscriptionstartdate} to ${subscription subscriptionenddate}`); console log(` monthly value $${(subscription totalamount / (subscription subscriptionterm || 12)) tofixed(2)}`); console log(` auto renew ${subscription autorenew ? 'yes' 'no'}`); // show renewal information if (subscription renewalterm) { console log(` renewal term ${subscription renewalterm} months`); } // show bundling information if (subscription bundled) { console log(` bundled yes (level ${subscription subscriptionlevel})`); } }); } else { console log('no active subscriptions found for this customer'); } } }) catch(error => console log('error ', error)); fetch specific subscription by name retrieve a specific subscription using its name const subscriptionname = "enterprise software license acme corp"; const encodedname = encodeuricomponent(subscriptionname); fetch(`https //api nue io/subscriptions?name=${encodedname}`, { method 'get', headers myheaders }) then(response => response json()) then(result => { if (result status === 'success' && result data length > 0) { const subscription = result data\[0]; console log('🎯 specific subscription retrieved'); console log(`name ${subscription name}`); console log(`id ${subscription id}`); console log(`customer ${subscription customerid}`); console log(`status ${subscription status}`); console log(`product ${subscription productid}`); console log(`quantity ${subscription quantity}`); console log(`total contract value $${subscription tcv}`); console log(`annual contract value $${subscription totalacv}`); console log(`subscription period ${subscription subscriptionstartdate} to ${subscription subscriptionenddate}`); if (subscription externalid) { console log(`external id ${subscription externalid}`); } } else { console log('subscription not found'); } }) catch(error => console log('error ', error)); including related data fetch subscriptions with product details include product information in the subscription response const customerids = \["d2e04653 ae90 49df a986 134cf64f6d03"]; const encodedids = encodeuricomponent(json stringify(customerids)); // include product details in the response const urlwithproducts = `https //api nue io/subscriptions?customerids=${encodedids}\&includes=product`; fetch(urlwithproducts, { method 'get', headers myheaders }) then(response => response json()) then(result => { if (result status === 'success' && result data) { result data foreach(subscription => { console log(`\n📦 subscription ${subscription name || subscription id}`); console log(` status ${subscription status}`); console log(` quantity ${subscription quantity}`); console log(` value $${subscription totalamount}`); // display product information if included if (subscription product) { console log(`\n 📋 product details `); console log(` name ${subscription product name}`); console log(` sku ${subscription product sku}`); console log(` category ${subscription product productcategory}`); console log(` price model ${subscription product pricemodel}`); } // display pricing tags if included if (subscription pricetags && subscription pricetags length > 0) { console log(`\n 🏷️ applied price tags `); subscription pricetags foreach(tag => { console log(` • ${tag name} ${tag type} ${tag value}`); }); } }); } }) catch(error => console log('error ', error)); fetch with all available data include all available related data // include all available data types const urlwithall = `https //api nue io/subscriptions?customerids=${encodedids}\&includes=product,pricetags`; fetch(urlwithall, { method 'get', headers myheaders }) then(response => response json()) then(result => { if (result status === 'success' && result data) { result data foreach(subscription => { console log(`\n🎯 complete subscription details ${subscription name || subscription id}`); console log(` status ${subscription status}`); console log(` customer ${subscription customerid}`); console log(` period ${subscription subscriptionstartdate} to ${subscription subscriptionenddate}`); // financial summary console log(`\n 💰 financial details `); console log(` list price $${subscription listprice || 0}`); console log(` sales price $${subscription salesprice || 0}`); console log(` total amount $${subscription totalamount || 0}`); console log(` tcv $${subscription tcv || 0}`); console log(` acv $${subscription totalacv || 0}`); // product details if (subscription product) { console log(`\n 📋 product `); console log(` ${subscription product name} (${subscription product sku})`); console log(` category ${subscription product productcategory}`); console log(` price model ${subscription product pricemodel}`); } // bundle information if (subscription bundled) { console log(`\n 📦 bundle details `); console log(` bundled yes`); console log(` level ${subscription subscriptionlevel}`); console log(` parent ${subscription parentsubscriptionobject || 'n/a'}`); } // billing information console log(`\n 🧾 billing `); console log(` billing account ${subscription billingaccountid}`); console log(` billing timing ${subscription billingtiming || 'standard'}`); // renewal information console log(`\n 🔄 renewal `); console log(` auto renew ${subscription autorenew ? 'yes' 'no'}`); console log(` renewal term ${subscription renewalterm || 'same as original'} months`); console log(` evergreen ${subscription evergreen ? 'yes' 'no'}`); }); } }) catch(error => console log('error ', error)); point in time snapshots and historical analysis subscription snapshots provide powerful capabilities for historical analysis, compliance reporting, and business intelligence unlike the current contract view which shows the complete subscription timeline, snapshots show the exact state of subscriptions as they existed on a specific date understanding subscription snapshots snapshots show the exact state of subscriptions as they existed on a specific date, including upcoming changes scheduled from that point forward key differences from current contract view current view complete timeline for operational management snapshot view point in time state for historical analysis and compliance primary use cases historical billing reconciliation compliance and audit reporting change impact analysis fetch snapshot by customer generate a point in time snapshot to see subscription state at a specific date // fetch snapshot by customer ids const customerids = \["d2e04653 ae90 49df a986 134cf64f6d03"]; const encodedids = encodeuricomponent(json stringify(customerids)); const snapshotdate = "2025 06 26"; fetch(`https //api nue io/subscriptions?customerids=${encodedids}\&snapshotdate=${snapshotdate}\&includes=upcomingchanges`, { method 'get', headers myheaders }) then(response => response json()) then(result => { if (result status === 'success' && result data) { console log(`📸 customer snapshot for ${snapshotdate}`); result data foreach(subscription => { console log(`\n📦 ${subscription name}`); console log(` status ${subscription status}`); console log(` quantity ${subscription quantity}`); console log(` period ${subscription subscriptionstartdate} to ${subscription subscriptionenddate}`); // show upcoming changes from snapshot date if (subscription upcomingchanges && subscription upcomingchanges length > 0) { console log(` 📅 upcoming changes `); subscription upcomingchanges foreach(change => { console log(` • ${change changetype} on ${change startdate}`); }); } }); } }) catch(error => console log('error ', error)); fetch snapshot by subscription name retrieve snapshot for a specific subscription by name // fetch snapshot by subscription name const subscriptionname = "enterprise license customer"; const snapshotdate = "2025 06 26"; fetch(`https //api nue io/subscriptions?name=${encodeuricomponent(subscriptionname)}\&snapshotdate=${snapshotdate}\&includes=upcomingchanges`, { method 'get', headers myheaders }) then(response => response json()) then(result => { if (result status === 'success' && result data length > 0) { const subscription = result data\[0]; console log(`📸 subscription snapshot ${subscription name}`); console log(` snapshot date ${subscription snapshotdate}`); console log(` customer ${subscription customerid}`); console log(` status ${subscription status}`); console log(` quantity ${subscription quantity}`); console log(` acv $${subscription totalacv}`); // show what changes were scheduled from this snapshot date if (subscription upcomingchanges && subscription upcomingchanges length > 0) { console log(`\n📅 changes scheduled from ${snapshotdate} `); subscription upcomingchanges foreach(change => { console log(` • ${change changetype} on ${change startdate}`); if (change changeinquantity) { console log(` quantity change ${change changeinquantity > 0 ? '+' ''}${change changeinquantity}`); } }); } else { console log(`\n📅 no changes scheduled from ${snapshotdate}`); } } }) catch(error => console log('error ', error)); snapshot response structure key snapshot specific fields { "status" "success", "data" \[ { "id" "f594fd3a 3659 4039 ae5c b2c6863d98a5", "name" "sub 00000309", "snapshotdate" "2025 01 15", "customerid" "81dd1eb9 7a2c 4486 be76 b1ac2f88bbb1", "status" "active", "quantity" 2, "subscriptionstartdate" "2025 07 01", "subscriptionenddate" "2026 06 30", "parentid" "3b573778 89c0 491d a972 bd3073d9add4", "upcomingchanges" \[ { "changetype" "updatequantity", "startdate" "2025 02 01", "changeinquantity" 5 } ] } ], "warnings" \[] } subscription history analysis fetch subscription history for trend analysis async function analyzesubscriptionhistory(subscriptionname) { const encodedname = encodeuricomponent(subscriptionname); const url = `https //api nue io/subscriptions?name=${encodedname}\&history=true`; try { const response = await fetch(url, { method 'get', headers myheaders }); const result = await response json(); if (result status === 'success' && result data length > 0) { console log(`📈 subscription history analysis ${subscriptionname}`); console log('=' repeat(60)); // sort by version to show evolution const sortedhistory = result data sort((a, b) => a subscriptionversion b subscriptionversion); sortedhistory foreach((version, index) => { console log(`\n${index + 1} version ${version subscriptionversion}`); console log(` period ${version subscriptionstartdate} to ${version subscriptionenddate}`); console log(` status ${version status}`); console log(` quantity ${version quantity}`); console log(` total amount $${version totalamount || 0}`); console log(` modified ${version lastmodifieddate} by ${version lastmodifiedbyid}`); // compare with previous version if (index > 0) { const previous = sortedhistory\[index 1]; const quantitychange = version quantity previous quantity; const amountchange = (version totalamount || 0) (previous totalamount || 0); if (quantitychange !== 0 || amountchange !== 0) { console log(` 📊 changes from previous version `); if (quantitychange !== 0) { console log(` quantity ${quantitychange > 0 ? '+' ''}${quantitychange}`); } if (amountchange !== 0) { console log(` amount ${amountchange > 0 ? '+' ''}$${amountchange tolocalestring()}`); } } } }); // generate summary insights console log(`\n💡 history insights `); console log(` total versions ${sortedhistory length}`); const firstversion = sortedhistory\[0]; const currentversion = sortedhistory\[sortedhistory length 1]; const totalquantitychange = currentversion quantity firstversion quantity; const totalamountchange = (currentversion totalamount || 0) (firstversion totalamount || 0); console log(` quantity evolution ${firstversion quantity} → ${currentversion quantity} (${totalquantitychange > 0 ? '+' ''}${totalquantitychange})`); console log(` value evolution $${firstversion totalamount || 0} → $${currentversion totalamount || 0} (${totalamountchange > 0 ? '+' ''}$${totalamountchange tolocalestring()})`); return sortedhistory; } else { console log('no subscription history found'); return \[]; } } catch (error) { console error('history analysis failed ', error); return \[]; } } // usage example analyzesubscriptionhistory("enterprise software license acme corp") then(history => { console log(`analysis complete ${history length} versions analyzed`); }); query parameters reference parameter type required description options customerids array\[string] json encoded array of customer ids \["customer uuid 1", "customer uuid 2"] name string specific subscription name to fetch "enterprise license customer" snapshotdate string no point in time snapshot date (yyyy mm dd) "2025 06 26" status string no filter by subscription status "active" , "expired" , "canceled" version string no filter by version type "latest" , "snapshot" history boolean no include subscription history true , false includes string no related data to include "product" , "pricetags" , "upcomingchanges" either customerids or name is required response structure regular subscription response (200 ok) { "status" "success", "data" \[ { "actualsubscriptionterm" 12, "autorenew" true, "billcycleday" "7th of month", "billcyclestartmonth" "03", "billingaccountid" "81dd1eb9 7a2c 4486 be76 b1ac2f88bbb1", "billingperiod" "annual", "billingtiming" "in advance", "bundled" true, "createdbyid" "74ef82c9 a9d7 4262 8331 ba7ac33d1f76", "createddate" "2025 07 02t23 12 30 582z", "customerid" "81dd1eb9 7a2c 4486 be76 b1ac2f88bbb1", "evergreen" false, "id" "f594fd3a 3659 4039 ae5c b2c6863d98a5", "lastmodifiedbyid" "74ef82c9 a9d7 4262 8331 ba7ac33d1f76", "lastmodifieddate" "2025 07 02t23 12 30 621z", "listprice" 19 9, "name" "sub 00000309", "nextbillingdate" "2025 07 01", "orderondate" "2025 07 02", "orderproductid" "03139976 1cc2 4430 8f61 996e641c8745", "parentid" "3b573778 89c0 491d a972 bd3073d9add4", "parentobjecttype" "subscription", "pricebookentryid" "01u7z000005ynbaaa4", "pricebookid" "01s7z000006dt4raac", "productid" "01t7z00000dxt09aad", "quantity" 2, "renewalterm" 12, "rootid" "3b573778 89c0 491d a972 bd3073d9add4", "salesprice" 19 9, "status" "active", "subscriptioncompositeid" "sub 00000309 1", "subscriptionenddate" "2026 06 30", "subscriptionlevel" 2, "subscriptionstartdate" "2025 07 01", "subscriptionterm" 12, "subscriptionversion" 1, "taxamount" 0, "tcv" 0, "totalacv" 0, "totalamount" 0, "totalprice" 0, "totaltcv" 0, "uomid" "a0s7z00000hyfptaa5" } ], "warnings" \[] } snapshot response (with snapshotdate) { "status" "success", "data" \[ { "id" "subscription uuid", "name" "enterprise software license", "customerid" "customer uuid", "snapshotdate" "2025 06 26", "status" "active", "quantity" 100, "upcomingchanges" \[ { "changetype" "quantity increase", "startdate" "2025 07 01", "changeinquantity" 25, "updatedterm" 12, "updatedenddate" "2025 12 31" } ] } ], "warnings" \[] } error handling common retrieval errors error description resolution invalid customer id customer id format invalid verify customer id format subscription not found named subscription doesn't exist check subscription name spelling invalid snapshot date snapshot date format invalid use yyyy mm dd format parameter conflict conflicting parameters used review parameter restrictions robust subscription fetching async function safesubscriptionfetch(customerids, options = {}) { try { // validate inputs if (!array isarray(customerids) || customerids length === 0) { throw new error('customerids must be a non empty array'); } 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 ${response status} ${response statustext}`); } const result = await response json(); if (result status !== 'success') { throw new error(`api error ${result message || 'unknown error'}`); } return { subscriptions result data || \[], found result data? length || 0, requested customerids length, warnings result warnings || \[] }; } catch (error) { console error('subscription fetch error ', error); return { subscriptions \[], found 0, requested customerids length, error error message }; } } best practices data retrieval use appropriate filters to reduce data transfer include related data selectively based on needs leverage snapshots for historical analysis monitor upcoming changes proactively performance optimization batch customer queries efficiently cache frequently accessed subscription data use status filters to focus on relevant subscriptions implement pagination for large datasets business intelligence track subscription trends over time monitor renewal patterns and auto renew rates analyze product adoption across subscriptions generate renewal forecasts from expiration data this comprehensive guide enables you to efficiently retrieve and analyze subscription data using the nue lifecycle management api, supporting everything from simple lookups to complex portfolio analysis and predictive renewal management