The Nue Self-Service API provides comprehensive capabilities for retrieving and managing customer subscriptions. This functionality enables customers to view their active subscriptions, track subscription history, and monitor their recurring services.

How to Retrieve Customer SubscriptionsCopied!

Required Information

To retrieve customer subscriptions, you need one of:

• Customer IDs: Array of unique identifiers for customers whose subscriptions you want to retrieve

• Subscription Name: The specific name of a subscription to fetch

Query Parameters

The subscription retrieval endpoint (/subscriptions) supports several query parameters:

• customerIds: JSON-encoded array of customer IDs (cannot be used with name)

• name: Name of specific subscription to fetch (cannot be used with customerIds)

• history: Boolean flag to include subscription history (only valid with name)

• includes: Comma-separated list of related data to include (currently supports product and pricetags)

• status: Filter subscriptions by status:

  • active: Currently active subscriptions

  • expired: Past subscriptions

  • canceled: Canceled subscriptions

Subscription Response

The response includes detailed information about each subscription:

1. Basic Details

   1. Subscription ID, name, status

   2. Creation and modification timestamps

   3. Subscription version and composite ID

2. Financial Information

   1. List price and sales price

   2. Total amounts (ACV, TCV)

   3. Tax amounts

3. Subscription Terms

   1. Start and end dates

   2. Subscription term length

   3. Auto-renewal settings

   4. Billing timing

4. Product and Price Tag Details

   1. Product details

   2. Price book entries

   3. Product features

   4. Unit of measure details

   5. Price tag details

   6. Price tag tiers

Note: Subscriptions originating in Nue have name format of SUB-XXXXXXXX which is the Nue name. These subscriptions have a field called externalName which refers to the name in Salesforce. Subscriptions originating in Salesforce will follow the standard Salesforce name with format SUB-XXXXXX

Use Cases for Subscription Retrieval

This functionality supports several key self-service scenarios:

1. Active Subscription Management:

   1. View current subscriptions

   2. Monitor renewal dates

   3. Track subscription quantities

2. Subscription History:

   1. Review past subscription changes

   2. Track version history

   3. Analyze usage patterns

3. Financial Planning:

   1. Monitor subscription costs

   2. Track recurring charges

   3. Plan for renewals

4. Product Management:

   1. View included features

   2. Understand pricing tiers

Best Practices

1. Performance Optimization:

   1. Use specific customer IDs when possible

   2. Include only necessary related data

   3. Implement appropriate caching strategies

2. Data Management:

   1. Regularly sync subscription data

   2. Monitor subscription statuses

   3. Track version changes

3. User Experience:

   1. Provide clear subscription status indicators

   2. Show relevant renewal information

   3. Link to appropriate subscription management actions

4. Error Handling:

   1. Handle expired subscriptions appropriately

   2. Manage subscription transitions

   3. Process renewal failures gracefully

By implementing effective subscription retrieval, you enable customers to maintain clear visibility into their recurring services and manage their ongoing relationship with your business effectively.