# 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](https://docs.api.lensing.ai/?op=getSubscription)

## 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

- `400` — Invalid request or business failure. Codes: NOT_FOUND
- `401` — Missing or invalid access token
- `403` — Not authorized
- `404` — Not found
- `429` — Too many requests
- `500` — Internal server error