Product Data Model

this comprehensive reference covers all product fields, data types, and relationships returned by the nue self service api product endpoints use this guide when implementing product catalog displays, pricing calculations, and order processing features important products are read only in the self service api this endpoint only retrieves published product data product creation and updates are managed through the nue platform interface core product identification fields essential fields that uniquely identify and classify products in api responses required fields field type description example notes id string unique product identifier (salesforce product id) "01te200000b8pyeiaj" system generated, always present name string display name of the product shown to customers "nue platform" always present in responses sku string stock keeping unit unique product identifier "nue platform" always present in responses product classification field type description valid values default recordtype string defines the type of product "product" , "service" , "bundle" "product" configurable boolean whether product has configuration options true , false false soldindependently boolean whether product can be purchased standalone true , false true status and visibility field type description valid values notes status string product lifecycle status "active" , "inactive" , "draft" only active products in self service lastpublisheddate datetime when product was last published "2025 03 12t10 30 00z" system managed lastpublishedbyid string id of user who last published product "005e200000jjwfqiar" salesforce user id product details and content fields for product descriptions, imagery, and content management field type description example max length description string short description for listings "manage customer revenue lifecycles" 255 chars longdescription string rich text description with html formatting "\<p>comprehensive platform for \</p>" no limit imageurl string url to product image for self service display "https //example com/products/image png" 255 chars pricing and revenue configuration critical fields for managing product pricing models and billing behavior price model configuration field type description valid values default pricemodel string how the product is priced "recurring" , "onetime" , "usage" , "crbd" "onetime" billingtiming string when billing occurs "in advance" , "in arrears" "in advance" defaultuomid string reference to default unit of measure "a0oe20000056n3viae" required subscription configuration field type description example notes autorenew boolean whether subscriptions auto renew true for recurring products defaultsubscriptionterm integer default subscription length 12 in uom units (months, years) defaultrenewalterm integer default renewal period length 12 in uom units evergreen boolean subscriptions have no fixed end date false continue until canceled free trial configuration field type description valid values example freetrialtype string unit type for free trials "days" , "months" , "years" "days" freetrialunit integer duration of the free trial positive integer 30 tax configuration fields for managing tax calculations and compliance field type description valid values example taxcode string tax classification identifier tax system specific codes "txcd 30070021" taxmode string how taxes are presented "taxexclusive" , "taxinclusive" "taxexclusive" taxcategory string vat or tax category code international tax codes optional bundle specific configuration fields that apply specifically to configurable bundle products field type description valid values example bundletemplate string bundle behavior model "basic" , "advanced" , "dynamicoptions" "advanced" showincludedproductoptions boolean display bundle components to customers true , false false referenceproductid string reference to another product salesforce product id optional product categorization fields for organizing and classifying products field type description valid values example productcategory string product classification "recurringservices" , "physicalgoods" , "customersupport" , etc "recurringservices" startdate datetime when product becomes available iso 8601 date format "2022 01 01" enddate datetime when product expires iso 8601 date format "2025 12 31" related data structures unit of measure (uom) the uom defines how a product is quantified and billed field type description valid values example name string display name of the unit human readable description "user/month" quantitydimension string what is counted "user" , "each" , "hour" , etc "user" termdimension string time period if applicable "month" , "year" , "quarter" , etc "month" decimalscale integer number of decimal places 0 10 0 roundingmode string how quantities are rounded "up" , "down" , "nearest" "up" price book entries price book entries represent specific pricing options for a product field type description example notes id string unique price book entry id "01uea00000f9jpqiav" salesforce id listprice decimal base price amount 99 00 required currencyisocode string currency code "usd" , "eur" , "gbp" iso 4217 format active boolean whether pricing is available true , false only active prices shown recommended boolean whether pricing is recommended true , false ui highlighting uom object unit of measure for this pricing uom object (see above) required pricingattributes array optional price segmentation \[{"name" "channel type", "value" "selfserve"}] for targeted pricing product features features describe capabilities or aspects of the product field type description example notes featurename string display name for the feature "premium features" user facing featureorder integer controls display order 0 lower numbers first feature object detailed feature information feature object contains metadata productoptions array options for this feature group array of options for bundle features product options (bundle components) for bundles, product options define the included components field type description valid values example id string unique product option id salesforce product option id "01oea00000g8kqriav" optionname string display name for this component human readable name "revenue dashboard" optiontype string type of relation "relatedproduct" , "linktobundlequantity" "relatedproduct" defaultquantity integer initial quantity selected positive integer 1 minquantity integer minimum allowed quantity 0 or positive integer 1 maxquantity integer maximum allowed quantity positive integer or null 10 quantityeditable boolean whether customers can change quantity true , false true required boolean whether this component is required true , false false bundled boolean included in bundle's base price true , false true recommended boolean whether recommended to customers true , false true product object full product data for component complete product object nested product price tags price tags define discounts and special pricing rules field type description valid values example pricetagtype string basis for the pricing rule "quantity" , "term" , etc "quantity" pricetype string how pricing varies "volume" , "tiered" , "ramp" "volume" uomdimension string which dimension this applies uom dimension "user" pricetiers array tier breakpoints and discounts array of tier objects see example price tier structure \[ { "chargemodel" "perunit", "discountpercentage" 10, "startunit" 0, "endunit" 100 } ] custom fields the nue self service api supports custom fields on the product object, allowing you to extend the standard data model custom field naming convention custom fields must follow the pattern fieldname c common custom field use cases use case example field example value purpose enhanced categorization productline c "enterprise" internal categorization technical information systemrequirements c "8gb ram minimum" technical specifications compliance information gdprcompliant c true regulatory compliance display attributes uibadge c "new" ui enhancement custom field access // accessing custom fields from product response fetch('https //api nue io/catalog/products?productid=01te200000b8pyeiaj') then(response => response json()) then(products => { const product = products\[0]; // access custom fields if (product customfields) { console log('product line ', product customfields productline c); console log('system requirements ', product customfields systemrequirements c); console log('gdpr compliant ', product customfields gdprcompliant c); console log('ui badge ', product customfields uibadge c); } }); field characteristics and constraints always present fields since products are pre validated before publishing, certain fields are guaranteed to be present id always present, unique salesforce product id name always present and non empty sku always present and unique across all products status always "active" (inactive products not returned) publishstatus always "published" (unpublished products not returned) optional fields these fields may be null or absent depending on product configuration description may be null for products without descriptions imageurl may be null if no product image is configured enddate may be null for products without expiration customfields may be empty object if no custom fields defined business logic characteristics configurable only true for bundle products with productoptions bundletemplate only present when configurable is true autorenew only relevant for products with pricemodel "recurring" productoptions only present for configurable bundle products api response examples standard product response { "id" "01te200000b8pyeiaj", "name" "professional analytics", "sku" "prof analytics v1", "recordtype" "product", "description" "advanced analytics and reporting platform", "longdescription" "\<p>comprehensive analytics solution with real time dashboards and custom reporting capabilities \</p>", "status" "active", "publishstatus" "published", "configurable" false, "soldindependently" true, "pricemodel" "recurring", "billingtiming" "in advance", "autorenew" true, "defaultsubscriptionterm" 12, "startdate" "2024 01 01", "imageurl" "https //example com/images/analytics png", "pricebookentries" \[ { "id" "01uea00000f9jpqiav", "listprice" 99 00, "currencyisocode" "usd", "active" true, "recommended" true, "uom" { "name" "user/month", "quantitydimension" "user", "termdimension" "month", "decimalscale" 0, "roundingmode" "up" } } ], "productfeatures" \[ { "featurename" "core analytics", "featureorder" 0, "feature" { "id" "01fea00000h7lrsiav", "name" "real time dashboards", "description" "interactive dashboards with live data" } } ], "customfields" { "productline c" "analytics", "targetmarket c" "smb" } } bundle product response { "id" "01te200000b8pyeiak", "name" "enterprise suite", "sku" "ent suite v1", "recordtype" "bundle", "description" "complete enterprise platform with all modules", "status" "active", "publishstatus" "published", "configurable" true, "bundletemplate" "advanced", "showincludedproductoptions" false, "pricemodel" "recurring", "pricebookentries" \[ { "id" "01uea00000f9jpriav", "listprice" 299 00, "currencyisocode" "usd", "active" true, "recommended" true, "uom" { "name" "user/month", "quantitydimension" "user", "termdimension" "month" } } ], "productoptions" \[ { "id" "01oea00000g8kqriav", "optionname" "analytics module", "optiontype" "relatedproduct", "defaultquantity" 1, "minquantity" 1, "quantityeditable" true, "required" true, "bundled" true, "recommended" true, "product" { "id" "01te200000b8pyeiaj", "name" "professional analytics", "sku" "prof analytics v1" } } ] } error responses product not found example { "error" "product not found", "message" "product with id '01te200000b8pyeiaj' not found or not published" } invalid product id format { "error" "invalid product id", "message" "product id must be a valid salesforce id format" } common error codes 400 bad request invalid product id format or malformed request 401 unauthorized invalid or missing api key 404 not found product id doesn't exist or not published 429 rate limited too many requests 500 server error internal system error note since products are read only, you won't encounter validation errors related to product data creation or updates best practices summary always use salesforce id format for product lookups cache product catalog data since products don't change frequently check publishstatus and status for product availability (both will always be active/published) use pricebookentries array for all pricing calculations implement proper bundle handling with productoptions for configurable products store product ids as primary identifiers for order creation consider uom implications for quantity calculations and billing displays parse custom fields for business specific display requirements handle price segmentation using pricingattributes when present monitor product availability using start and end dates implement graceful fallbacks for optional fields that may be null use proper error handling for product not found scenarios remember products are read only in the self service api use this data for catalog displays, pricing calculations, and order processing, but manage product creation and updates through the nue platform interface this comprehensive reference provides the complete specification for understanding product data in the nue self service api use it alongside other product guides for complete implementation guidance