Price Tag Data Reference

30 min

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	Lower bound of the tier range, exclusive	0
startUnitDimension	String	Unit type for start range	"User"
endUnit	Number	Upper bound of the tier range, inclusive	10
endUnitDimension	String	Unit type for end range	"User"

A tier matches when startUnit < quantity <= endUnit. Consecutive tiers therefore share a boundary: set each tier's startUnit to the previous tier's endUnit, and start the first tier at 0 so that a quantity of 1 is covered. A quantity that falls outside every tier receives no adjustment from the tag, and no error is returned.

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": 0,
      "endUnit": 10,
      "discountPercentage": 0.0,
      "chargeModel": "PerUnit"
    },
    {
      "tierNumber": 2,
      "startUnit": 10,
      "endUnit": 50,
      "discountPercentage": 10.0,
      "chargeModel": "PerUnit"
    },
    {
      "tierNumber": 3,
      "startUnit": 50,
      "endUnit": 1000,
      "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:

Price tags are not supported on change orders. assetChanges entries do not accept priceTagIds or priceTagCodes.

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 are not supported on change order asset changes (assetChanges)

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.