Search subscriptions

Operation ID: searchSubscription

Group: Accounting › Subscriptions

Open in the interactive reference

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. 
{
  "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. 
{
  "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