Fetch Customer Subscriptions

1 min

GET

https://api.nue.io/subscriptions

This endpoint allows you to retrieve all subscriptions associated with a customer. Supports both current subscription data and point-in-time snapshots with upcoming changes.

customerIdsarrayA JSON-encoded array of customerIds to fetch all customer subscriptions for those customers. Cannot be used with name parameter.

namestringThe name of the subscription to fetch. Cannot be used with the customerIds parameter.

snapshotDatestringGenerate a point-in-time snapshot of the subscription as it existed on this date. Format is YYYY-MM-DD. When provided, returns snapshot-formatted data with calculated upcoming changes. Cannot be used with history, status, or version parameters.

historybooleanInclude the history of the subscription. Can only be used with the name parameter. Cannot be used with snapshotDate.

includesstringA list of fields to include in the response. Valid options are product, pricetags, and upcomingChanges (only with snapshotDate).

productDetailstringControls how much of each product is returned. Requires <code>includes=product</code>. Sending <code>productDetail</code> without it returns 400 INVALID_PARAMETER_COMBINATION. <ul> <li><code>full</code> (default): the complete product, including its recursive product option graph.</li> <li><code>root</code>: the product's own identity and pricing only. <code>productOptions</code> and <code>productFeatures</code> are omitted, while <code>id</code>, <code>sku</code>, <code>name</code>, <code>priceModel</code>, <code>status</code>, <code>publishStatus</code>, <code>uom</code> and <code>priceBookEntries</code> are retained.</li> </ul> Use <code>root</code> when you need to identify the product a subscription is on rather than its sellable configuration. For bundles with deep option trees this substantially reduces the response size. The value is case-insensitive and an empty value is treated as <code>full</code>; any other value returns 400 INVALID_PARAMETER.

bundledbooleanFilters to subscriptions by whether they are a bundled component priced as part of a parent bundle. <code>false</code> also matches subscriptions where the value was never set, so <code>true</code> and <code>false</code> partition the result set between them.

subscriptionLevelstringFilters to subscriptions at a given depth in the bundle hierarchy. <code>1</code> is a top-level subscription, <code>2</code> is an option inside it, and so on. Accepts a comma-separated list, e.g. <code>1,2</code>. A well-formed value outside the range present in the data matches nothing rather than erroring; a non-integer value returns 400 INVALID_FILTER_VALUE.

statusstringFilter the subscriptions by status. Valid values are active for currently active subscriptions, expired for past subscriptions, or canceled for canceled subscriptions. Cannot be used with snapshotDate.

versionstringFilter the subscriptions by version. Valid values are latest for current versions or snapshot for chronological snapshots. Cannot be used with snapshotDate.

acceptstringGenerated from available response content types

200Successful retrieval of customer subscriptions.

207Partial success. The subscriptions were returned, but at least one filter could not be applied, typically a filter combined with <code>snapshotDate</code> on a field that a snapshot recalculates. The skipped filters are named in a <code>FILTER_NOT_SUPPORTED_WITH_SNAPSHOT</code> entry in <code>warnings</code>.

400Invalid request. Returned when a query parameter does not correspond to a field on the subscription object, when a filter value does not match its field's type (INVALID_FILTER_VALUE), or when <code>productDetail</code> is supplied without <code>includes=product</code> (INVALID_PARAMETER_COMBINATION).

curl --request GET \
     --url 'https://api.nue.io/subscriptions?productDetail=full' \
     --header 'accept: application/json'