---
title: Getting Started with Price Tags
slug: getting-started-with-price-tags
docTags: 
createdAt: 2026-02-13T04:24:47.243Z
---

This guide walks you through the essential price tag operations in the Nue Self-Service API. You'll learn how to retrieve price tag information, understand pricing structures, and implement dynamic pricing for your applications.

## Prerequisites

Before you begin, ensure you have:

- A valid Nue API key
- Access to the Nue Lifecycle Manager API
- Basic understanding of REST APIs and JSON
- Published price tags in your Nue environment (only published price tags appear in the API)

## Authentication

All price tag operations require authentication using your Nue API key in the `nue-api-key` header:

```javascript
const myHeaders = new Headers();
myHeaders.append("nue-api-key", "YOUR_API_KEY_HERE");
myHeaders.append("Content-Type", "application/json");
```

## Understanding Price Tags

Price tags are powerful pricing rules that modify base product prices through:

- **Volume discounts** based on quantity purchased
- **Term discounts** based on subscription length
- **Tiered pricing** with different rates at different levels
- **Time-limited promotions** with start and end dates

## Retrieving Price Tag Information

The price tag API allows you to fetch all published price tags or specific tags by ID. To learn more about publishing price tags, please read [here](https://api-docs.nue.io/publishing-price-tags).

### Fetch All Price Tags

**Try it now:** [Fetch price tags API →](https://api-docs.nue.io/fetch-price-tag)

```javascript
const myHeaders = new Headers();
myHeaders.append("nue-api-key", "YOUR_API_KEY_HERE");
myHeaders.append("Content-Type", "application/json");

const requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("https://api.nue.io/catalog/price-tags", requestOptions)
  .then(response => response.json())
  .then(result => {
    console.log('Price tags loaded:', result);
    
    // Display each price tag
    result.forEach(priceTag => {
      console.log(`Price Tag: ${priceTag.name}`);
      console.log(`Code: ${priceTag.code}`);
      console.log(`Type: ${priceTag.priceTagType}`);
      console.log(`Active: ${priceTag.active}`);
      console.log(`Tiers: ${priceTag.priceTiers.length}`);
      console.log('---');
    });
  })
  .catch(error => console.log('error', error));
```

### Fetch Specific Price Tag

**Try it now:** [Fetch price tags API →](https://api-docs.nue.io/fetch-price-tag)

```javascript
const myHeaders = new Headers();
myHeaders.append("nue-api-key", "YOUR_API_KEY_HERE");
myHeaders.append("Content-Type", "application/json");

// Fetch a specific price tag by code
const priceTagCode = "FFT";

const requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch(`https://api.nue.io/catalog/price-tags/${priceTagCode}`, requestOptions)
  .then(response => response.json())
  .then(result => {
    console.log('Price tag details:', result);
    
    const priceTag = result[0]; // API returns array even for single price tag
    if (priceTag) {
      console.log(`Price Tag Name: ${priceTag.name}`);
      console.log(`Code: ${priceTag.code}`);
      console.log(`Description: ${priceTag.description}`);
      console.log(`Price Type: ${priceTag.priceType}`);
      console.log(`Publish Status: ${priceTag.publishStatus}`);
      
      // Display pricing tiers
      if (priceTag.priceTiers && priceTag.priceTiers.length > 0) {
        console.log('Pricing Tiers:');
        priceTag.priceTiers.forEach((tier, index) => {
          console.log(`  Tier ${index + 1}:`);
          console.log(`    Range: ${tier.startUnit || 0} - ${tier.endUnit || '∞'}`);
          console.log(`    Charge Model: ${tier.chargeModel}`);
          
          if (tier.discountPercentage) {
            console.log(`    Discount: ${tier.discountPercentage}%`);
          }
          if (tier.amount) {
            console.log(`    Amount: $${tier.amount}`);
          }
        });
      }
    }
  })
  .catch(error => console.log('error', error));
```

## Understanding Price Tag Structure

Price tags in the Nue catalog have a comprehensive data structure. Here's what you'll typically work with:

### Core Price Tag Fields

- `id`: Unique price tag identifier (Salesforce Price Tag ID)
- `name`: Display name for the price tag
- `code`: Unique code for API references and promotions (used for fetching individual price tags)
- `description`: Detailed explanation of the pricing rule
- `active`: Whether the price tag is currently active
- `publishStatus`: Whether the price tag is published for self-service (only "Published" price tags appear in API responses)

### Pricing Configuration

- `priceTagType`: "Quantity" or "Term" based pricing
- `priceType`: "Volume", "Tiered", or "Ramp" pricing model
- `uomDimension`: Unit of measure (User, License, etc.)
- `startTime`: When the pricing becomes effective
- `endTime`: When the pricing expires (optional)

### Price Tiers

Each price tag contains `priceTiers` that define specific pricing rules:

- `chargeModel`: "PerUnit" or "FlatFee"
- `startUnit`: Beginning of tier range
- `endUnit`: End of tier range
- `amount`: Price amount for price tags
- `discountPercentage`: Percentage discount for discount tags

## Building a Price Tag Display

Here's a practical example of building a price tag display for your application:

```javascript
async function buildPriceTagCatalog() {
  const myHeaders = new Headers();
  myHeaders.append("nue-api-key", "YOUR_API_KEY_HERE");
  myHeaders.append("Content-Type", "application/json");

  try {
    const response = await fetch("https://api.nue.io/catalog/price-tags", {
      method: 'GET',
      headers: myHeaders
    });
    
    const priceTags = await response.json();
    
    // Note: Only published price tags are returned by the API
    // Filter only active price tags (publishStatus will always be 'Published')
    const activePriceTags = priceTags.filter(tag => tag.active);
    
    // Organize price tags by type
    const organizedTags = {
      volume: [],
      term: [],
      promotional: []
    };
    
    activePriceTags.forEach(tag => {
      const tagInfo = {
        id: tag.id,
        name: tag.name,
        code: tag.code,
        description: tag.description,
        type: tag.priceTagType,
        priceType: tag.priceType,
        uomDimension: tag.uomDimension,
        isTimeLimited: tag.endTime ? true : false,
        expiryDate: tag.endTime,
        tiers: tag.priceTiers.map(tier => ({
          range: `${tier.startUnit || 0} - ${tier.endUnit || '∞'}`,
          chargeModel: tier.chargeModel,
          discount: tier.discountPercentage || 0,
          amount: tier.amount || 0
        }))
      };
      
      // Categorize by type
      if (tag.priceTagType === 'Quantity') {
        organizedTags.volume.push(tagInfo);
      } else if (tag.priceTagType === 'Term') {
        organizedTags.term.push(tagInfo);
      }
      
      // Check if it's promotional (time-limited)
      if (tag.endTime) {
        organizedTags.promotional.push(tagInfo);
      }
    });
    
    console.log('Price Tag Catalog ready for display:', organizedTags);
    return organizedTags;
    
  } catch (error) {
    console.error('Failed to load price tag catalog:', error);
    throw error;
  }
}

// Usage
buildPriceTagCatalog()
  .then(catalog => {
    // Render your price tag catalog UI
    console.log('\n📊 Volume-Based Price Tags:');
    catalog.volume.forEach(tag => {
      console.log(`🏷️  ${tag.name} (${tag.code})`);
      console.log(`   ${tag.description}`);
      console.log(`   Unit: ${tag.uomDimension}`);
      
      tag.tiers.forEach((tier, index) => {
        console.log(`   Tier ${index + 1}: ${tier.range} units`);
        if (tier.discount > 0) {
          console.log(`     Discount: ${tier.discount}%`);
        }
        if (tier.amount > 0) {
          console.log(`     Price: $${tier.amount}`);
        }
      });
      console.log('');
    });
    
    console.log('\n📅 Term-Based Price Tags:');
    catalog.term.forEach(tag => {
      console.log(`🏷️  ${tag.name} (${tag.code})`);
      console.log(`   ${tag.description}`);
      
      tag.tiers.forEach((tier, index) => {
        console.log(`   Tier ${index + 1}: ${tier.range}`);
        if (tier.discount > 0) {
          console.log(`     Discount: ${tier.discount}%`);
        }
      });
      console.log('');
    });
    
    if (catalog.promotional.length > 0) {
      console.log('\n🎉 Promotional Price Tags:');
      catalog.promotional.forEach(tag => {
        console.log(`🏷️  ${tag.name} (${tag.code})`);
        console.log(`   ${tag.description}`);
        console.log(`   Expires: ${tag.expiryDate}`);
        console.log('');
      });
    }
  });
```

## Filtering and Searching Price Tags

For better user experience, you'll want to implement filtering and search:

```javascript
function filterPriceTags(priceTags, filters = {}) {
  return priceTags.filter(tag => {
    // Filter by active status
    if (filters.activeOnly && !tag.active) return false;
    
    // Note: publishStatus will always be 'Published' since only published tags are returned
    // No need to filter by publication status
    
    // Filter by price tag type
    if (filters.type && tag.priceTagType !== filters.type) return false;
    
    // Filter by code search
    if (filters.code) {
      const searchTerm = filters.code.toLowerCase();
      if (!tag.code.toLowerCase().includes(searchTerm)) return false;
    }
    
    // Filter by name/description search
    if (filters.search) {
      const searchTerm = filters.search.toLowerCase();
      const matchesName = tag.name.toLowerCase().includes(searchTerm);
      const matchesDescription = tag.description?.toLowerCase().includes(searchTerm);
      if (!matchesName && !matchesDescription) return false;
    }
    
    // Filter by time validity
    if (filters.validNow) {
      const now = new Date();
      const startTime = tag.startTime ? new Date(tag.startTime) : new Date('1970-01-01');
      const endTime = tag.endTime ? new Date(tag.endTime) : new Date('2099-12-31');
      
      if (now < startTime || now > endTime) return false;
    }
    
    return true;
  });
}

// Usage example
async function searchPriceTags() {
  const allTags = await buildPriceTagCatalog();
  const flatTags = [...allTags.volume, ...allTags.term, ...allTags.promotional];
  
  // Search for volume discounts currently valid
  const volumeDiscounts = filterPriceTags(flatTags, {
    type: 'Quantity',
    validNow: true,
    activeOnly: true
  });
  
  console.log(`Found ${volumeDiscounts.length} active volume discounts`);
  
  // Search for price tags by code
  const specificTag = filterPriceTags(flatTags, {
    code: 'ENTERPRISE'
  });
  
  console.log(`Found ${specificTag.length} tags matching 'ENTERPRISE'`);
}
```

## Calculating Price Impact

Understanding how price tags affect final pricing is crucial for building quotes:

```javascript
function calculatePriceImpact(basePrice, quantity, priceTag) {
  if (!priceTag || !priceTag.tiers || priceTag.tiers.length === 0) {
    return {
      originalPrice: basePrice * quantity,
      finalPrice: basePrice * quantity,
      savings: 0,
      effectiveTier: null
    };
  }
  
  // Find applicable tier based on quantity
  let applicableTier = null;
  
  for (const tier of priceTag.tiers) {
    const tierStart = tier.startUnit || 0;
    const tierEnd = tier.endUnit || Infinity;
    
    if (quantity >= tierStart && quantity <= tierEnd) {
      applicableTier = tier;
      break;
    }
  }
  
  if (!applicableTier) {
    return {
      originalPrice: basePrice * quantity,
      finalPrice: basePrice * quantity,
      savings: 0,
      effectiveTier: null
    };
  }
  
  let finalPrice;
  const originalPrice = basePrice * quantity;
  
  if (priceTag.priceType === 'Volume') {
    // Volume pricing: all units get the same rate
    if (applicableTier.discountPercentage) {
      const discountMultiplier = 1 - (applicableTier.discountPercentage / 100);
      finalPrice = originalPrice * discountMultiplier;
    } else if (applicableTier.amount) {
      finalPrice = applicableTier.amount * quantity;
    } else {
      finalPrice = originalPrice;
    }
  } else if (priceTag.priceType === 'Tiered') {
    // Tiered pricing: different rates for different portions
    finalPrice = 0;
    let remainingQuantity = quantity;
    
    for (const tier of priceTag.tiers.sort((a, b) => a.startUnit - b.startUnit)) {
      const tierStart = tier.startUnit || 0;
      const tierEnd = tier.endUnit || Infinity;
      
      if (remainingQuantity <= 0) break;
      
      const tierQuantity = Math.min(remainingQuantity, tierEnd - tierStart);
      
      if (tier.discountPercentage) {
        const discountMultiplier = 1 - (tier.discountPercentage / 100);
        finalPrice += (basePrice * tierQuantity * discountMultiplier);
      } else if (tier.amount) {
        finalPrice += (tier.amount * tierQuantity);
      } else {
        finalPrice += (basePrice * tierQuantity);
      }
      
      remainingQuantity -= tierQuantity;
    }
  }
  
  return {
    originalPrice: originalPrice,
    finalPrice: finalPrice,
    savings: originalPrice - finalPrice,
    savingsPercentage: ((originalPrice - finalPrice) / originalPrice) * 100,
    effectiveTier: applicableTier
  };
}

// Usage example
async function demonstratePricing() {
  const priceTags = await buildPriceTagCatalog();
  const volumeTag = priceTags.volume[0]; // Get first volume discount
  
  if (volumeTag) {
    const scenarios = [
      { quantity: 5, basePrice: 100 },
      { quantity: 25, basePrice: 100 },
      { quantity: 100, basePrice: 100 }
    ];
    
    console.log(`\n💰 Pricing with ${volumeTag.name}:`);
    
    scenarios.forEach(scenario => {
      const pricing = calculatePriceImpact(scenario.basePrice, scenario.quantity, volumeTag);
      
      console.log(`\n📊 ${scenario.quantity} units at $${scenario.basePrice} base price:`);
      console.log(`   Original: $${pricing.originalPrice.toFixed(2)}`);
      console.log(`   Final: $${pricing.finalPrice.toFixed(2)}`);
      console.log(`   Savings: $${pricing.savings.toFixed(2)} (${pricing.savingsPercentage.toFixed(1)}%)`);
      
      if (pricing.effectiveTier) {
        console.log(`   Applied Tier: ${pricing.effectiveTier.range}`);
      }
    });
  }
}

// Run the demonstration
demonstratePricing();
```

## Common Patterns and Best Practices

### 1. Error Handling

Always implement proper error handling for your price tag operations:

```javascript
async function safePriceTagFetch(priceTagCode = null) {
  try {
    const url = priceTagCode 
      ? `https://api.nue.io/catalog/price-tags/${priceTagCode}`
      : 'https://api.nue.io/catalog/price-tags';
      
    const response = await fetch(url, {
      method: 'GET',
      headers: myHeaders
    });
    
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    
    const priceTags = await response.json();
    
    if (priceTagCode && priceTags.length === 0) {
      throw new Error(`Price tag with code ${priceTagCode} not found or not published`);
    }
    
    return priceTags;
    
  } catch (error) {
    console.error('Price tag fetch error:', error);
    
    // Return empty array for graceful degradation
    return [];
  }
}
```

### 2. Caching Price Tags

Price tags don't change frequently, so implement caching:

```javascript
class PriceTagCache {
  constructor(ttlMinutes = 60) {
    this.cache = new Map();
    this.ttl = ttlMinutes * 60 * 1000; // Convert to milliseconds
  }
  
  set(key, data) {
    this.cache.set(key, {
      data,
      timestamp: Date.now()
    });
  }
  
  get(key) {
    const cached = this.cache.get(key);
    if (!cached) return null;
    
    // Check if cache has expired
    if (Date.now() - cached.timestamp > this.ttl) {
      this.cache.delete(key);
      return null;
    }
    
    return cached.data;
  }
  
  async getPriceTags() {
    const cached = this.get('all-price-tags');
    if (cached) {
      console.log('Using cached price tag data');
      return cached;
    }
    
    console.log('Fetching fresh price tag data');
    const priceTags = await safePriceTagFetch();
    this.set('all-price-tags', priceTags);
    return priceTags;
  }
}

// Usage
const priceTagCache = new PriceTagCache(60); // 60-minute cache
const priceTags = await priceTagCache.getPriceTags();
```

### 3. Price Tag Validation

Validate price tags before applying them:

```javascript
function validatePriceTag(priceTag) {
  const now = new Date();
  
  // Check if active
  if (!priceTag.active) {
    return { valid: false, reason: 'Price tag is not active' };
  }
  
  // Note: publishStatus will always be 'Published' since only published tags are returned by the API
  // No need to check publication status
  
  // Check time validity
  if (priceTag.startTime && new Date(priceTag.startTime) > now) {
    return { valid: false, reason: 'Price tag has not started yet' };
  }
  
  if (priceTag.endTime && new Date(priceTag.endTime) < now) {
    return { valid: false, reason: 'Price tag has expired' };
  }
  
  return { valid: true, reason: 'Price tag is valid' };
}
```

## Next Steps

Now that you understand basic price tag operations, you can:

- **Learn about pricing strategies** in the Key Considerations guide
- **Understand price tag types** for implementing specific pricing models
- **Explore the data model** to understand all available fields
- **Build dynamic pricing** with real-time price calculations

Move on to **Key Considerations for Price Tags** to learn about pricing strategies and implementation best practices, or **Price Tag Types** to understand different pricing models you can implement.