Retrieve a subscription

Operation ID: getSubscription

Group: Accounting › Subscriptions

Open in the interactive reference

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