# Search subscriptions

Operation ID: `searchSubscription`

Group: Accounting › Subscriptions

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

`POST /accounting/subscriptions/search`

Read-only: A read that takes its filters in the body. Changes nothing, and ignores Idempotency-Key.

Searches subscriptions. Each subscription in the response is the full record, with its customer, legal entity, and lines. The response also includes cancellationNote and suspensionNote, which GET accounting/subscriptions doesn't return.

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

## 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` | date | no | The earliest serviceStartDate to include. Format YYYY-MM-DD. |
| `filters.serviceStartDate.end` | 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` | date | no | The earliest serviceEndDate to include. Format YYYY-MM-DD. |
| `filters.serviceEndDate.end` | 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. |

```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<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. Unique within the tenant. Example: 'SUB-1'. |
| `items[].customerId` | string | no | The customer this subscription belongs to. See id on GET accounting/customers/:id. |
| `items[].customerName` | string | no | The name of the customer this subscription belongs to. See name on GET accounting/customers/:id. |
| `items[].entityId` | string | no | The legal entity that owns this subscription. 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` | decimal | no | The percentage by which the price changes on renewal. |
| `items[].termType` | string | yes | The term type of the subscription. Possible values: 'termed', 'evergreen'. |
| `items[].subscriptionStatus` | string | no | The status of the subscription, 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` | date | no | The date service was activated. Set only when serviceStartDateBasis is 'serviceActivation'. Format YYYY-MM-DD. |
| `items[].serviceStartDate` | date | no | The earliest service start date across the subscription's lines. Format YYYY-MM-DD. |
| `items[].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. |
| `items[].submissionDate` | date | no | The submission date of the sales order this subscription came from. Format YYYY-MM-DD. |
| `items[].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. |
| `items[].cancellationNote` | string | no | A note 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` | 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 note 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` | decimal | no | The annual recurring revenue, in the subscription's currency: the sum of annualRecurringRevenue across its active and suspended lines. |
| `items[].monthlyRecurringRevenue` | decimal | no | The monthly recurring revenue, in the subscription's currency: the sum of monthlyRecurringRevenue across its active and suspended lines. |
| `items[].totalUserCount` | decimal | no | The number of active users or seats across the subscription's active lines. |
| `items[].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. |
| `items[].lines` | array<object> | yes | The subscription's lines, one per product on the subscription, oldest first. An empty array when the subscription has none. GET accounting/subscriptions/:id returns the same lines. GET accounting/subscriptions returns header fields only, without lines. |
| `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` | decimal | no | Quantity across the line's associated sales order product lines. A count, not a currency amount. |
| `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` | date | no | Date service starts for this line (YYYY-MM-DD). |
| `items[].lines[].serviceEndDate` | date | no | Date service ends for this line (YYYY-MM-DD). |
| `items[].lines[].customServiceEndDate` | 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` | date | no | Latest service end date across this line's sales order product lines (YYYY-MM-DD). |
| `items[].lines[].annualRecurringRevenue` | decimal | no | Annualized recurring revenue of this line, in the line currency (see this line's `currency`). |
| `items[].lines[].monthlyRecurringRevenue` | decimal | no | Monthly recurring revenue of this line, in the line currency (see this line's `currency`). |
| `items[].lines[].salesOrders` | array<object> | yes | The sales orders that carry this line, oldest first. An empty array when no sales order carries it. |
| `items[].lines[].salesOrders[].id` | string | yes | The sales order. See id on GET accounting/sales-orders/:id. |
| `items[].lines[].salesOrders[].orderNumber` | string | no | The sales order number. Example: 'SO-1042'. |
| `items[].lines[].salesOrders[].orderType` | string | no | The type of the sales order. Possible values: 'new', 'upsell', 'earlyRenewal', 'renewal', 'replacement'. |
| `items[].lines[].salesOrders[].approvalStatus` | string | no | The approval status of the sales order. Possible values: 'draft', 'pendingApproval', 'revise', 'approved', 'rejected'. |
| `items[].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. |
| `items[].salesOrders[].id` | string | yes | The sales order. See id on GET accounting/sales-orders/:id. |
| `items[].salesOrders[].orderNumber` | string | no | The sales order number. Example: 'SO-1042'. |
| `items[].salesOrders[].orderType` | string | no | The type of the sales order. Possible values: 'new', 'upsell', 'earlyRenewal', 'renewal', 'replacement'. |
| `items[].salesOrders[].approvalStatus` | string | no | The approval status of the sales order. Possible values: 'draft', 'pendingApproval', 'revise', 'approved', 'rejected'. |
| `items[].lastModifiedDate` | date-time | yes | The date and time the subscription last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `pagination` | object | yes | The pagination information 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. |

```json
{
  "data": {
    "items": [
      {
        "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": [
              null
            ]
          }
        ],
        "salesOrders": [
          {
            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "orderNumber": "<orderNumber>",
            "orderType": "<orderType>",
            "approvalStatus": "<approvalStatus>"
          }
        ],
        "lastModifiedDate": "2026-01-15T09:30:00.000Z"
      }
    ],
    "pagination": {
      "nextCursor": "<nextCursor>",
      "hasMore": true
    }
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}
```

## Statuses

- `400` — Invalid request or business failure
- `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