Get Subscription

GET /accounting/subscriptions/{id}

Group: Accounting › Subscriptions · Operation ID: getSubscription

Fetch a single subscription by its id (a UUID), bound from the :id path segment. Returns the subscription with its customer and legal entity references, renewal terms, derived service dates and lifecycle status, cancellation/suspension state and notes, recognised recurring revenue, and its line detail: every subscription line with its product, quantity, service dates and own recurring revenue. The full item schema — header fields and the nested lines collection alike — matches POST accounting/subscriptions/search (R2.4.1). GET accounting/subscriptions is a data-set and returns header fields only. Read-only. Raises NOT_FOUND when no subscription has that id (should map to 404). Every request must carry the Api-Version header.

Open in the interactive reference

Parameters

Name In Type Required Description
Api-Version header "v1" yes The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version v1.
id path string yes Id of the subscription to fetch (a UUID); bound from the :id path segment.

Response

200 Success

Under data (getSubscriptionOutput):

Field Type Required Description
id string yes Id of the subscription (a UUID) — the public identifier used by GET accounting/subscriptions/:id.
subscriptionNumber string no System-generated, human-readable subscription number (e.g. SUB-1), unique per tenant. Absent until one has been assigned.
customerId string no Id of the customer this subscription belongs to (a UUID).
customerName string no Display name of that customer, denormalised onto the subscription.
entityId string no Id of the legal entity that owns this subscription (a UUID). Absent when the entity's own uuid column is unset — a pre-existing data-quality gap on some entity records, not an error (see qtc/subscription/core/search/searchSubscription.ts's toViews()).
currency string yes ISO 4217 three-letter currency code (e.g. USD, EUR, GBP) governing annualRecurringRevenue and monthlyRecurringRevenue below.
autoRenew boolean no Whether the subscription renews automatically at term end.
renewalTerm number no Length of the auto-renewal term, in the subscription's term unit.
renewalPriceChangePercentage string (decimal) no Percentage to adjust the price by on renewal. A percentage, not an amount — it carries no currency (R9.4c).
termType string yes Contract term structure. A TermType member: 'termed' or 'evergreen'.
subscriptionStatus string no Derived lifecycle status, computed from the status of the subscription's lines. A SubscriptionStatus member: 'pendingActivation', 'notStarted', 'active', 'pendingOrderApproval', 'canceled', 'suspended'.
serviceStartDateBasis string no Basis on which the service start date is determined. A ServiceStartDateBasis member: 'fixedDate' or 'serviceActivation'.
serviceActivationDate string (date) no Date service was activated, when serviceStartDateBasis is 'serviceActivation' (YYYY-MM-DD).
serviceStartDate string (date) no Earliest service start date across the subscription's lines (YYYY-MM-DD), derived.
serviceEndDate string (date) no Latest service end date across the subscription's lines (YYYY-MM-DD), derived.
submissionDate string (date) no Date the subscription's originating sales order was submitted (YYYY-MM-DD).
cancellationDate string (date) no Date from which the subscription is or will be canceled, when a cancellation has been recorded (YYYY-MM-DD).
cancellationNote string no Free-text note recorded about the cancellation. Carried here and on search/v1; the list data-set omits it as free text (R7.2).
cancellationReason string no Short reason code for the cancellation. A SubscriptionCancellationReasons member. Absent when the subscription has not been canceled.
isCancellationEnabled boolean no Whether the cancellation procedure has been applied to this subscription.
suspensionDate string (date) no Date from which the subscription is or will be suspended, when a suspension has been recorded (YYYY-MM-DD).
suspensionNote string no Free-text note recorded about the suspension. Carried here and on search/v1; the list data-set omits it as free text (R7.2).
suspensionReason string no Short reason code for the suspension. A SubscriptionSuspensionReasons member. Absent when the subscription has not been suspended.
isSuspensionEnabled boolean no Whether the suspension process is enabled for this subscription.
externalSubscriptionId string no Identifier of this subscription in an external system, when one was recorded at creation.
annualRecurringRevenue string (decimal) no Annualized recurring revenue, in the subscription currency (see currency): the sum of each active line's own annual recurring revenue.
monthlyRecurringRevenue string (decimal) no Monthly recurring revenue, in the subscription currency (see currency): the sum of each active line's own monthly recurring revenue.
totalUserCount string (decimal) no Total active user/seat count across the subscription's active lines. A count, not a currency amount (R9.4c).
prepaidBalance string (decimal) no Remaining prepaid balance available to this subscription, summed across its prepaid balance accesses. A drawdown counter, not a currency amount (R9.4c).
lines array of object yes The subscription's lines — one per product on the subscription — oldest first. Empty when the subscription has none. POST accounting/subscriptions/search carries the identical collection (R2.4.1); GET accounting/subscriptions cannot, being a scalar-only data-set (R2.3).
lines[].id string yes Id of the subscription line (a UUID) — its public identifier.
lines[].subscriptionLineNumber string no Unique, human-readable number of this subscription line. Absent until one has been assigned.
lines[].productName string no Name of the product this line covers.
lines[].quantity string (decimal) no Quantity across the line's associated sales order product lines. A count, not a currency amount (R9.4c).
lines[].currency string yes ISO 4217 three-letter currency code (e.g. USD, EUR, GBP) governing this line's annualRecurringRevenue and monthlyRecurringRevenue.
lines[].subscriptionLineStatus string no Lifecycle status of this line. A SubscriptionLineStatus member.
lines[].serviceStartDate string (date) no Date service starts for this line (YYYY-MM-DD).
lines[].serviceEndDate string (date) no Date service ends for this line (YYYY-MM-DD).
lines[].customServiceEndDate string (date) no Service end date recorded against this line by a subscription update, when one has overridden the derived date (YYYY-MM-DD).
lines[].maxSalesOrderProductLineServiceEndDate string (date) no Latest service end date across this line's sales order product lines (YYYY-MM-DD).
lines[].annualRecurringRevenue string (decimal) no Annualized recurring revenue of this line, in the line currency (see this line's currency).
lines[].monthlyRecurringRevenue string (decimal) no Monthly recurring revenue of this line, in the line currency (see this line's currency).
lastModifiedDate string (date-time) yes Instant the subscription record last changed, as ISO 8601 UTC (YYYY-MM-DDTHH:mm:ss.sssZ). Poll on this to sync incrementally rather than re-reading the whole collection.

Errors

Code Status
NOT_FOUND 400

Statuses