Active subscription

Use activeSubscription to retrieve the active 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:

Anchor to Access requirementsAccess requirements

• The API client must have the Manage apps permission. See 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.

Anchor to ExampleExample

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

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

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

Anchor to Pricing typesPricing types

The price field on each subscription item implements the Price interface and resolves to one of two concrete types:

• FlatRatePrice: A recurring flat rate. Exposes amount and currency.
• 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 to read the quantity and calculated cost for the current billing cycle.

Anchor to TrialsTrials

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.

Anchor to Pending updatesPending 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.

Anchor to Legacy subscription IDsLegacy subscription IDs

legacySubscriptionId returns the GraphQL Admin API 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.

Anchor to Error handlingError handling