GuideReference

Retrieve Subscriptions

The Nue Self-Service API provides comprehensive capabilities for retrieving and managing customer subscriptions. There are two ways of showing customer’s their subscriptions:

Current Contract View

Use this view when you need to:

  • View the complete subscription lifecycle

  • See all changes (past, present, and future)

  • Understand the full contract terms

  • Plan future modifications

  • Generate complete subscription reports

Snapshot View

Use this view when you need to:

  • Analyze subscription state at a specific point in time

  • Track historical changes

  • Understand the impact of upcoming changes

  • Generate financial reports for a specific period

  • Audit subscription changes

How to Retrieve Current Contract ViewCopied!

To retrieve the current contract for 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)

  • version: To specify the version of the subscriptions to retrieve, with currently the only option being latest

  • 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

How to Retrieve Snapshot ViewCopied!

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

For the snapshot view, the snapshotDate MUST be provided as a query parameter. In addition, the following query parameters are supported:

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

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

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

Subscription Response

The response includes detailed information about each subscription at a specific point in time:

  1. Basic Details

    1. Subscription ID, name, status

    2. External ID and parent subscription relationships

    3. Snapshot date and subscription state

  2. Account Information

    1. Customer ID and billing account ID

    2. External system identifiers

    3. Account hierarchies and relationships

  3. Subscription Terms

    1. Start and end dates

    2. Subscription term length

    3. Unit of measure details

      1. Term dimension (Month, Year, etc.)

  4. Product and Pricing Details

    1. Product ID and product details (when includes=product)

    2. Price book entries

    3. Quantity and unit specifications

    4. Price tag details (when includes=pricetags)

  5. Future Changes (when includes=upcomingChanges)

    1. Scheduled quantity updates

    2. Product upgrades and swaps

    3. Term modifications and renewals

    4. Cancellation and end dates

    5. Change effective dates

  6. Snapshot Metadata

    1. Point-in-time calculation date

    2. Subscription status at snapshot date

    3. Warnings and validation messages

Why We Differentiate Subscription Naming Between Nue and SalesforceCopied!

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 th

© 2025 Nue.io