Get Subscription

Retrieves detailed information about a specific subscription.

Query

Query

query GetSubscription($input: GetSubscriptionInput!) {
  getSubscription(input: $input) {
    subscriptionId
    status
    startDate
    endDate
    trialEndDate
    cancellationDate
    currentBillingPeriodStart
    currentBillingPeriodEnd
    billingCycleAnchor
    plan {
      refId
      displayName
      pricingType
    }
    addons {
      addon {
        refId
        displayName
      }
      quantity
    }
    prices {
      billingModel
      billingPeriod
      price {
        amount
        currency
      }
    }
    customer {
      customerId
      name
    }
    paymentCollection
    coupon {
      code
      discountValue
      type
    }
    scheduledUpdates {
      scheduledExecutionTime
      targetPlan {
        refId
      }
    }
  }
}

{
  "input": {
    "subscriptionId": "sub-456"
  }
}

{
  "data": {
    "getSubscription": {
      "subscriptionId": "sub-456",
      "status": "ACTIVE",
      "startDate": "2024-01-15T00:00:00Z",
      "endDate": null,
      "trialEndDate": null,
      "cancellationDate": null,
      "currentBillingPeriodStart": "2024-01-15T00:00:00Z",
      "currentBillingPeriodEnd": "2024-02-15T00:00:00Z",
      "billingCycleAnchor": "2024-01-15T00:00:00Z",
      "plan": {
        "refId": "plan-pro",
        "displayName": "Pro Plan",
        "pricingType": "PAID"
      },
      "addons": [
        {
          "addon": {
            "refId": "addon-seats",
            "displayName": "Extra Seats"
          },
          "quantity": 5
        }
      ],
      "prices": [
        {
          "billingModel": "FLAT_FEE",
          "billingPeriod": "MONTHLY",
          "price": {
            "amount": 99,
            "currency": "USD"
          }
        }
      ],
      "customer": {
        "customerId": "customer-123",
        "name": "Acme Corp"
      },
      "paymentCollection": "PAID",
      "coupon": null,
      "scheduledUpdates": []
    }
  }
}

Parameters

input · GetSubscriptionInput · required

Input parameters for retrieving the subscription

Show properties

subscriptionId · String · required

The unique subscription ID

environmentId · UUID

The environment ID. If not provided, uses the environment from your API key.

Return Type

Returns a CustomerSubscription object with:

Field	Type	Description
subscriptionId	String	Unique subscription identifier
status	SubscriptionStatus	ACTIVE, IN_TRIAL, CANCELED, EXPIRED, NOT_STARTED
startDate	DateTime	When subscription started
endDate	DateTime	When subscription ends (if set)
trialEndDate	DateTime	Trial end date (if in trial)
cancellationDate	DateTime	When cancellation was requested
currentBillingPeriodStart	DateTime	Current period start
currentBillingPeriodEnd	DateTime	Current period end
plan	Plan	The subscribed plan
addons	[SubscriptionAddon]	Applied addons with quantities
prices	[Price]	Subscription pricing
customer	Customer	Associated customer
paymentCollection	PaymentCollection	Payment status
coupon	Coupon	Applied coupon (if any)
scheduledUpdates	[ScheduledUpdate]	Pending scheduled changes

Subscription Status Values

Status	Description
ACTIVE	Subscription is active and paid
IN_TRIAL	Subscription is in trial period
CANCELED	Subscription has been canceled
EXPIRED	Trial or subscription has expired
NOT_STARTED	Scheduled subscription not yet started
PAYMENT_PENDING	Awaiting payment

Common Use Cases

Display subscription details

Show current plan, pricing, and renewal date on account pages.

Check trial status

Determine if user is in trial and when it expires.

Show pending changes

Display any scheduled updates (plan changes, cancellations).

Related Operations

• List Subscriptions - Query multiple subscriptions
• Get Active Subscriptions - Get active subscriptions for a customer
• Update Subscription - Modify subscription
• Cancel Subscription - Cancel subscription