Subscription Terms

subscription terms subscription terms control the duration, billing cadence, renewal behavior, and date calculations for recurring products on a quote this guide covers all common term configurations, from standard annual subscriptions to evergreen contracts and backdated quotes use this guide when you need to configure subscription start and end dates, term lengths, billing periods, auto renewal, or per product term overrides term calculation rules the pricing engine requires any two of the following three values to calculate the third provided calculated rule subscriptionstartdate + subscriptionterm subscriptionenddate end date = start date + term subscriptionstartdate + subscriptionenddate subscriptionterm term = difference between dates in the specified dimension subscriptionenddate + subscriptionterm subscriptionstartdate start date = end date term if all three are provided, the engine uses the start date and term to verify the end date date conventions all dates use iso 8601 format yyyy mm dd (e g , 2025 01 01 ) the subscriptiontermdimension field specifies the unit for the term value valid values "month" , "year" , "day" when subscriptiontermdimension is "month" , a subscriptionterm of 12 equals one year billing configuration fields field type valid values default description billingperiod string "monthly" , "quarterly" , "semi annual" , "annual" inherited from product how often the customer is invoiced billingtiming string "in advance" , "in arrears" inherited from product whether billing occurs at the start or end of each period autorenew boolean true , false false whether the subscription automatically renews at end of term renewalterm number any positive integer same as subscriptionterm the term length for each renewal period evergreen boolean true , false false whether the subscription continues indefinitely with no fixed end date authentication setup all examples below use the following headers const myheaders = new headers(); myheaders append("nue api key", "your api key here"); myheaders append("content type", "application/json"); use case 1 standard 12 month term the most common configuration a 12 month subscription with explicit start date, end date, and term const quotedata = { opportunityid "006xx000001abc123", name "standard annual subscription", subscriptionstartdate "2025 01 01", subscriptionenddate "2026 01 01", subscriptiontermdimension "month", subscriptionterm 12, products \[ { productsku "platform base", uom "user/month", quantity 50 } ] }; fetch('https //api nue io/cpq/quotes\ preview', { method 'post', headers myheaders, body json stringify(quotedata) }) then(response => response json()) then(result => { console log(`start ${result quote subscriptionstartdate}`); console log(`end ${result quote subscriptionenddate}`); console log(`term ${result quote subscriptionterm} months`); console log(`total $${result quote totalamount}`); }) catch(error => console log('error ', error)); curl x post 'https //api nue io/cpq/quotes\ preview' \\ h 'nue api key your api key here' \\ h 'content type application/json' \\ d '{ "opportunityid" "006xx000001abc123", "name" "standard annual subscription", "subscriptionstartdate" "2025 01 01", "subscriptionenddate" "2026 01 01", "subscriptiontermdimension" "month", "subscriptionterm" 12, "products" \[ { "productsku" "platform base", "uom" "user/month", "quantity" 50 } ] }' the pricing engine calculates listunitprice quantity 12 months use case 2 24 month term with future start date create a subscription that starts 3 months in the future with a 24 month term the end date is calculated automatically const quotedata = { opportunityid "006xx000001abc123", name "24 month future start", subscriptionstartdate "2025 04 01", subscriptiontermdimension "month", subscriptionterm 24, products \[ { productsku "platform base", uom "user/month", quantity 100 } ] }; fetch('https //api nue io/cpq/quotes\ preview', { method 'post', headers myheaders, body json stringify(quotedata) }) then(response => response json()) then(result => { console log(`start ${result quote subscriptionstartdate}`); // 2025 04 01 console log(`end ${result quote subscriptionenddate}`); // 2027 04 01 (calculated) console log(`term ${result quote subscriptionterm} months`); // 24 console log(`total $${result quote totalamount}`); }) catch(error => console log('error ', error)); curl x post 'https //api nue io/cpq/quotes\ preview' \\ h 'nue api key your api key here' \\ h 'content type application/json' \\ d '{ "opportunityid" "006xx000001abc123", "name" "24 month future start", "subscriptionstartdate" "2025 04 01", "subscriptiontermdimension" "month", "subscriptionterm" 24, "products" \[ { "productsku" "platform base", "uom" "user/month", "quantity" 100 } ] }' by providing only subscriptionstartdate and subscriptionterm , the pricing engine calculates subscriptionenddate as 2027 04 01 use case 3 short term subscriptions (3 and 6 months) create short term subscriptions by specifying a lower subscriptionterm multiple products can share the same term const quotedata = { opportunityid "006xx000001abc123", name "short term 6 month trial", subscriptionstartdate "2025 01 01", subscriptiontermdimension "month", subscriptionterm 6, products \[ { productsku "platform base", uom "user/month", quantity 25 }, { productsku "analytics addon", uom "user/month", quantity 25 } ] }; fetch('https //api nue io/cpq/quotes\ preview', { method 'post', headers myheaders, body json stringify(quotedata) }) then(response => response json()) then(result => { console log(`term ${result quote subscriptionterm} months`); console log(`end ${result quote subscriptionenddate}`); // 2025 07 01 (calculated) console log(`total $${result quote totalamount}`); // pricing reflects 6 months, not 12 }) catch(error => console log('error ', error)); curl x post 'https //api nue io/cpq/quotes\ preview' \\ h 'nue api key your api key here' \\ h 'content type application/json' \\ d '{ "opportunityid" "006xx000001abc123", "name" "short term 6 month trial", "subscriptionstartdate" "2025 01 01", "subscriptiontermdimension" "month", "subscriptionterm" 6, "products" \[ { "productsku" "platform base", "uom" "user/month", "quantity" 25 }, { "productsku" "analytics addon", "uom" "user/month", "quantity" 25 } ] }' the total reflects 6 months of recurring charges rather than 12 the calculated end date is 2025 07 01 use case 4 per product term overrides different products on the same quote can have different subscription terms set subscriptionterm , subscriptionstartdate , and subscriptionenddate at the product level to override the quote level values const quotedata = { opportunityid "006xx000001abc123", name "mixed term lengths", subscriptionstartdate "2025 01 01", subscriptionenddate "2026 01 01", subscriptiontermdimension "month", subscriptionterm 12, products \[ { productsku "platform base", uom "user/month", quantity 50 // inherits quote level 12 month term, 2025 01 01 to 2026 01 01 }, { productsku "analytics addon", uom "user/month", quantity 50, subscriptionterm 6, subscriptionstartdate "2025 01 01", subscriptionenddate "2025 07 01" // override 6 month term for this product only }, { productsku "premium support", uom "user/month", quantity 50, subscriptionterm 24, subscriptionstartdate "2025 01 01", subscriptionenddate "2027 01 01" // override 24 month term for this product only } ] }; fetch('https //api nue io/cpq/quotes\ preview', { method 'post', headers myheaders, body json stringify(quotedata) }) then(response => response json()) then(result => { result quotelineitems foreach(item => { console log(`${item product sku} term=${item subscriptionterm}mo, $${item totalprice}`); }); }) catch(error => console log('error ', error)); curl x post 'https //api nue io/cpq/quotes\ preview' \\ h 'nue api key your api key here' \\ h 'content type application/json' \\ d '{ "opportunityid" "006xx000001abc123", "name" "mixed term lengths", "subscriptionstartdate" "2025 01 01", "subscriptionenddate" "2026 01 01", "subscriptiontermdimension" "month", "subscriptionterm" 12, "products" \[ { "productsku" "platform base", "uom" "user/month", "quantity" 50 }, { "productsku" "analytics addon", "uom" "user/month", "quantity" 50, "subscriptionterm" 6, "subscriptionstartdate" "2025 01 01", "subscriptionenddate" "2025 07 01" }, { "productsku" "premium support", "uom" "user/month", "quantity" 50, "subscriptionterm" 24, "subscriptionstartdate" "2025 01 01", "subscriptionenddate" "2027 01 01" } ] }' result platform base 12 month term (inherited from quote header) analytics addon 6 month term (product level override) premium support 24 month term (product level override) each line item's totalprice reflects its own term length use case 5 auto renew configuration enable automatic renewal by setting autorenew true on the quote optionally specify a renewalterm for the renewal period length if renewalterm is not provided, it defaults to the original subscriptionterm const quotedata = { opportunityid "006xx000001abc123", name "auto renewing annual subscription", subscriptionstartdate "2025 01 01", subscriptionenddate "2026 01 01", subscriptiontermdimension "month", subscriptionterm 12, autorenew true, renewalterm 12, products \[ { productsku "platform base", uom "user/month", quantity 50 }, { productsku "analytics addon", uom "user/month", quantity 25 } ] }; fetch('https //api nue io/cpq/quotes\ preview', { method 'post', headers myheaders, body json stringify(quotedata) }) then(response => response json()) then(result => { console log(`auto renew ${result quote autorenew}`); // true console log(`renewal term ${result quote renewalterm} months`); // 12 console log(`total (initial term) $${result quote totalamount}`); }) catch(error => console log('error ', error)); curl x post 'https //api nue io/cpq/quotes\ preview' \\ h 'nue api key your api key here' \\ h 'content type application/json' \\ d '{ "opportunityid" "006xx000001abc123", "name" "auto renewing annual subscription", "subscriptionstartdate" "2025 01 01", "subscriptionenddate" "2026 01 01", "subscriptiontermdimension" "month", "subscriptionterm" 12, "autorenew" true, "renewalterm" 12, "products" \[ { "productsku" "platform base", "uom" "user/month", "quantity" 50 }, { "productsku" "analytics addon", "uom" "user/month", "quantity" 25 } ] }' the quote is priced for the initial 12 month term the autorenew and renewalterm values are stored on the resulting subscription and control automatic renewal behavior at the end of the initial term use case 6 billing period and timing overrides override the default billing period and timing at the quote level these values apply to all products unless overridden at the product level const quotedata = { opportunityid "006xx000001abc123", name "monthly in advance billing", subscriptionstartdate "2025 01 01", subscriptionenddate "2026 01 01", subscriptiontermdimension "month", subscriptionterm 12, billingperiod "monthly", billingtiming "in advance", products \[ { productsku "platform base", uom "user/month", quantity 50 }, { productsku "analytics addon", uom "user/month", quantity 25 } ] }; fetch('https //api nue io/cpq/quotes\ preview', { method 'post', headers myheaders, body json stringify(quotedata) }) then(response => response json()) then(result => { console log(`billing period ${result quote billingperiod}`); // monthly console log(`billing timing ${result quote billingtiming}`); // in advance console log(`total $${result quote totalamount}`); result quotelineitems foreach(item => { console log(`${item product sku} billingperiod=${item billingperiod}, billingtiming=${item billingtiming}`); }); }) catch(error => console log('error ', error)); curl x post 'https //api nue io/cpq/quotes\ preview' \\ h 'nue api key your api key here' \\ h 'content type application/json' \\ d '{ "opportunityid" "006xx000001abc123", "name" "monthly in advance billing", "subscriptionstartdate" "2025 01 01", "subscriptionenddate" "2026 01 01", "subscriptiontermdimension" "month", "subscriptionterm" 12, "billingperiod" "monthly", "billingtiming" "in advance", "products" \[ { "productsku" "platform base", "uom" "user/month", "quantity" 50 }, { "productsku" "analytics addon", "uom" "user/month", "quantity" 25 } ] }' both products inherit the quote level billingperiod and billingtiming the total amount is the same regardless of billing period billing period affects invoice scheduling, not the quote total use case 7 evergreen subscriptions an evergreen subscription has no fixed end date it continues indefinitely until explicitly canceled set evergreen true on the quote when evergreen is enabled, subscriptionenddate and subscriptionterm are not required const quotedata = { opportunityid "006xx000001abc123", name "evergreen subscription", subscriptionstartdate "2025 01 01", subscriptiontermdimension "month", evergreen true, billingperiod "monthly", products \[ { productsku "platform base", uom "user/month", quantity 50 } ] }; fetch('https //api nue io/cpq/quotes\ preview', { method 'post', headers myheaders, body json stringify(quotedata) }) then(response => response json()) then(result => { console log(`evergreen ${result quote evergreen}`); // true console log(`end date ${result quote subscriptionenddate}`); // null or not set console log(`total $${result quote totalamount}`); // total is typically calculated for one billing period }) catch(error => console log('error ', error)); curl x post 'https //api nue io/cpq/quotes\ preview' \\ h 'nue api key your api key here' \\ h 'content type application/json' \\ d '{ "opportunityid" "006xx000001abc123", "name" "evergreen subscription", "subscriptionstartdate" "2025 01 01", "subscriptiontermdimension" "month", "evergreen" true, "billingperiod" "monthly", "products" \[ { "productsku" "platform base", "uom" "user/month", "quantity" 50 } ] }' note evergreen subscriptions conflict with autorenew do not set both evergreen true and autorenew true an evergreen subscription has no term boundary to trigger renewal use case 8 term calculation from dates provide only subscriptionstartdate and subscriptionenddate and let the pricing engine calculate the term automatically this is useful when the business requirement is defined by calendar dates rather than a fixed number of months const quotedata = { opportunityid "006xx000001abc123", name "date driven term calculation", subscriptionstartdate "2025 03 15", subscriptionenddate "2026 09 15", subscriptiontermdimension "month", products \[ { productsku "platform base", uom "user/month", quantity 50 } ] }; fetch('https //api nue io/cpq/quotes\ preview', { method 'post', headers myheaders, body json stringify(quotedata) }) then(response => response json()) then(result => { console log(`start ${result quote subscriptionstartdate}`); // 2025 03 15 console log(`end ${result quote subscriptionenddate}`); // 2026 09 15 console log(`calculated term ${result quote subscriptionterm} months`); // 18 console log(`total $${result quote totalamount}`); }) catch(error => console log('error ', error)); curl x post 'https //api nue io/cpq/quotes\ preview' \\ h 'nue api key your api key here' \\ h 'content type application/json' \\ d '{ "opportunityid" "006xx000001abc123", "name" "date driven term calculation", "subscriptionstartdate" "2025 03 15", "subscriptionenddate" "2026 09 15", "subscriptiontermdimension" "month", "products" \[ { "productsku" "platform base", "uom" "user/month", "quantity" 50 } ] }' the pricing engine calculates the term as 18 months (from march 15, 2025 to september 15, 2026) and prices accordingly use case 9 backdated quotes create a quote with a start date in the past this is useful for retroactive contracts or late entry deals the pricing engine calculates the term and total based on the provided dates regardless of the current calendar date const quotedata = { opportunityid "006xx000001abc123", name "backdated quote", subscriptionstartdate "2024 10 01", subscriptionenddate "2025 10 01", subscriptiontermdimension "month", subscriptionterm 12, products \[ { productsku "platform base", uom "user/month", quantity 50 } ] }; fetch('https //api nue io/cpq/quotes\ preview', { method 'post', headers myheaders, body json stringify(quotedata) }) then(response => response json()) then(result => { console log(`start ${result quote subscriptionstartdate}`); // 2024 10 01 (in the past) console log(`end ${result quote subscriptionenddate}`); // 2025 10 01 console log(`term ${result quote subscriptionterm} months`); // 12 console log(`total $${result quote totalamount}`); }) catch(error => console log('error ', error)); curl x post 'https //api nue io/cpq/quotes\ preview' \\ h 'nue api key your api key here' \\ h 'content type application/json' \\ d '{ "opportunityid" "006xx000001abc123", "name" "backdated quote", "subscriptionstartdate" "2024 10 01", "subscriptionenddate" "2025 10 01", "subscriptiontermdimension" "month", "subscriptionterm" 12, "products" \[ { "productsku" "platform base", "uom" "user/month", "quantity" 50 } ] }' the pricing engine does not reject past start dates the full 12 month term is priced normally downstream billing and invoicing systems handle proration or catch up invoices for the elapsed period term and billing field reference field type scope description subscriptionstartdate string (iso date) quote root, product start date of the subscription subscriptionenddate string (iso date) quote root, product end date of the subscription subscriptionterm number quote root, product duration of the subscription in the specified dimension subscriptiontermdimension string quote root unit for the term "month" , "year" , or "day" billingperiod string quote root, product invoice frequency "monthly" , "quarterly" , "semi annual" , "annual" billingtiming string quote root, product when to bill "in advance" or "in arrears" autorenew boolean quote root whether the subscription auto renews renewalterm number quote root term length for renewals (defaults to subscriptionterm ) evergreen boolean quote root whether the subscription is open ended with no fixed end date key behaviors summary scenario what happens start + term provided, no end date end date is calculated automatically start + end date provided, no term term is calculated automatically all three provided start + term used; end date verified product level term override product uses its own dates/term instead of quote header autorenew true subscription renews at end of term for renewalterm months evergreen true no end date; subscription continues until canceled evergreen true + autorenew true conflict do not combine; evergreen has no renewal boundary backdated start date accepted; pricing calculated normally from the past date billingperiod / billingtiming affects invoice scheduling, not the quote total amount next steps docid\ y9awhgt5iyiblymwve6nx apply header, parent, and line level discretionary discounts docid\ z5zott7eszhmhaxifqmkr apply tiered, volume, and ramp pricing adjustments docid\ fri8qggg2m1jvpi qlnvi work with bundle products and add ons docid\ bc idxynwaus7o9efycwq return to the full api reference