Price Tags

price tags price tags modify pricing through volume, tiered, or ramp calculations they allow you to define dynamic pricing rules that are evaluated at quote time, giving you flexible pricing beyond simple per unit rates use this guide when you need to apply catalog defined pricing dimensions or discount dimensions to quote line items whether by referencing tags explicitly in the request or relying on auto attached tags from product configuration price tag types type description effect pricedimension (price tag) overrides or sets the unit price replaces the base unit price from the price book entry discountdimension (discount tag) applies a percentage or fixed amount discount reduces the price after the base unit price is resolved tag evaluation modes mode description example volume a single tier is selected based on the total quantity; all units use that tier's price 0 100 units = $10, 100 500 units = $8, 500+ units = $6 tiered units are distributed across tiers; each tier prices only the units within its range first 100 units at $10, the next 400 at $8, the remainder at $6 ramp different rates apply across time periods within the subscription term months 1 3 at 50% off, months 4 6 at 25% off, months 7 12 at full price tier ranges a tier matches when startunit < quantity <= endunit the lower bound is exclusive and the upper bound is inclusive consecutive tiers share a boundary, so each tier's startunit is the previous tier's endunit , and the first tier starts at 0 so that a quantity of 1 is covered tier startunit endunit covers 1 0 100 1 100 2 100 200 101 200 3 200 300 201 300 a quantity outside every tier above the last endunit , or in a gap left by non adjacent tiers receives no adjustment from the tag the request still succeeds and no error is returned, so verify the pricing fields on the line item to confirm a tier was applied how tags are applied price tags reach a line item through two mechanisms auto attached configured directly on the product in the catalog these tags are applied automatically whenever the product appears on a quote no action is required in the api request request applied specified explicitly in the pricetags array on the product input these are evaluated in addition to any auto attached tags pricetaginput structure tags can be referenced by code or by id you must provide one or the other not both "pricetags" \[ { "code" "volume tier enterprise" }, { "id" "a1b2c3d4e5f6g7h8" } ] field type required description code string one of code/id the price tag code defined in the catalog id string one of code/id the price tag record id important provide either code or id on a tag entry, not both sending both returns 400 pricetags\[0] only one of \[code, id] should be set referencing a tag by code and by id are otherwise equivalent a tag code that does not resolve is silently ignored the request returns 200 , the line is priced with no discount, and the tag is absent from the response pricetags array check pricetags in the response to confirm a tag was actually attached response pricetags each response line item carries a pricetags array listing the tags that were attached to that line every entry is the tag definition , including its full tier table "pricetags" \[ { "name" "volume tier enterprise", "id" "a0ihe000001wrqvyag", "recordtype" "discountdimension", "pricedimensiontype" "quantity", "pricetype" "volume", "active" true, "starttime" null, "endtime" null, "pricetiers" \[ { "tiernumber" 1, "startunit" 0 00, "startunitdimension" null, "endunit" 100 00, "endunitdimension" null, "chargemodel" "perunit", "amount" null, "discountpercentage" 0 00 }, { "tiernumber" 2, "startunit" 100 00, "startunitdimension" null, "endunit" null, "endunitdimension" null, "chargemodel" "perunit", "amount" null, "discountpercentage" 20 00 } ] } ] pricetags does not report the resolved outcome the array tells you which tags were attached and what their tiers are it does not say which tier matched or what was applied read the pricing fields on the line item itself to see the result a price tag resolves the unit price, so compare listprice and listtotalprice a discount tag lands in systemdiscount (percentage) and systemdiscountamount (currency), then subtotal = listtotalprice systemdiscountamount tag discounts do not populate discount or discountamount ; those hold discretionary discounts you pass in the request and stay 0 when only a tag applied for example, a 500 unit line at $2 00 with the tag above returns listtotalprice 12000 , systemdiscount 20 , systemdiscountamount 2400 and totalprice 9600 , while discount and discountamount remain 0 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 apply a discount tag by id reference a discount tag using its record id the tag's discount logic (percentage, amount, tiered, etc ) is evaluated by the pricing engine const quotedata = { opportunityid "006xx000001abc123", name "discount tag by id", subscriptionstartdate "2025 01 01", subscriptionenddate "2026 01 01", subscriptiontermdimension "month", subscriptionterm 12, products \[ { productsku "platform base", uom "user/month", quantity 100, pricetags \[{ id "a1b2c3d4e5f6g7h8" }] } ] }; fetch('https //api nue io/cpq/quotes\ preview', { method 'post', headers myheaders, body json stringify(quotedata) }) then(response => response json()) then(result => { const line = result quotelineitems\[0]; console log(`list price $${line listtotalprice}`); console log(`after tag $${line 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" "discount tag by id", "subscriptionstartdate" "2025 01 01", "subscriptionenddate" "2026 01 01", "subscriptiontermdimension" "month", "subscriptionterm" 12, "products" \[ { "productsku" "platform base", "uom" "user/month", "quantity" 100, "pricetags" \[{ "id" "a1b2c3d4e5f6g7h8" }] } ] }' the pricing engine looks up the tag by its record id, resolves the discount logic, and applies it to the line the pricetags array in the response confirms which tag was attached; read systemdiscount and systemdiscountamount on the line to see what it applied use case 2 apply a discount tag by code reference a discount tag using its code this is often more readable and portable across environments than using ids const quotedata = { opportunityid "006xx000001abc123", name "discount tag by code", subscriptionstartdate "2025 01 01", subscriptionenddate "2026 01 01", subscriptiontermdimension "month", subscriptionterm 12, products \[ { productsku "platform base", uom "user/month", quantity 100, pricetags \[{ code "regr disc qty tiered" }] } ] }; fetch('https //api nue io/cpq/quotes\ preview', { method 'post', headers myheaders, body json stringify(quotedata) }) then(response => response json()) then(result => { const line = result quotelineitems\[0]; console log(`list price $${line listtotalprice}`); console log(`discounted price $${line 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" "discount tag by code", "subscriptionstartdate" "2025 01 01", "subscriptionenddate" "2026 01 01", "subscriptiontermdimension" "month", "subscriptionterm" 12, "products" \[ { "productsku" "platform base", "uom" "user/month", "quantity" 100, "pricetags" \[{ "code" "regr disc qty tiered" }] } ] }' the regr disc qty tiered tag evaluates the quantity (100) against its tiered discount schedule and applies the appropriate discount use case 3 apply a price tag by code (unit price override) a pricedimension tag overrides the unit price from the price book entry this is used for volume pricing, tiered pricing, or any scenario where the per unit rate depends on quantity or other factors const quotedata = { opportunityid "006xx000001abc123", name "price tag override", subscriptionstartdate "2025 01 01", subscriptionenddate "2026 01 01", subscriptiontermdimension "month", subscriptionterm 12, products \[ { productsku "platform base", uom "user/month", quantity 500, pricetags \[{ code "volume tier enterprise" }] } ] }; fetch('https //api nue io/cpq/quotes\ preview', { method 'post', headers myheaders, body json stringify(quotedata) }) then(response => response json()) then(result => { const line = result quotelineitems\[0]; console log(`unit price (after tag) $${line listunitprice}`); console log(`total $${line 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" "price tag override", "subscriptionstartdate" "2025 01 01", "subscriptionenddate" "2026 01 01", "subscriptiontermdimension" "month", "subscriptionterm" 12, "products" \[ { "productsku" "platform base", "uom" "user/month", "quantity" 500, "pricetags" \[{ "code" "volume tier enterprise" }] } ] }' the volume tier enterprise tag evaluates the quantity (500) against its tier table and sets the appropriate unit price the resolved price shows up in the line's listprice and listtotalprice ; pricetags echoes the tag definition and its tiers use case 4 price tag and discount tag on the same line you can apply both a price tag and a discount tag to the same product the price tag resolves the unit price first, then the discount tag reduces the result const quotedata = { opportunityid "006xx000001abc123", name "price + discount tags combined", subscriptionstartdate "2025 01 01", subscriptionenddate "2026 01 01", subscriptiontermdimension "month", subscriptionterm 12, products \[ { productsku "platform base", uom "user/month", quantity 500, pricetags \[ { code "volume tier enterprise" }, { code "loyalty discount 10pct" } ] } ] }; fetch('https //api nue io/cpq/quotes\ preview', { method 'post', headers myheaders, body json stringify(quotedata) }) then(response => response json()) then(result => { const line = result quotelineitems\[0]; console log(`list unit price (from price tag) $${line listunitprice}`); console log(`total after discount tag $${line totalprice}`); console log('attached tags ', line pricetags); }) 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" "price + discount tags combined", "subscriptionstartdate" "2025 01 01", "subscriptionenddate" "2026 01 01", "subscriptiontermdimension" "month", "subscriptionterm" 12, "products" \[ { "productsku" "platform base", "uom" "user/month", "quantity" 500, "pricetags" \[ { "code" "volume tier enterprise" }, { "code" "loyalty discount 10pct" } ] } ] }' execution order the volume price tag sets the unit price based on the 500 unit tier, then the loyalty discount tag reduces the total by 10% both tags appear in the line's pricetags array, and the combined effect is visible in systemdiscount and systemdiscountamount use case 5 auto attached tags (no request input needed) if a product has auto attached tags configured in the catalog, they are applied automatically you do not need to include a pricetags array in the request the response still shows the applied tags const quotedata = { opportunityid "006xx000001abc123", name "auto attached tags only", subscriptionstartdate "2025 01 01", subscriptionenddate "2026 01 01", subscriptiontermdimension "month", subscriptionterm 12, products \[ { productsku "platform base", // has auto attached volume tier tag in catalog uom "user/month", quantity 200 // no pricetags array auto attached tags are applied automatically } ] }; fetch('https //api nue io/cpq/quotes\ preview', { method 'post', headers myheaders, body json stringify(quotedata) }) then(response => response json()) then(result => { const line = result quotelineitems\[0]; console log(`unit price (from auto attached tag) $${line listunitprice}`); console log(`total $${line totalprice}`); console log('attached tags ', line pricetags); // pricetags shows the auto attached tag even though none were in the request }) 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 attached tags only", "subscriptionstartdate" "2025 01 01", "subscriptionenddate" "2026 01 01", "subscriptiontermdimension" "month", "subscriptionterm" 12, "products" \[ { "productsku" "platform base", "uom" "user/month", "quantity" 200 } ] }' the pricing engine automatically evaluates the product's catalog configured tags if you also specify request applied tags in pricetags , both auto attached and request applied tags are evaluated together use case 6 different tags on different lines each product in the products array can have its own pricetags , allowing different pricing strategies per line const quotedata = { opportunityid "006xx000001abc123", name "per line tag assignment", subscriptionstartdate "2025 01 01", subscriptionenddate "2026 01 01", subscriptiontermdimension "month", subscriptionterm 12, products \[ { productsku "platform base", uom "user/month", quantity 500, pricetags \[{ code "volume tier enterprise" }] }, { productsku "analytics addon", uom "user/month", quantity 100, pricetags \[{ code "regr disc qty tiered" }] }, { productsku "data export", uom "user/month", quantity 50 // no pricetags uses base price book entry price (or auto attached tags) } ] }; 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 => { const tags = item pricetags || \[]; console log(`${item product sku} $${item listunitprice}/unit → $${item totalprice} total (${tags length} tags applied)`); }); }) 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" "per line tag assignment", "subscriptionstartdate" "2025 01 01", "subscriptionenddate" "2026 01 01", "subscriptiontermdimension" "month", "subscriptionterm" 12, "products" \[ { "productsku" "platform base", "uom" "user/month", "quantity" 500, "pricetags" \[{ "code" "volume tier enterprise" }] }, { "productsku" "analytics addon", "uom" "user/month", "quantity" 100, "pricetags" \[{ "code" "regr disc qty tiered" }] }, { "productsku" "data export", "uom" "user/month", "quantity" 50 } ] }' each product is priced independently platform base uses a volume tier tag, analytics addon uses a quantity tiered discount tag, and data export uses its base price (or auto attached tags from the catalog) use case 7 ramp discount tags (multi period) ramp discount tags apply different discount rates over different time periods within the subscription term for example, a tag might give 50% off for the first 3 months, then 25% off for months 4 6, and full price thereafter ramp tags are configured in the catalog with time based tiers you apply them the same way as any other tag const quotedata = { opportunityid "006xx000001abc123", name "ramp discount schedule", subscriptionstartdate "2025 01 01", subscriptionenddate "2026 01 01", subscriptiontermdimension "month", subscriptionterm 12, products \[ { productsku "platform base", uom "user/month", quantity 50, pricetags \[{ code "ramp onboarding discount" }] } ] }; fetch('https //api nue io/cpq/quotes\ preview', { method 'post', headers myheaders, body json stringify(quotedata) }) then(response => response json()) then(result => { const line = result quotelineitems\[0]; console log(`total (with ramp) $${line totalprice}`); console log('attached tags ', line pricetags); // the total reflects the blended price across all ramp periods }) 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" "ramp discount schedule", "subscriptionstartdate" "2025 01 01", "subscriptionenddate" "2026 01 01", "subscriptiontermdimension" "month", "subscriptionterm" 12, "products" \[ { "productsku" "platform base", "uom" "user/month", "quantity" 50, "pricetags" \[{ "code" "ramp onboarding discount" }] } ] }' the pricing engine evaluates the ramp schedule against the subscription dates and calculates a blended total across all ramp periods the line's pricetags echoes the ramp tag with its tier table; the blended result is in systemdiscountamount and totalprice tag application summary scenario request input what happens auto attached tag only no pricetags array needed catalog configured tags are applied automatically request applied tag by code pricetags \[{ code " " }] tag looked up by code and evaluated request applied tag by id pricetags \[{ id " " }] tag looked up by record id and evaluated auto attached + request applied pricetags array with additional tags both are evaluated; combined result price + discount tags together multiple entries in pricetags price tag resolves unit price first, then discount tag reduces different tags per line each product has its own pricetags tags evaluated independently per line ramp tag pricetags \[{ code "ramp " }] time based tiers evaluated against subscription dates price tag field reference field type location description pricetags array product input array of pricetaginput objects pricetags\[] code string pricetaginput tag code from the catalog (use code or id) pricetags\[] id string pricetaginput tag record id (use code or id) pricetags array response line item tag definitions attached to this line, each with its pricetiers does not report which tier resolved see systemdiscount / systemdiscountamount next steps discounts docid\ y9awhgt5iyiblymwve6nx apply header, parent, and line level discretionary discounts subscription terms docid\ wwo0bzasgs6mdcue g kl configure term lengths, billing periods, and renewal settings bundles docid\ fri8qggg2m1jvpi qlnvi work with bundle products and add ons create quote overview docid\ bc idxynwaus7o9efycwq return to the full api reference