---
title: Active subscription
description: Query the active managed pricing subscription for a specific shop using the Partner API.
api_version: 2026-07
api_name: partner
source_url:
  html: https://shopify.dev/docs/api/partner/2026-07/active-subscription
  md: https://shopify.dev/docs/api/partner/2026-07/active-subscription.md
---

# Active subscription

**Release candidate:**

The `activeSubscription` query and all supporting types are available in the `2026-07` release candidate and `unstable`.

Use `activeSubscription` to retrieve the active [Shopify App Pricing](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing) subscription for a specific shop. This query returns the current plan, billing period, current billing cycle, subscription items (including pricing and usage), any discounts, and any pending updates that will be applied at the next billing cycle.

`activeSubscription` is a root query on the Partner API and takes required `appId` and `shopId` arguments:

```graphql
activeSubscription(appId: ID!, shopId: ID!): ActiveSubscription
```

***

## Access requirements

* The API client must have the **Manage apps** permission. See [Create a Partner API client](https://shopify.dev/docs/api/partner/%7BAPI_VERSION%7D#create-a-partner-api-client).
* The app must be a public app. Custom and private apps aren't supported.
* The shop must have an active managed pricing contract for the app. If no contract exists, `activeSubscription` returns `null`.

***

## Example

## Active subscription

##### Query

```graphql
query ActiveSubscription($appId: ID!, $shopId: ID!) {
  activeSubscription(appId: $appId, shopId: $shopId) {
    shop {
      id
      myshopifyDomain
    }
      billingPeriod
      cancelAtEndOfCycle
      trialEndsAt
      currentBillingCycle {
        startTime
        endTime
      }
      items {
        handle
        description
        price {
          __typename
          active
          currency
          ... on FlatRatePrice {
            amount
          }
          ... on TieredPrice {
            tiersMode
            tiers {
              upTo
              amountPerUnit
              amount
            }
          }
        }
        discount {
          amount
          percentage
          originalDiscountCycles
          remainingDiscountCycles
          discountEndsAt
        }
        usage {
          quantity
          cost {
            amount
            currencyCode
          }
        }
      }
    pendingUpdate {
      billingPeriod
      items {
        handle
        price {
          __typename
          ... on FlatRatePrice {
            amount
          }
        }
      }
      legacySubscriptionId
    }
    legacySubscriptionId
  }
}
```

##### Variables

```json
{
  "appId": "gid://shopify/App/1234",
  "shopId": "gid://shopify/Shop/5678"
}
```

##### Response

```json
{
  "data": {
    "activeSubscription": {
      "shop": { "id": "gid://shopify/Shop/5678", "myshopifyDomain": "example.myshopify.com" },
        "billingPeriod": "EVERY_30_DAYS",
        "cancelAtEndOfCycle": false,
        "trialEndsAt": null,
        "currentBillingCycle": {
          "startTime": "2026-04-01T00:00:00Z",
          "endTime": "2026-05-01T00:00:00Z"
        },
        "items": [
          {
            "handle": "pro_plan",
            "description": "Pro plan",
            "price": {
              "__typename": "FlatRatePrice",
              "active": true,
              "currency": "USD",
              "amount": "29.00"
            },
            "discount": null,
            "usage": null
          }
        ],
      "pendingUpdate": null,
      "legacySubscriptionId": "gid://shopify/AppSubscription/987654321"
    }
  }
}
```

***

## Pricing types

The `price` field on each subscription item implements the [`Price`](https://shopify.dev/docs/api/partner/%7BAPI_VERSION%7D/interfaces/Price) interface and resolves to one of two concrete types:

* **[`FlatRatePrice`](https://shopify.dev/docs/api/partner/%7BAPI_VERSION%7D/objects/FlatRatePrice)**: A recurring flat rate. Exposes `amount` and `currency`.
* **[`TieredPrice`](https://shopify.dev/docs/api/partner/%7BAPI_VERSION%7D/objects/TieredPrice)**: Usage-based pricing with tiers. Exposes `currency`, `tiersMode` (`VOLUME` or `GRADUATED`), and an array of `tiers` (each with `upTo`, `amountPerUnit`, and `amount`).

For tiered items, use the `usage` field on [`SubscriptionItem`](https://shopify.dev/docs/api/partner/%7BAPI_VERSION%7D/objects/SubscriptionItem) to read the quantity and calculated cost for the current billing cycle.

***

## Trials

While a subscription is in its trial period, `currentBillingCycle` is `null` and `trialEndsAt` is set to the end of the trial. After the trial ends, `trialEndsAt` becomes `null` and `currentBillingCycle` is populated.

***

## Pending updates

If the merchant has scheduled a plan change, `pendingUpdate` contains the items that are active at the start of the next billing cycle. If no update is scheduled, `pendingUpdate` is `null`.

***

## Legacy subscription IDs

`legacySubscriptionId` returns the GraphQL Admin API [`AppSubscription`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/AppSubscription) GID for subscriptions that were created via the Billing API and migrated to managed pricing. For subscriptions created natively in managed pricing, this field is `null`.

***

## Error handling

| Condition | Behavior |
| - | - |
| App is not a public app | Returns a GraphQL execution error: `Only public apps can access active subscription` |
| Shop not found | Returns a GraphQL execution error: `Shop not found` |
| No active contract for the shop | Returns `null` for `activeSubscription` |
| Feature not enabled for the organization | Returns a GraphQL execution error |

***