# Search Subscription

`POST /accounting/subscriptions/search`

Group: Accounting › Subscriptions · Operation ID: `searchSubscription`

Returns the subscriptions that match the given filters. Each match is the full record, including the customer and legal entity and the cancellation and suspension notes the collection omits.

[Open in the interactive reference](https://docs.api.lensing.ai/?op=searchSubscription)

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

## Request body

Required, `application/json`: searchSubscriptionInput.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filters` | object | no | The filters to apply. A subscription must match every filter you send. Omit to return all subscriptions you may read. |
| `filters.id` | string | no | Limits results to the subscription with this identifier. The match is exact. |
| `filters.subscriptionNumber` | string | no | Limits results to the subscription with this subscription number, for example 'SUB-1'. The match is exact. |
| `filters.customerId` | string | no | Limits results to subscriptions of this customer. An id that matches no customer returns an empty page. See id on GET accounting/customers/:id. |
| `filters.entityId` | string | no | Limits results to subscriptions owned by this legal entity. An id that matches no entity returns an empty page. See id on GET base/entities. |
| `filters.termType` | string | no | Limits results to subscriptions with this term structure. Possible values: 'termed', 'evergreen'. Any other value matches nothing. |
| `filters.subscriptionStatus` | string | no | Limits results to subscriptions in this status. Possible values: 'pendingActivation', 'notStarted', 'active', 'pendingOrderApproval', 'canceled', 'suspended'. Any other value matches nothing. |
| `filters.autoRenew` | boolean | no | Limits results to subscriptions set to auto-renew when true, or not when false. |
| `filters.cancellationReason` | string | no | Limits results to subscriptions canceled for this reason. Possible values: 'noReasonGiven', 'budgetary', 'movingToCompetitors', 'lowCustomerSatisfaction', 'bankruptcy', 'acquisitionMerger'. Any other value matches nothing. |
| `filters.suspensionReason` | string | no | Limits results to subscriptions suspended for this reason. Possible values: 'unpaidBalance', 'invalidPaymentMethod'. Any other value matches nothing. |
| `filters.externalSubscriptionId` | string | no | Limits results to the subscription with this external identifier. The match is exact. |
| `filters.serviceStartDate` | object | no | Limits results to subscriptions whose derived serviceStartDate falls in this range. Both bounds are inclusive, and omitting one leaves that side open. |
| `filters.serviceStartDate.start` | string (date) | no | The earliest serviceStartDate to include. Format YYYY-MM-DD. |
| `filters.serviceStartDate.end` | string (date) | no | The latest serviceStartDate to include. Format YYYY-MM-DD. |
| `filters.serviceEndDate` | object | no | Limits results to subscriptions whose derived serviceEndDate falls in this range. Both bounds are inclusive, and omitting one leaves that side open. |
| `filters.serviceEndDate.start` | string (date) | no | The earliest serviceEndDate to include. Format YYYY-MM-DD. |
| `filters.serviceEndDate.end` | string (date) | no | The latest serviceEndDate to include. Format YYYY-MM-DD. |
| `page` | object | no | Pagination controls. Omit for the first page. |
| `page.cursor` | string | no | The cursor from the previous response's pagination.nextCursor. Omit on the first request. |
| `page.size` | number | no | The number of subscriptions per page. Defaults to 50. A value above 200 is treated as 200, not rejected. |

Example:

```json
{
  "filters": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "subscriptionNumber": "<subscriptionNumber>",
    "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "termType": "<termType>",
    "subscriptionStatus": "<subscriptionStatus>",
    "autoRenew": true,
    "cancellationReason": "<cancellationReason>",
    "suspensionReason": "<suspensionReason>",
    "externalSubscriptionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "serviceStartDate": {
      "start": "2026-01-15",
      "end": "2026-01-15"
    },
    "serviceEndDate": {
      "start": "2026-01-15",
      "end": "2026-01-15"
    }
  },
  "page": {
    "cursor": "<cursor>",
    "size": 0
  }
}
```

## Response

`200` Success

Under `data` (searchSubscriptionOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object | yes | The subscriptions that match, most recently created first. An empty array when nothing matches. |
| `items[].id` | string | yes | The unique identifier for the subscription. |
| `items[].subscriptionNumber` | string | no | The subscription number, for example 'SUB-1', unique within the tenant. Absent until one has been assigned. |
| `items[].customerId` | string | no | The customer this subscription belongs to. See id on GET accounting/customers/:id. |
| `items[].customerName` | string | no | The display name of the customer this subscription belongs to. |
| `items[].entityId` | string | no | The legal entity that owns this subscription. Absent when the owning entity has no recorded identifier. See id on GET base/entities. |
| `items[].currency` | string | yes | The currency of annualRecurringRevenue and monthlyRecurringRevenue. Format ISO 4217, for example 'USD'. |
| `items[].autoRenew` | boolean | no | Whether the subscription renews automatically at the end of its term. |
| `items[].renewalTerm` | number | no | The length of the auto-renewal term, in the subscription's term unit. |
| `items[].renewalPriceChangePercentage` | string (decimal) | no | The percentage the price is adjusted by on renewal. It is a percentage, not an amount, so it has no currency. |
| `items[].termType` | string | yes | The contract term structure. Possible values: 'termed', 'evergreen'. |
| `items[].subscriptionStatus` | string | no | The subscription's lifecycle status, derived from the status of its lines. Possible values: 'pendingActivation', 'notStarted', 'active', 'pendingOrderApproval', 'canceled', 'suspended'. |
| `items[].serviceStartDateBasis` | string | no | How the service start date is determined. Possible values: 'fixedDate', 'serviceActivation'. |
| `items[].serviceActivationDate` | string (date) | no | The date service was activated, when serviceStartDateBasis is 'serviceActivation'. Format YYYY-MM-DD. |
| `items[].serviceStartDate` | string (date) | no | The earliest service start date across the subscription's lines. Format YYYY-MM-DD. |
| `items[].serviceEndDate` | string (date) | no | The latest service end date across the subscription's lines. Format YYYY-MM-DD. |
| `items[].submissionDate` | string (date) | no | The date the subscription's originating sales order was submitted. Format YYYY-MM-DD. |
| `items[].cancellationDate` | string (date) | no | The date from which the subscription is or will be canceled. Absent when no cancellation has been recorded. Format YYYY-MM-DD. |
| `items[].cancellationNote` | string | no | A free-text note recorded about the cancellation. |
| `items[].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. |
| `items[].isCancellationEnabled` | boolean | no | Whether the cancellation procedure has been applied to this subscription. |
| `items[].suspensionDate` | string (date) | no | The date from which the subscription is or will be suspended. Absent when no suspension has been recorded. Format YYYY-MM-DD. |
| `items[].suspensionNote` | string | no | A free-text note recorded about the suspension. |
| `items[].suspensionReason` | string | no | The reason code for the suspension. Possible values: 'unpaidBalance', 'invalidPaymentMethod'. Absent when the subscription has not been suspended. |
| `items[].isSuspensionEnabled` | boolean | no | Whether the suspension process is enabled for this subscription. |
| `items[].externalSubscriptionId` | string | no | The subscription's identifier in an external system. Absent when none was recorded at creation. |
| `items[].annualRecurringRevenue` | string (decimal) | no | The annualized recurring revenue, in the subscription's currency: the sum of each active line's annual recurring revenue. |
| `items[].monthlyRecurringRevenue` | string (decimal) | no | The monthly recurring revenue, in the subscription's currency: the sum of each active line's monthly recurring revenue. |
| `items[].totalUserCount` | string (decimal) | no | The total active user or seat count across the subscription's active lines. It is a count, not a currency amount. |
| `items[].prepaidBalance` | string (decimal) | no | The remaining prepaid balance available to this subscription, summed across its prepaid balance accesses. It is a drawdown counter, not a currency amount. |
| `items[].lines` | array of object | yes | The subscription's lines — one per product on the subscription — oldest first. Empty when the subscription has none. GET accounting/subscriptions/:id carries the identical collection (R2.4.1); GET accounting/subscriptions cannot, being a scalar-only data-set (R2.3). Read for the whole page in one query, but a large page still fans out into every line of every subscription on it. |
| `items[].lines[].id` | string | yes | Id of the subscription line (a UUID) — its public identifier. |
| `items[].lines[].subscriptionLineNumber` | string | no | Unique, human-readable number of this subscription line. Absent until one has been assigned. |
| `items[].lines[].productName` | string | no | Name of the product this line covers. |
| `items[].lines[].quantity` | string (decimal) | no | Quantity across the line's associated sales order product lines. A count, not a currency amount (R9.4c). |
| `items[].lines[].currency` | string | yes | ISO 4217 three-letter currency code (e.g. USD, EUR, GBP) governing this line's annualRecurringRevenue and monthlyRecurringRevenue. |
| `items[].lines[].subscriptionLineStatus` | string | no | Lifecycle status of this line. A SubscriptionLineStatus member. |
| `items[].lines[].serviceStartDate` | string (date) | no | Date service starts for this line (YYYY-MM-DD). |
| `items[].lines[].serviceEndDate` | string (date) | no | Date service ends for this line (YYYY-MM-DD). |
| `items[].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). |
| `items[].lines[].maxSalesOrderProductLineServiceEndDate` | string (date) | no | Latest service end date across this line's sales order product lines (YYYY-MM-DD). |
| `items[].lines[].annualRecurringRevenue` | string (decimal) | no | Annualized recurring revenue of this line, in the line currency (see this line's `currency`). |
| `items[].lines[].monthlyRecurringRevenue` | string (decimal) | no | Monthly recurring revenue of this line, in the line currency (see this line's `currency`). |
| `items[].lastModifiedDate` | string (date-time) | yes | The date and time the subscription record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `pagination` | object | yes | The pagination cursor for this page. |
| `pagination.nextCursor` | string | no | The cursor for the next page. Pass it as page.cursor. Absent on the last page. |
| `pagination.hasMore` | boolean | yes | True when more matches remain beyond this page. |

## Statuses

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