Skip to main content
Retrieves detailed information about a specific subscription.

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
      }
    }
  }
}

Parameters

input
GetSubscriptionInput
required
Input parameters for retrieving the subscription

Return Type

Returns a CustomerSubscription object with:
FieldTypeDescription
subscriptionIdStringUnique subscription identifier
statusSubscriptionStatusACTIVE, IN_TRIAL, CANCELED, EXPIRED, NOT_STARTED
startDateDateTimeWhen subscription started
endDateDateTimeWhen subscription ends (if set)
trialEndDateDateTimeTrial end date (if in trial)
cancellationDateDateTimeWhen cancellation was requested
currentBillingPeriodStartDateTimeCurrent period start
currentBillingPeriodEndDateTimeCurrent period end
planPlanThe subscribed plan
addons[SubscriptionAddon]Applied addons with quantities
prices[Price]Subscription pricing
customerCustomerAssociated customer
paymentCollectionPaymentCollectionPayment status
couponCouponApplied coupon (if any)
scheduledUpdates[ScheduledUpdate]Pending scheduled changes

Subscription Status Values

StatusDescription
ACTIVESubscription is active and paid
IN_TRIALSubscription is in trial period
CANCELEDSubscription has been canceled
EXPIREDTrial or subscription has expired
NOT_STARTEDScheduled subscription not yet started
PAYMENT_PENDINGAwaiting payment

Common Use Cases

Show current plan, pricing, and renewal date on account pages.
Determine if user is in trial and when it expires.
Display any scheduled updates (plan changes, cancellations).