Fetching Entitlements

14 min

Retrieve entitlement data using the Nue Lifecycle Management API. Entitlements define customer access rights and usage limits based on their active assets and subscriptions.

Prerequisites

Before you begin, ensure you have:

A valid Nue API key with entitlement read permissions

Customer IDs or entitlement numbers for the entitlements you want to retrieve

Basic understanding of REST APIs and JSON

Familiarity with entitlement concepts and usage tracking

Authentication

All entitlement retrieval operations require authentication using your Nue API key in the nue-api-key header:

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

REST Endpoints

The Nue API provides REST endpoints for flexible entitlement data access:

// Global entitlement endpoints
GET https://api.nue.io/entitlements                        // Get all entitlements with pagination
GET https://api.nue.io/entitlements/{entitlementNumber}    // Get a specific entitlement by number

// Customer-scoped entitlement endpoints  
GET https://api.nue.io/customers/{customerId}/entitlements                        // Get entitlements for a customer
GET https://api.nue.io/customers/{customerId}/entitlements/{entitlementNumber}    // Get a specific entitlement for a customer

Filtering

Entitlement endpoints support filtering using query parameters:

Query Parameters:

customerIds - Array of customer IDs to filter by

entitlementNumber - Specific entitlement number to search for

status - Filter by status: Active, Expired, Suspended, Draft

history - Include entitlement history (true/false)

includes - Include related data (e.g., product, pricetags)

page - Page number for pagination

limit - Number of results per page

Basic Entitlement Retrieval

Try it now: Fetch Entitlements →

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

// Fetch all entitlements for a customer
const customerIds = ["d2e04653-ae90-49df-a986-134cf64f6d03"];
const encodedCustomerIds = encodeURIComponent(JSON.stringify(customerIds));

fetch(`https://api.nue.io/entitlements?customerIds=${encodedCustomerIds}`, {
  method: 'GET',
  headers: myHeaders
})
.then(response => response.json())
.then(result => {
  if (result.status === 'SUCCESS' && result.data) {
    console.log(`Found ${result.data.length} entitlements`);
    
    result.data.forEach(entitlement => {
      console.log(`${entitlement.entitlementNumber}: ${entitlement.status}`);
      console.log(`Product: ${entitlement.productId}`);
      console.log(`Usage: ${entitlement.usedQuantity || 0}/${entitlement.quantity}`);
      console.log(`Period: ${entitlement.startDate} to ${entitlement.endDate}`);
    });
  }
})
.catch(error => console.log('Error:', error));

Fetch Entitlements for Multiple Customers

// Fetch entitlements for multiple customers
const customerIds = [
  "d2e04653-ae90-49df-a986-134cf64f6d03",
  "cc5e1f0f-5e14-48cc-ab98-9e5b191aa46f"
];

const encodedCustomerIds = encodeURIComponent(JSON.stringify(customerIds));

fetch(`https://api.nue.io/entitlements?customerIds=${encodedCustomerIds}`, {
  method: 'GET',
  headers: myHeaders
})
.then(response => response.json())
.then(result => {
  if (result.status === 'SUCCESS') {
    result.data.forEach(entitlement => {
      console.log(`${entitlement.entitlementNumber}: ${entitlement.status}`);
      console.log(`Customer: ${entitlement.customerId}`);
    });
  }
})
.catch(error => console.log('Error:', error));

Filtered Entitlement Retrieval

Fetch Active Entitlements Only

Filter entitlements by their current status:

const customerIds = ["d2e04653-ae90-49df-a986-134cf64f6d03"];
const encodedCustomerIds = encodeURIComponent(JSON.stringify(customerIds));

// Fetch only active entitlements
const url = `https://api.nue.io/entitlements?customerIds=${encodedCustomerIds}&status=active`;

