PApax8
Subscriptions

Get Subscription By ID

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.

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

Path parameters

subscriptionIdstring required
Example:04814f37-bef0-48b7-b388-c04a1e31f889

The ID of any subscription record in the lineage. The response describes the most recent record in that lineage, and its id is the lineage's original subscription ID, which may differ from the value supplied here.

Response

Successful operation

idstring 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.

parentSubscriptionIdstring 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.

currentSubscriptionIdstring 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.

companyIdstring uuid
productIdstring uuid
vendorSubscriptionIdstring

The vendor's unique identifier for this subscription

quantitynumber
startDatestring date-time
endDatestring date-time
createdDatestring 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.

updatedDatestring date-time
billingStartstring 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.

pricenumber

The price for the customer.

currencyCodestring

The currency ISO 4217 code

partnerCostnumber

The price for the Partner.

productNamestring

The name of the product associated with this subscription

billingTerm'Monthly' | 'Annual' | '2-Year' | '3-Year' | 'One-Time' | 'Trial' | 'Activation'
usageEligibleboolean

Indicates whether this subscription's product supports usage-based billing

vendorSkuIdstring

The vendor's unique identifier for the sku associated with this subscription

Example response

{
  "price": 15.39,
  "currencyCode": "USD",
  "partnerCost": 11.39,
  "productName": "Microsoft Office 365 E3",
  "provisioningDetails": [
    {
      "key": "userEmailAddress",
      "description": "Provide the user's email address"
    }
  ],
  "commitmentTerm": {
    "term": "3-Year"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.