---
title: Fetching Entitlements
slug: fetching-entitlements
docTags: 
createdAt: 2026-02-13T04:24:47.548Z
---

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:

```javascript
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:

```javascript
// 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 →](https://api-docs.nue.io/fetch-entitlements)

```javascript
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

```javascript
// 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:

```javascript
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:

```javascript
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));
```

## Including Related Data

### Fetch Entitlements with Product Details

Include product information in the entitlement response:

```javascript
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:

```javascript
// 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:

```javascript
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

```javascript
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.