fetch(url, {
  method: 'GET',
  headers: myHeaders
})
.then(response => response.json())
.then(result => {
  if (result.status === 'SUCCESS') {
    console.log('🟢 Active Entitlements Retrieved');
    
    if (result.data && result.data.length > 0) {
      result.data.forEach(entitlement => {
        console.log(`\n📋 ${entitlement.name || entitlement.entitlementNumber}`);
        console.log(`   Status: ${entitlement.status}`);
        console.log(`   Product: ${entitlement.productId}`);
        console.log(`   Capacity: ${entitlement.quantity}`);
        console.log(`   Used: ${entitlement.usedQuantity || 0}`);
        console.log(`   Available: ${(entitlement.quantity || 0) - (entitlement.usedQuantity || 0)}`);
        console.log(`   Valid Period: ${entitlement.startDate} to ${entitlement.endDate}`);
        
        // Usage analysis
        const usagePercent = entitlement.quantity > 0 ? 
          ((entitlement.usedQuantity || 0) / entitlement.quantity * 100) : 0;
        
        console.log(`   Usage Rate: ${usagePercent.toFixed(1)}%`);
        
        // Capacity planning insights
        if (usagePercent >= 90) {
          console.log(`   🚨 Critical: Near capacity limit`);
        } else if (usagePercent >= 75) {
          console.log(`   ⚠️  Warning: High usage detected`);
        } else if (usagePercent >= 50) {
          console.log(`   📊 Moderate: Good utilization`);
        } else {
          console.log(`   ✅ Healthy: Low utilization`);
        }
        
        // Time-based insights
        if (entitlement.endDate) {
          const endDate = new Date(entitlement.endDate);
          const now = new Date();
          const daysRemaining = Math.ceil((endDate - now) / (1000 * 60 * 60 * 24));
          
          if (daysRemaining <= 30) {
            console.log(`   🔔 Renewal needed: Expires in ${daysRemaining} days`);
          }
        }
      });
    } else {
      console.log('No active entitlements found for this customer');
    }
  }
})
.catch(error => console.log('Error:', error));

Fetch Specific Entitlement by Number

Retrieve a specific entitlement using its entitlement number:

const entitlementNumber = "ENT-001234";
const encodedEntitlementNumber = encodeURIComponent(entitlementNumber);

fetch(`https://api.nue.io/entitlements?entitlementNumber=${encodedEntitlementNumber}`, {
  method: 'GET',
  headers: myHeaders
})
.then(response => response.json())
.then(result => {
  if (result.status === 'SUCCESS' && result.data.length > 0) {
    const entitlement = result.data[0];
    
    console.log('🎯 Specific Entitlement Retrieved');
    console.log(`Entitlement Number: ${entitlement.entitlementNumber}`);
    console.log(`Name: ${entitlement.name}`);
    console.log(`Status: ${entitlement.status}`);
    console.log(`Customer: ${entitlement.customerId}`);
    console.log(`Product: ${entitlement.productId}`);
    console.log(`Total Quantity: ${entitlement.quantity}`);
    console.log(`Used Quantity: ${entitlement.usedQuantity || 0}`);
    console.log(`Available: ${(entitlement.quantity || 0) - (entitlement.usedQuantity || 0)}`);
    console.log(`Start Date: ${entitlement.startDate}`);
    console.log(`End Date: ${entitlement.endDate}`);
    console.log(`Version: ${entitlement.entitlementVersion}`);
    console.log(`Billing Account: ${entitlement.billingAccountId}`);
    
    // Detailed usage analysis
    if (entitlement.quantity > 0) {
      const usagePercent = ((entitlement.usedQuantity || 0) / entitlement.quantity * 100);
      const remaining = entitlement.quantity - (entitlement.usedQuantity || 0);
      
      console.log(`\n📊 Usage Analysis:`);
      console.log(`   Utilization: ${usagePercent.toFixed(1)}%`);
      console.log(`   Remaining Capacity: ${remaining} units`);
      
      // Usage velocity (if we had historical data)
      if (entitlement.startDate) {
        const startDate = new Date(entitlement.startDate);
        const now = new Date();
        const daysActive = Math.ceil((now - startDate) / (1000 * 60 * 60 * 24));
        
        if (daysActive > 0 && entitlement.usedQuantity > 0) {
          const dailyUsage = entitlement.usedQuantity / daysActive;
          const daysToDepletion = remaining / dailyUsage;
          
          console.log(`   Daily Usage Rate: ${dailyUsage.toFixed(2)} units/day`);
          
          if (daysToDepletion > 0) {
            console.log(`   Estimated Depletion: ${Math.ceil(daysToDepletion)} days`);
            
            if (daysToDepletion <= 30) {
              console.log(`   🚨 Action Required: Will exceed capacity soon`);
            }
          }
        }
      }
    }
    
    // Time remaining analysis
    if (entitlement.endDate) {
      const endDate = new Date(entitlement.endDate);
      const now = new Date();
      const daysRemaining = Math.ceil((endDate - now) / (1000 * 60 * 60 * 24));
      
      console.log(`\n⏰ Time Analysis:`);
      if (daysRemaining > 0) {
        console.log(`   Days Remaining: ${daysRemaining}`);
        console.log(`   Expiration Date: ${entitlement.endDate}`);
        
        if (daysRemaining <= 7) {
          console.log(`   🚨 Critical: Expires within 1 week`);
        } else if (daysRemaining <= 30) {
          console.log(`   ⚠️  Warning: Expires within 1 month`);
        } else if (daysRemaining <= 90) {
          console.log(`   📅 Notice: Expires within 3 months`);
        }
      } else {
        console.log(`   ❌ Expired: ${Math.abs(daysRemaining)} days ago`);
      }
    }
  } else {
    console.log('Entitlement not found');
  }
})
.catch(error => console.log('Error:', error));

