> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stigg.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Subscription

Retrieves detailed information about a specific subscription.

## Query

<CodeGroup>
  ```graphql Query theme={null}
  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
        }
      }
    }
  }
  ```

  ```json Variables theme={null}
  {
    "input": {
      "subscriptionId": "sub-456"
    }
  }
  ```

  ```json Response theme={null}
  {
    "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": []
      }
    }
  }
  ```
</CodeGroup>

## Parameters

<ParamField body="input" type="GetSubscriptionInput" required>
  Input parameters for retrieving the subscription

  <Expandable title="properties">
    <ParamField body="subscriptionId" type="String" required>
      The unique subscription ID
    </ParamField>

    <ParamField body="environmentId" type="UUID">
      The environment ID. If not provided, uses the environment from your API key.
    </ParamField>
  </Expandable>
</ParamField>

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

<AccordionGroup>
  <Accordion title="Display subscription details">
    Show current plan, pricing, and renewal date on account pages.
  </Accordion>

  <Accordion title="Check trial status">
    Determine if user is in trial and when it expires.
  </Accordion>

  <Accordion title="Show pending changes">
    Display any scheduled updates (plan changes, cancellations).
  </Accordion>
</AccordionGroup>

## Related Operations

* [List Subscriptions](/api-and-sdks/api-reference/queries/list-subscriptions) - Query multiple subscriptions
* [Get Active Subscriptions](/api-and-sdks/api-reference/queries/get-active-subscriptions) - Get active subscriptions for a customer
* [Update Subscription](/api-and-sdks/api-reference/mutations/update-subscription) - Modify subscription
* [Cancel Subscription](/api-and-sdks/api-reference/mutations/cancel-subscription) - Cancel subscription