Retrieve Subscription Data for Client Side Pricing Engine

19 min

The Nue Self-Service API provides specialized endpoints for retrieving subscription data optimized for client-side pricing calculations. This enables real-time pricing previews and calculations without server round trips.

Overview

Client-side pricing capabilities allow you to:

Calculate subscription changes instantly - Preview pricing for quantity updates, renewals, and modifications

Provide immediate feedback - Show customers pricing impacts before submitting changes

Reduce server load - Perform calculations locally with cached pricing data

Improve user experience - Eliminate waiting times for pricing calculations

Key Benefits

Real-Time Calculations

Calculate prices instantly based on subscription changes without API calls during user interactions.

Server-Side Parity

Ensure consistent pricing logic between client and server calculations.

Performance Optimization

Reduce server load by offloading pricing calculations to the client.

Offline Capability

Enable pricing calculations even without active network connections.

API Endpoint

Request Format

GET /subscriptions/pricing-engine-input

Query Parameters

Parameter	Type	Required	Description
customerIds	Array	Yes	JSON-encoded array of customer IDs

Example Request

const customerId = "003XX000004TmFd";
const customerIds = JSON.stringify([customerId]);
const url = `https://api.nue.io/subscriptions/pricing-engine-input?customerIds=${encodeURIComponent(customerIds)}`;

const response = await fetch(url, {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  }
});

const pricingData = await response.json();

Response Structure

The API returns subscription data organized by subscription name:

{
  "status": "SUCCESS",
  "data": {
    "SUB-00000483": {
      "changes": [
        {
          "changeType": "NewProduct",
          "endDate": "2025-01-12",
          "lineType": "LineItem",
          "listTotal": 148.5,
          "netSalesPrice": 9.9,
          "quantity": 15,
          "startDate": "2024-12-13",
          "subtotal": 148.5,
          "term": 1,
          "totalAmount": 148.5,
          "totalPrice": 148.5
        }
      ],
      "orderProduct": {
        "endDate": "2025-01-12",
        "listPrice": 9.9,
        "listTotal": 178.2,
        "product": {
          "id": "01tEi0000088M9QIAU",
          "name": "Revenue Dashboard",
          "priceModel": "Recurring",
          "productCategory": "RecurringServices",
          "sku": "REVENUE_DASHBOARD"
        },
        "quantity": 18,
        "startDate": "2024-12-13",
        "subtotal": 178.2,
        "term": 1
      }
    }
  },
  "warnings": []
}

Using the Pricing Engine

Installation

Install the required packages:

npm install @nue-apps/nue-pricing-clientjs
npm install @nue-apps/nue-js

Implementation

import { NuePricingChangeOrderCalculator } from '@nue-apps/nue-pricing-clientjs';

// Fetch pricing data
async function getPricingEngineData(customerId) {
  const customerIds = JSON.stringify([customerId]);
  const url = `https://api.nue.io/subscriptions/pricing-engine-input?customerIds=${encodeURIComponent(customerIds)}`;
  
  const response = await fetch(url, {
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    }
  });
  
  const result = await response.json();
  return result.data;
}

// Calculate subscription changes
async function calculateSubscriptionChanges(subscription, changes) {
  const pricingData = await getPricingEngineData(subscription.customerId);
  const subscriptionData = pricingData[subscription.name];
  
  if (!subscriptionData) {
    throw new Error(`No pricing data found for subscription ${subscription.name}`);
  }
  
  const calculator = new NuePricingChangeOrderCalculator();
  return calculator.calculateWithAssetChanges(subscriptionData, changes);
}

Common Use Cases

Quantity Updates

const quantityChanges = [{
  changeType: 'UpdateQuantity',
  newQuantity: 25,
  effectiveDate: '2024-07-01'
}];

const result = await calculateSubscriptionChanges(subscription, quantityChanges);

Subscription Renewals

const renewalChanges = [{
  changeType: 'Renew',
  renewalTerm: 12
}];

const result = await calculateSubscriptionChanges(subscription, renewalChanges);

Term Modifications

const termChanges = [{
  changeType: 'UpdateTerm',
  newTerm: 24,
  effectiveDate: '2024-07-01'
}];

const result = await calculateSubscriptionChanges(subscription, termChanges);

Best Practices

Caching Strategy

Implement intelligent caching to improve performance:

const pricingCache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes

async function getCachedPricingData(customerId) {
  const cacheKey = customerId;
  const cached = pricingCache.get(cacheKey);
  
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }
  
  const data = await getPricingEngineData(customerId);
  pricingCache.set(cacheKey, {
    data,
    timestamp: Date.now()
  });
  
  return data;
}

Error Handling

async function safeCalculateChanges(subscription, changes) {
  try {
    return await calculateSubscriptionChanges(subscription, changes);
  } catch (error) {
    console.error('Pricing calculation failed:', error);
    
    if (error.message.includes('No pricing data found')) {
      return { error: 'Pricing data unavailable' };
    }
    
    throw error;
  }
}

Batch Processing

Process multiple calculations efficiently:

async function batchCalculateSubscriptions(subscriptionChanges) {
  const customerIds = [...new Set(
    subscriptionChanges.map(item => item.subscription.customerId)
  )];
  
  // Fetch all pricing data at once
  const allPricingData = await Promise.all(
    customerIds.map(id => getPricingEngineData(id))
  );
  
  // Process calculations
  return Promise.all(
    subscriptionChanges.map(({ subscription, changes }) => {
      const pricingData = allPricingData.find(data => 
        data[subscription.name]
      );
      
      if (pricingData) {
        return calculateSubscriptionChanges(subscription, changes);
      }
      return null;
    })
  );
}

Response Format

Pricing calculations return detailed pricing information:

{
  "assetPrice": {
    "assetNumber": "SUB-000084",
    "changeItems": [
      {
        "deltaACV": 50000,
        "deltaARR": 50000,
        "deltaCMRR": 4166.67,
        "deltaTCV": 600000,
        "changeType": "Renew",
        "totalAmount": 660000,
        "totalPrice": 600000
      }
    ],
    "endDate": "2046-03-03",
    "quantity": 100,
    "startDate": "2022-03-04",
    "term": 24
  },
  "priceSummary": {
    "totalAmount": 660000,
    "totalPrice": 600000
  }
}

For additional information on subscription management and pricing:

Subscription Management Guide - Overview of subscription operations

Advanced Subscription Workflows - Complex subscription scenarios

Client Side Pricing Engine Documentation - Complete technical reference

This specialized endpoint provides the foundation for building responsive, real-time pricing experiences in your subscription management applications.