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

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:

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