# Retrieve a subscription

Operation ID: `getSubscription`

Group: Accounting › Subscriptions

[Open in the interactive reference](https://docs.api.lensing.ai/lensing/v1/endpoints/getSubscription)

`GET /accounting/subscriptions/{id}`

Read-only: Reads and returns; changes nothing.

Retrieves a subscription. Use the subscription's id, not its subscriptionNumber.

The response includes the subscription's customer, legal entity, and lines. POST accounting/subscriptions/search returns the same fields for each subscription.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Api-Version` | header | string · 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 | The unique identifier of the subscription you want to retrieve. |

## Response

`200` Success

Under `data` (getSubscriptionOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The unique identifier for the subscription. |
| `subscriptionNumber` | string | no | The subscription number. Unique within the tenant. Example: 'SUB-1'. |
| `customerId` | string | no | The customer this subscription belongs to. See id on GET accounting/customers/:id. |
| `customerName` | string | no | The name of the customer this subscription belongs to. See name on GET accounting/customers/:id. |
| `entityId` | string | no | The legal entity that owns this subscription. See id on GET base/entities. |
| `currency` | string | yes | The currency of annualRecurringRevenue and monthlyRecurringRevenue. Format ISO 4217, for example 'USD'. |
| `autoRenew` | boolean | no | Whether the subscription renews automatically at the end of its term. |
| `renewalTerm` | number | no | The length of the auto-renewal term, in the subscription's term unit. |
| `renewalPriceChangePercentage` | decimal | no | The percentage by which the price changes on renewal. |
| `termType` | string | yes | The term type of the subscription. Possible values: 'termed', 'evergreen'. |
| `subscriptionStatus` | string | no | The status of the subscription, derived from the status of its lines. Possible values: 'pendingActivation', 'notStarted', 'active', 'pendingOrderApproval', 'canceled', 'suspended'. |
| `serviceStartDateBasis` | string | no | How the service start date is determined. Possible values: 'fixedDate', 'serviceActivation'. |
| `serviceActivationDate` | date | no | The date service was activated. Set only when serviceStartDateBasis is 'serviceActivation'. Format YYYY-MM-DD. |
| `serviceStartDate` | date | no | The earliest service start date across the subscription's lines. Format YYYY-MM-DD. |
| `serviceEndDate` | date | no | The latest service end date across all of the subscription's lines. Format YYYY-MM-DD. Usually absent when the subscription is evergreen, but present once it is canceled or suspended. |
| `submissionDate` | date | no | The submission date of the sales order this subscription came from. Format YYYY-MM-DD. |
| `cancellationDate` | date | no | The date from which the subscription is or will be canceled. Absent when no cancellation has been recorded. Format YYYY-MM-DD. |
| `cancellationNote` | string | no | A note about the cancellation. |
| `cancellationReason` | string | no | The reason code for the cancellation. Possible values: 'noReasonGiven', 'budgetary', 'movingToCompetitors', 'lowCustomerSatisfaction', 'bankruptcy', 'acquisitionMerger'. Absent when the subscription has not been canceled. |
| `isCancellationEnabled` | boolean | no | Whether the cancellation procedure has been applied to this subscription. |
| `suspensionDate` | date | no | The date from which the subscription is or will be suspended. Absent when no suspension has been recorded. Format YYYY-MM-DD. |
| `suspensionNote` | string | no | A note about the suspension. |
| `suspensionReason` | string | no | The reason code for the suspension. Possible values: 'unpaidBalance', 'invalidPaymentMethod'. Absent when the subscription has not been suspended. |
| `isSuspensionEnabled` | boolean | no | Whether the suspension process is enabled for this subscription. |
| `externalSubscriptionId` | string | no | The subscription's identifier in an external system. Absent when none was recorded at creation. |
| `annualRecurringRevenue` | decimal | no | The annual recurring revenue, in the subscription's currency: the sum of annualRecurringRevenue across its active and suspended lines. |
| `monthlyRecurringRevenue` | decimal | no | The monthly recurring revenue, in the subscription's currency: the sum of monthlyRecurringRevenue across its active and suspended lines. |
| `totalUserCount` | decimal | no | The number of active users or seats across the subscription's active lines. |
| `prepaidBalance` | decimal | no | The prepaid balance remaining for this subscription, summed across the prepaid balances linked to it. The balance is a quantity, not a currency amount. |
| `lines` | array<object> | yes | The subscription's lines, one for each product on the subscription, oldest first. An empty array when the subscription has none. |
| `lines[].id` | string | yes | The unique identifier for the subscription line. |
| `lines[].subscriptionLineNumber` | string | no | The subscription line number. Unique within the tenant. |
| `lines[].productName` | string | no | The name of the product this line covers. |
| `lines[].quantity` | decimal | no | The quantity currently on this line, summed across its sales order product lines. |
| `lines[].currency` | string | yes | The currency of annualRecurringRevenue and monthlyRecurringRevenue on this line. Format ISO 4217, for example 'USD'. |
| `lines[].subscriptionLineStatus` | string | no | The status of this line. Possible values: 'pendingActivation', 'notStarted', 'active', 'pendingOrderApproval', 'canceled', 'suspended'. |
| `lines[].serviceStartDate` | date | no | The date service starts for this line. Format YYYY-MM-DD. |
| `lines[].serviceEndDate` | date | no | The date service ends for this line: the later of customServiceEndDate and maxSalesOrderProductLineServiceEndDate. When the subscription is cancelable and has a cancellationDate, serviceEndDate is maxSalesOrderProductLineServiceEndDate. Format YYYY-MM-DD. |
| `lines[].customServiceEndDate` | date | no | The service end date set on this line by a subscription modification, such as extending the term or ending the line. Absent when no modification has set one. Format YYYY-MM-DD. |
| `lines[].maxSalesOrderProductLineServiceEndDate` | date | no | The latest service end date across this line's sales order product lines. Format YYYY-MM-DD. |
| `lines[].annualRecurringRevenue` | decimal | no | The annual recurring revenue of this line, in the line's currency. The value counts only while subscriptionLineStatus is 'active' or 'suspended', and is 0 otherwise. |
| `lines[].monthlyRecurringRevenue` | decimal | no | The monthly recurring revenue of this line, in the line's currency. monthlyRecurringRevenue = annualRecurringRevenue / 12. |
| `lines[].salesOrders` | array<object> | yes | The sales orders that carry this line, oldest first. An empty array when no sales order carries it. |
| `lines[].salesOrders[].id` | string | yes | The sales order. See id on GET accounting/sales-orders/:id. |
| `lines[].salesOrders[].orderNumber` | string | no | The sales order number. Example: 'SO-1042'. |
| `lines[].salesOrders[].orderType` | string | no | The type of the sales order. Possible values: 'new', 'upsell', 'earlyRenewal', 'renewal', 'replacement'. |
| `lines[].salesOrders[].approvalStatus` | string | no | The approval status of the sales order. Possible values: 'draft', 'pendingApproval', 'revise', 'approved', 'rejected'. |
| `salesOrders` | array<object> | yes | The sales orders that carry this subscription, oldest first: the order that created it, then every later upsell, renewal or replacement. An empty array when no sales order carries it. |
| `salesOrders[].id` | string | yes | The sales order. See id on GET accounting/sales-orders/:id. |
| `salesOrders[].orderNumber` | string | no | The sales order number. Example: 'SO-1042'. |
| `salesOrders[].orderType` | string | no | The type of the sales order. Possible values: 'new', 'upsell', 'earlyRenewal', 'renewal', 'replacement'. |
| `salesOrders[].approvalStatus` | string | no | The approval status of the sales order. Possible values: 'draft', 'pendingApproval', 'revise', 'approved', 'rejected'. |
| `lastModifiedDate` | date-time | yes | The date and time the subscription last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |

```json
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "subscriptionNumber": "<subscriptionNumber>",
    "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "customerName": "<customerName>",
    "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "currency": "<currency>",
    "autoRenew": true,
    "renewalTerm": 0,
    "renewalPriceChangePercentage": "19.99",
    "termType": "<termType>",
    "subscriptionStatus": "<subscriptionStatus>",
    "serviceStartDateBasis": "<serviceStartDateBasis>",
    "serviceActivationDate": "2026-01-15",
    "serviceStartDate": "2026-01-15",
    "serviceEndDate": "2026-01-15",
    "submissionDate": "2026-01-15",
    "cancellationDate": "2026-01-15",
    "cancellationNote": "<cancellationNote>",
    "cancellationReason": "<cancellationReason>",
    "isCancellationEnabled": true,
    "suspensionDate": "2026-01-15",
    "suspensionNote": "<suspensionNote>",
    "suspensionReason": "<suspensionReason>",
    "isSuspensionEnabled": true,
    "externalSubscriptionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "annualRecurringRevenue": "19.99",
    "monthlyRecurringRevenue": "19.99",
    "totalUserCount": "19.99",
    "prepaidBalance": "19.99",
    "lines": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "subscriptionLineNumber": "<subscriptionLineNumber>",
        "productName": "<productName>",
        "quantity": "19.99",
        "currency": "<currency>",
        "subscriptionLineStatus": "<subscriptionLineStatus>",
        "serviceStartDate": "2026-01-15",
        "serviceEndDate": "2026-01-15",
        "customServiceEndDate": "2026-01-15",
        "maxSalesOrderProductLineServiceEndDate": "2026-01-15",
        "annualRecurringRevenue": "19.99",
        "monthlyRecurringRevenue": "19.99",
        "salesOrders": [
          {
            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "orderNumber": "<orderNumber>",
            "orderType": "<orderType>",
            "approvalStatus": "<approvalStatus>"
          }
        ]
      }
    ],
    "salesOrders": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "orderNumber": "<orderNumber>",
        "orderType": "<orderType>",
        "approvalStatus": "<approvalStatus>"
      }
    ],
    "lastModifiedDate": "2026-01-15T09:30:00.000Z"
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}
```

## Errors

| Code | Status |
| --- | --- |
| `NOT_FOUND` | 400 |

## Statuses

- `400` — Invalid request or business failure. Codes: NOT_FOUND
- `401` — The request carries no valid access token.
- `403` — Not authorized
- `404` — Not found
- `429` — Too many requests from this client address. The response has no body and no `Retry-After` header.
- `500` — Internal server error