Price Tag Data Reference

this comprehensive reference covers all price tag related data structures, field definitions, pricing behaviors, and validation rules in the nue self service api core price tag object the price tag object represents a pricing rule that can modify base product prices through discounts, volume pricing, or promotional campaigns price tag fields reference identification fields field type description example id string unique price tag identifier (salesforce price tag id) "a0x7z000007cckxeaw" name string display name for the price tag "enterprise volume discount" code string unique code for api references and fetching individual price tags "enterprise volume" description string detailed explanation of the pricing rule "30% discount for enterprise customers" status and publication field type description example active boolean whether the price tag is currently active true lastpublishedbyid string id of user who last published "005xx000001sv6yaas" lastpublisheddate string (iso 8601) date of last publication "2025 01 15t10 30 00z" pricing configuration field type description example pricetagtype string type of pricing rule "quantity" , "term" pricetype string pricing model "volume" , "tiered" , "ramp" uomdimension string unit of measure dimension "user" , "license" , "gb" recordtype string type of record "discountdimension" time based controls field type description example starttime string (iso 8601) when pricing becomes effective "2025 01 01t00 00 00z" endtime string (iso 8601) when pricing expires (optional) "2025 12 31t23 59 59z" price tiers object price tiers define the specific pricing rules within a price tag, including quantity ranges, discount percentages, and charge models price tier fields reference core tier fields field type description example id string unique tier identifier "a0yxx000001tdgreak" name string tier name "tier 1 1 10 users" tiernumber number order of the tier 1 chargemodel string how charges are calculated "perunit" , "flatfee" quantity range field type description example startunit number beginning of tier range 1 startunitdimension string unit type for start range "user" endunit number end of tier range 10 endunitdimension string unit type for end range "user" pricing values field type description example discountpercentage number percentage discount applied 15 0 amount number fixed price amount (for price tags) 85 00 price tag types and behaviors quantity based price tags behavior apply discounts or pricing based on the quantity of units purchased common use cases volume discounts (buy more, save more) bulk pricing tiers enterprise quantity thresholds example structure { "id" "a0x7z000007cckxeaw", "name" "volume discount platform licenses", "code" "volume platform", "pricetagtype" "quantity", "pricetype" "volume", "uomdimension" "user", "active" true, "publishstatus" "published", "pricetiers" \[ { "tiernumber" 1, "startunit" 1, "endunit" 9, "discountpercentage" 0 0, "chargemodel" "perunit" }, { "tiernumber" 2, "startunit" 10, "endunit" 49, "discountpercentage" 10 0, "chargemodel" "perunit" }, { "tiernumber" 3, "startunit" 50, "endunit" 999, "discountpercentage" 20 0, "chargemodel" "perunit" } ] } term based price tags behavior apply discounts based on subscription term length common use cases annual billing discounts multi year commitment rewards subscription length incentives example structure { "id" "a0x7z000007ddlxeaw", "name" "annual subscription discount", "code" "annual discount", "pricetagtype" "term", "pricetype" "volume", "uomdimension" "month", "active" true, "publishstatus" "published", "pricetiers" \[ { "tiernumber" 1, "startunit" 1, "endunit" 11, "discountpercentage" 0 0, "chargemodel" "perunit" }, { "tiernumber" 2, "startunit" 12, "endunit" 23, "discountpercentage" 15 0, "chargemodel" "perunit" }, { "tiernumber" 3, "startunit" 24, "endunit" 999, "discountpercentage" 25 0, "chargemodel" "perunit" } ] } pricing models volume pricing behavior all units in the order receive the same discount based on total quantity order 25 units, all 25 get the 10% discount simple to understand and calculate best for straightforward volume discounts tiered pricing behavior different portions of the order receive different pricing first 10 units at full price next 15 units at 10% discount remaining units at 20% discount more complex but can provide better granular control ramp pricing behavior pricing changes over time within the subscription year 1 full price year 2 10% discount year 3+ 20% discount useful for long term commitment incentives price tag application automatic application price tags are automatically applied when order meets quantity criteria defined in the price tag tiers subscription term matches term based price tag requirements price tag is active and published current date falls within the price tag's effective period no conflicting exclusions are in place manual application price tags can be manually applied using in order requests { "orderproducts" \[ { "pricebookentryid" "01uea000008icdeiac", "quantity" 25, "pricetagcodes" \["volume platform", "annual discount"] } ] } in change orders { "assetchanges" \[ { "changetype" "updatequantity", "assetnumber" "sub 00000279", "quantity" 10, "pricetagcodes" \["enterprise upgrade"] } ] } validation rules price tag validation status requirements active must be true publishstatus must be "published" current date must be within starttime and endtime range tier validation tiers must have non overlapping ranges startunit must be less than or equal to endunit tier numbers should be sequential all tiers must have consistent uomdimension pricing validation discountpercentage must be between 0 and 100 either discountpercentage or amount should be specified, not both chargemodel must be valid ("perunit", "flatfee") integration validation order integration price tags must be compatible with product price book entries quantity must fall within defined tier ranges terms must match term based price tag requirements change order integration price tags can be applied to quantity and renewal changes asset must be in active status new quantities must meet tier requirements error handling common error scenarios error type description resolution price tag not found price tag id or code not found verify price tag exists and is published price tag inactive price tag is not active check price tag status price tag expired price tag outside valid date range check starttime and endtime tier not applicable quantity doesn't match any tier verify quantity falls within defined ranges incompatible combination conflicting price tags applied review price tag compatibility rules error response format { "status" "failure", "errortype" "validation error", "errorcode" "price tag not found", "message" "price tag with code 'invalid code' not found or not published", "details" { "field" "pricetagcode", "value" "invalid code", "allowedvalues" \["volume platform", "annual discount"] } } api endpoints price tag retrieval endpoint method purpose /catalog/price tags get retrieve all published price tags /catalog/price tags/{code} get retrieve specific price tag by code query parameters get /catalog/price tags retrieve all published price tags no parameters required get /catalog/price tags/{ code } retrieve a specific price tag by its code the code is specified in the url path response structure \[ { "id" "a0x7z000007cckxeaw", "name" "enterprise volume discount", "code" "enterprise volume", "description" "volume discount for enterprise customers", "active" true, "publishstatus" "published", "pricetagtype" "quantity", "pricetype" "volume", "uomdimension" "user", "starttime" "2025 01 01t00 00 00z", "endtime" null, "lastpublishedbyid" "005xx000001sv6yaas", "lastpublisheddate" "2025 01 15t10 30 00z", "recordtype" "discountdimension", "pricetiers" \[ { "id" "a0yxx000001tdgreak", "name" "tier 1", "tiernumber" 1, "startunit" 1, "endunit" 9, "startunitdimension" "user", "endunitdimension" "user", "discountpercentage" 0 0, "chargemodel" "perunit" } ] } ] best practices price tag design clear naming use descriptive names that explain the discount purpose logical codes create memorable, consistent codes for api integration non overlapping tiers ensure tier ranges don't overlap to avoid conflicts reasonable discounts set appropriate discount percentages for business goals implementation patterns cache price tags price tags change infrequently, implement caching validate before application check price tag validity before using in orders handle gracefully implement fallbacks when price tags are unavailable monitor performance track price tag application impact on pricing user experience show savings display discount amounts prominently to customers explain tiers help customers understand quantity thresholds time sensitivity clearly communicate promotional expiration dates progressive disclosure show relevant price tags based on context this comprehensive reference provides the foundation for implementing effective price tag management with the nue self service api for specific implementation examples, see the getting started guide and advanced implementation patterns