Fetch Entitlements with Product Details

Include product information in the entitlement response:

const customerIds = ["d2e04653-ae90-49df-a986-134cf64f6d03"];
const encodedIds = encodeURIComponent(JSON.stringify(customerIds));

// Include product details in the response
const urlWithProducts = `https://api.nue.io/entitlements?customerIds=${encodedIds}&includes=product`;

fetch(urlWithProducts, {
  method: 'GET',
  headers: myHeaders
})
.then(response => response.json())
.then(result => {
  if (result.status === 'SUCCESS' && result.data) {
    result.data.forEach(entitlement => {
      console.log(`\n📋 Entitlement: ${entitlement.entitlementNumber}`);
      console.log(`   Status: ${entitlement.status}`);
      console.log(`   Usage: ${entitlement.usedQuantity || 0}/${entitlement.quantity}`);
      
      // Display product information if included
      if (entitlement.product) {
        console.log(`\n   📦 Product Details:`);
        console.log(`     Name: ${entitlement.product.name}`);
        console.log(`     SKU: ${entitlement.product.sku}`);
        console.log(`     ID: ${entitlement.product.id}`);
        console.log(`     Description: ${entitlement.product.description || 'No description'}`);
      }
      
      // Display pricing tags if included
      if (entitlement.priceTags && entitlement.priceTags.length > 0) {
        console.log(`\n   🏷️  Applied Price Tags:`);
        entitlement.priceTags.forEach(tag => {
          console.log(`     • ${tag.name} (${tag.code})`);
        });
      }
      
      // Usage insights with product context
      if (entitlement.product && entitlement.quantity > 0) {
        const usagePercent = ((entitlement.usedQuantity || 0) / entitlement.quantity * 100);
        console.log(`\n   📊 ${entitlement.product.name} Usage:`);
        console.log(`     Current: ${usagePercent.toFixed(1)}% utilized`);
        console.log(`     Available: ${entitlement.quantity - (entitlement.usedQuantity || 0)} units`);
      }
    });
  }
})
.catch(error => console.log('Error:', error));

Fetch with All Available Data

Include all available related data:

// Include all available data types
const urlWithAll = `https://api.nue.io/entitlements?customerIds=${encodedIds}&includes=product,pricetags`;

