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. This can be either the Nue name or the Salesforce name. See note in Subscription Response below for details around the format’s for Nue name and Salesforce name.

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

Why We Differentiate Subscription Naming Between Nue and Salesforce

Subscriptions created directly through Nue's self-service flow are assigned names in the format SUB-XXXXXXXX. These also carry an externalName field that maps to the corresponding Salesforce subscription name (which typically follows the format SUB-XXXXXX).

On the other hand, subscriptions originating in Salesforce retain the standard Salesforce naming convention (SUB-XXXXXX) and do not require the externalName mapping.

This approach is intentional and critical for data integrity. When a customer creates a subscription through self-service (i.e., within Nue), there's a chance that the sync to Salesforce could fail due to a variety of reasons (e.g., API limits, connectivity issues, data validation errors). If we used only the Salesforce name format and the sync failed, that subscription might get lost or become inaccessible.

By assigning Nue-generated subscriptions their own unique name format and storing the Salesforce name separately in externalName, we:

• Preserve the customer's data even if the Salesforce sync doesn't go through.

• Ensure billing continuity—the subscription still exists in Nue and can be billed against.

• Maintain traceability between Nue and Salesforce systems without data loss.

• Enable re-sync or manual intervention later, which will populate the externalName at that time.

This setup is a safeguard to protect valuable self-service subscription data and support uninterrupted billing workflows.

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.