---
title: "Get Subscription By ID"
method: GET
path: "/subscriptions/{subscriptionId}"
tags: ["Subscriptions"]
---

# Get Subscription By ID

`GET /subscriptions/{subscriptionId}`

## Request

- Base URL: `https://api.pax8.com/v1`
- URL: `https://api.pax8.com/v1/subscriptions/{subscriptionId}`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://token-manager.pax8.com/oauth/token`

Returns the current state of a subscription.

Subscriptions are versioned. Each change to a subscription — quantity, billing term,
price, or product — creates a new subscription record that belongs to the same lineage
as the original. You may supply the ID of **any** record in that lineage; this endpoint
always resolves to the most recent record in it.

Because of this, the `id` in the response is the lineage's *original* subscription ID,
which may differ from the `subscriptionId` you supplied. This is expected and does not
indicate an error. The original subscription ID is stable for the life of the
subscription, so prefer it when storing a reference.

To see every record in the lineage, including the one matching the ID you supplied, pass
the `id` from this response to `GET /subscriptions/{subscriptionId}/history`.

Returns `404` if no subscription matches the supplied `subscriptionId`.

## Path parameters

- `subscriptionId` string, required

## Response `200`

Successful operation

- Subscription
  - `id` string, uuid: The original subscription ID for this lineage. This value is stable for the life of the subscription and is not changed by modifications, so prefer it when storing a reference. It may differ from the `subscriptionId` supplied in a request path when that ID belongs to a later record in the same lineage.
  - `parentSubscriptionId` string, uuid: The original subscription ID of this subscription's parent, for products that use a parent/child structure. Omitted when the subscription has no parent.
  - `currentSubscriptionId` string, uuid: The subscription ID of the record currently active in this lineage — the one with no end date, or whose end date has not yet passed. Because `id` above is always the lineage's *original* subscription ID, use `currentSubscriptionId` to tell at a glance whether the record you looked up is still the one in effect. Equals `id` when the subscription has never been modified.
  - `companyId` string, uuid
  - `productId` string, uuid
  - `vendorSubscriptionId` string: The vendor's unique identifier for this subscription
  - `quantity` number
  - `startDate` string, date-time
  - `endDate` string, date-time
  - `createdDate` string, date-time: The date the *original* subscription in this lineage was created. Because the remaining fields describe the most recent record in the lineage, `createdDate` can be earlier than `startDate` for a subscription that has been modified.
  - `updatedDate` string, date-time
  - `billingStart` string, date
  - `status` 'Active' | 'Cancelled' | 'PendingManual' | 'PendingAutomated' | 'PendingCancel' | 'WaitingForDetails' | 'Trial' | 'Converted' | 'PendingActivation' | 'Activated': Subscription Status : * `Active` - Provisioning request complete * `Cancelled` - Deprovisioning request complete * `PendingManual` - An associated manual provisioning task isn't started/completed * `PendingAutomated` - An associated automated provisioning task isn't started/completed * `PendingCancel` - Deprovisioning request pending * `WaitingForDetails` - Provisioning details are missing * `Trial` - Trial subscriptions offer free or discounted access for a limited time. * `Converted` - Converted from trial * `PendingActivation` - Requires Activation but has not yet been activated * `Activated` - Requires Activation and has been activated Activation is required for a small subset of products. Billing services do not begin for these products until "activation" is complete.
  - `price` number: The price for the customer.
  - `currencyCode` string: The currency ISO 4217 code
  - `partnerCost` number: The price for the Partner.
  - `productName` string: The name of the product associated with this subscription
  - `billingTerm` 'Monthly' | 'Annual' | '2-Year' | '3-Year' | 'One-Time' | 'Trial' | 'Activation'
  - `provisioningDetails` ProvisioningDetail[]
    - `label` string: The label to display
    - `key` string: The key
    - `values` string[]: A list of values based on the ```valuetype``` and ```possibleValues```
    - `description` string: Instructions and context to help enter the required provisioning information
    - `valueType` 'Input' | 'Single-Value' | 'Multi-Value': Provisioning Detail Value Type: * `Input` - A value that is supplied by a user * `Single-Value` - A single value that is picked from the `possibleValues` list * `Multi-Value` - One or multiple values that are picked from the `possibleValues` list
    - `possibleValues` string[]: A list of possible values. `possibleValues` will be null when `valueType` is `Input`
  - `commitmentTerm` SubscriptionCommitment
    - `id` string, uuid: Unique identifier for the commitment record
    - `term` string: Duration of the commitment
    - `endDate` string, date-time
  - `usageEligible` boolean: Indicates whether this subscription's product supports usage-based billing
  - `vendorSkuId` string: The vendor's unique identifier for the sku associated with this subscription

## Other responses

- `404`: Subscription not found

---

[API](https://skmtc.dev/pax8/apis/partner-endpoints.md) - [All operations](https://skmtc.dev/pax8/apis/partner-endpoints/llms.txt) - [OpenAPI document](https://skmtc.dev/pax8/apis/partner-endpoints/revisions/f90cec5b4720?raw)