fetch(urlWithAll, {
  method: 'GET',
  headers: myHeaders
})
.then(response => response.json())
.then(result => {
  if (result.status === 'SUCCESS' && result.data) {
    result.data.forEach(entitlement => {
      console.log(`\n🎯 Complete Entitlement Details: ${entitlement.entitlementNumber}`);
      console.log(`   Name: ${entitlement.name}`);
      console.log(`   Status: ${entitlement.status}`);
      console.log(`   Customer: ${entitlement.customerId}`);
      
      // Entitlement Capacity
      console.log(`\n   📊 Capacity & Usage:`);
      console.log(`     Total Quantity: ${entitlement.quantity}`);
      console.log(`     Used Quantity: ${entitlement.usedQuantity || 0}`);
      console.log(`     Available: ${(entitlement.quantity || 0) - (entitlement.usedQuantity || 0)}`);
      
      const usagePercent = entitlement.quantity > 0 ? 
        ((entitlement.usedQuantity || 0) / entitlement.quantity * 100) : 0;
      console.log(`     Utilization: ${usagePercent.toFixed(1)}%`);
      
      // Product Details
      if (entitlement.product) {
        console.log(`\n   📦 Product:`);
        console.log(`     ${entitlement.product.name} (${entitlement.product.sku})`);
        console.log(`     ID: ${entitlement.product.id}`);
        if (entitlement.product.description) {
          console.log(`     Description: ${entitlement.product.description}`);
        }
      }
      
      // Time Period
      console.log(`\n   📅 Validity Period:`);
      console.log(`     Start: ${entitlement.startDate}`);
      console.log(`     End: ${entitlement.endDate}`);
      
      // Time analysis
      if (entitlement.endDate) {
        const endDate = new Date(entitlement.endDate);
        const now = new Date();
        const daysRemaining = Math.ceil((endDate - now) / (1000 * 60 * 60 * 24));
        
        if (daysRemaining > 0) {
          console.log(`     Days Remaining: ${daysRemaining}`);
        } else {
          console.log(`     Status: Expired ${Math.abs(daysRemaining)} days ago`);
        }
      }
      
      // Billing Information
      console.log(`\n   🧾 Billing:`);
      console.log(`     Billing Account: ${entitlement.billingAccountId}`);
      console.log(`     Order Product: ${entitlement.orderProductId}`);
      
      // Versioning
      console.log(`\n   🔄 Version Control:`);
      console.log(`     Version: ${entitlement.entitlementVersion}`);
      console.log(`     Created: ${entitlement.createdDate}`);
      console.log(`     Last Modified: ${entitlement.lastModifiedDate}`);
      
      // Price Tags
      if (entitlement.priceTags && entitlement.priceTags.length > 0) {
        console.log(`\n   🏷️  Price Tags (${entitlement.priceTags.length}):`);
        entitlement.priceTags.forEach(tag => {
          console.log(`     • ${tag.name} (${tag.code})`);
        });
      }
    });
  }
})
.catch(error => console.log('Error:', error));

Entitlement History and Compliance Tracking

Fetch Entitlement History

Retrieve historical versions of a specific entitlement for compliance and audit:

