Product Data Model

30 min

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"

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/01tE200000B8pYeIAJ')
  .then(response => response.json())
  .then(product => {
    // 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.