async function fetchEntitlementHistory(entitlementNumber) {
  const encodedEntitlementNumber = encodeURIComponent(entitlementNumber);
  const url = `https://api.nue.io/entitlements?entitlementNumber=${encodedEntitlementNumber}&history=true`;
  
  try {
    const response = await fetch(url, {
      method: 'GET',
      headers: myHeaders
    });
    
    const result = await response.json();
    
    if (result.status === 'SUCCESS' && result.data.length > 0) {
      console.log(`📜 Entitlement History for ${entitlementNumber}`);
      console.log('='.repeat(60));
      
      // Sort by version to show evolution
      const sortedHistory = result.data.sort((a, b) => a.entitlementVersion - b.entitlementVersion);
      
      sortedHistory.forEach((version, index) => {
        console.log(`\n${index + 1}. Version ${version.entitlementVersion}`);
        console.log(`   Status: ${version.status}`);
        console.log(`   Quantity: ${version.quantity}`);
        console.log(`   Used: ${version.usedQuantity || 0}`);
        console.log(`   Period: ${version.startDate} to ${version.endDate}`);
        console.log(`   Modified: ${version.lastModifiedDate}`);
        
        // Compare with previous version
        if (index > 0) {
          const previous = sortedHistory[index - 1];
          const changes = [];
          
          if (version.status !== previous.status) {
            changes.push(`Status: ${previous.status} → ${version.status}`);
          }
          
          if (version.quantity !== previous.quantity) {
            changes.push(`Quantity: ${previous.quantity} → ${version.quantity}`);
          }
          
          if ((version.usedQuantity || 0) !== (previous.usedQuantity || 0)) {
            changes.push(`Used: ${previous.usedQuantity || 0} → ${version.usedQuantity || 0}`);
          }
          
          if (version.endDate !== previous.endDate) {
            changes.push(`End Date: ${previous.endDate} → ${version.endDate}`);
          }
          
          if (changes.length > 0) {
            console.log(`   📊 Changes from previous version:`);
            changes.forEach(change => console.log(`     ${change}`));
          }
        }
      });
      
      // Generate compliance insights
      console.log(`\n📋 Compliance Analysis:`);
      console.log(`   Total Versions: ${sortedHistory.length}`);
      
      const firstVersion = sortedHistory[0];
      const currentVersion = sortedHistory[sortedHistory.length - 1];
      
      console.log(`   Original Quantity: ${firstVersion.quantity}`);
      console.log(`   Current Quantity: ${currentVersion.quantity}`);
      console.log(`   Quantity Changes: ${currentVersion.quantity - firstVersion.quantity}`);
      
      // Track usage progression
      const maxUsed = Math.max(...sortedHistory.map(v => v.usedQuantity || 0));
      console.log(`   Peak Usage: ${maxUsed} units`);
      
      // Compliance status
      const currentUsage = currentVersion.usedQuantity || 0;
      const isCompliant = currentUsage <= currentVersion.quantity;
      console.log(`   Current Compliance: ${isCompliant ? '✅ Compliant' : '❌ Over-usage detected'}`);
      
      return sortedHistory;
    } else {
      console.log('No entitlement history found');
      return [];
    }
  } catch (error) {
    console.error('History fetch failed:', error);
    return [];
  }
}

// Usage example
fetchEntitlementHistory("ENT-001234")
  .then(history => {
    console.log(`Compliance audit complete: ${history.length} versions analyzed`);
  });

Error Handling

async function safeEntitlementFetch(customerIds, options = {}) {
  try {
    if (!Array.isArray(customerIds) || customerIds.length === 0) {
      throw new Error('CustomerIds must be a non-empty array');
    }
    
    const encodedIds = encodeURIComponent(JSON.stringify(customerIds));
    let url = `https://api.nue.io/entitlements?customerIds=${encodedIds}`;
    
    if (options.status) url += `&status=${options.status}`;
    if (options.includes) url += `&includes=${options.includes}`;
    
    const response = await fetch(url, {
      method: 'GET',
      headers: myHeaders
    });
    
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }
    
    const result = await response.json();
    
    if (result.status !== 'SUCCESS') {
      throw new Error(`API Error: ${result.message || 'Unknown error'}`);
    }
    
    return {
      entitlements: result.data || [],
      found: result.data?.length || 0,
      warnings: result.warnings || []
    };
    
  } catch (error) {
    console.error('Entitlement fetch error:', error);
    return {
      entitlements: [],
      found: 0,
      error: error.message
    };
  }
}

Query Parameters Reference

Parameter	Type	Required	Description
customerIds	Array[String]	*	JSON-encoded array of customer IDs
entitlementNumber	String	*	Specific entitlement number to fetch
status	String	No	Filter by entitlement status
includes	String	No	Related data to include

*Either customerIds or entitlementNumber is required

Entitlements provide customer access rights and usage limits based on their active assets and subscriptions.