Shopify App Pricing

Shopify App Pricing lets you define your app's pricing plans directly in the app submission form, without needing to use the Billing API. Shopify hosts your app's plan selection page, and automates most common billing tasks, such as recurring charges, usage-based pricing, free trials, proration, test charges, and price updates.

For most developers, Shopify App Pricing is simpler and more consistent than coding your own billing logic using the Billing API.

Anchor to Pricing modelsPricing models

Shopify App Pricing supports the following billing models:

• Recurring charges: Bill merchants on a regular schedule with free, monthly, yearly, or monthly-with-yearly-discount plans. Learn more about setting up subscription charges.
• Usage-based pricing: Charge merchants based on actual usage using fixed, graduated, or volume pricing structures. Learn more about setting up usage charges.
• Combined pricing: Combine recurring fees with usage-based charges for hybrid plans. Learn more about combined subscription and usage.

You can also configure free trials, public and private plans, and welcome links for each plan.

Anchor to Set up Shopify App PricingSet up Shopify App Pricing

Shopify App Pricing is the default option when you submit a new public app for approval. Existing apps without active paid merchants can opt into Shopify App Pricing by selecting the option. This will be available for all developers soon. Learn more about migrating.

Anchor to Opt in to Shopify App PricingOpt in to Shopify App Pricing

If you've already created plans with the Billing API that aren't compatible with Shopify App Pricing, then you'll need to remove them before you can switch.

1. From your Partner Dashboard, click Apps > All Apps and click the name of the app you want to update pricing for.
2. Click Distribution.
3. Beside Shopify App Store listing, click Manage listing.
4. Under Published languages, click Edit for the locale you want to update.
5. Under Pricing content, click Manage to open the Pricing index page.
6. Click Settings.
7. Select Shopify App Pricing.
8. In the confirmation dialog, click Switch.

Anchor to Plan selection pagePlan selection page

When using Shopify App Pricing, Shopify hosts your plan selection page. It's visible in the Shopify admin, and allows merchants to view and select their plan.

Your app's plan selection page URL follows this pattern:

Learn how to redirect merchants to the plan selection page in your app.

Anchor to Redirection URLRedirection URL

The redirection URL is where merchants are redirected after approving your app plan charge. You can configure welcome links on a per-plan basis to customize your app onboarding experience.

• Apps with a landing page in App Home: Specify a relative path to your app root, such as /welcome. Your plan_handle URL parameter is appended to all redirect URLs which is a plan that merchant is subscribed to.
• Apps without a landing page in App Home: Redirect to a valid URL (including the http or https protocol). URL parameters for the plan_handle and the merchant shop domain are appended to redirect URLs.

After a merchant approves a charge, query the Partner API to confirm the subscription status. See query subscription data for details. If you enrolled before April 2026, refer to legacy Billing API queries.

Anchor to TestingTesting

Anchor to Test planTest plan

Shopify App Pricing includes a $0 private test plan that you can use to configure and test your billing integration without charging merchants. The test plan is available in the Private plans section of your app's pricing configuration in the Partner Dashboard. Use it to verify that your usage meters, welcome links, and billing events work correctly before publishing a public plan.

Anchor to Testing your plan selection UITesting your plan selection UI

You can validate that plan selection works as expected by following the test charge documentation.

Anchor to Query subscription dataQuery subscription data

With Shopify App Pricing, you use the Partner API to retrieve both a merchant's current subscription status and their subscription history. This is different from the Billing API, where subscription status comes from the GraphQL Admin API.

For Partner API setup — including authentication, creating a Partner API client, rate limits, and error handling — see the Partner API technical reference.

Anchor to Subscription statusSubscription status

Query activeSubscription(appId:, shopId:) on the Partner API to get a merchant's current subscription, including the active plan, billing period, current billing cycle, subscription items (with pricing and usage), discounts, and any pending updates. This is the canonical way to check "what is this merchant subscribed to right now?" — the query returns the live contract state, not a derived view of historical events.

query ActiveSubscription($appId: ID!, $shopId: ID!) {
  activeSubscription(appId: $appId, shopId: $shopId) {
    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
        remainingDiscountCycles
      }
      usage {
        quantity
        cost {
          amount
          currencyCode
        }
      }
    }
    pendingUpdate {
      billingPeriod
      items {
        handle
      }
    }
  }
}

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

activeSubscription returns null when the shop doesn't have an active Shopify App Pricing contract for the app. It only works for public apps.

For full field reference, including trial behavior, pending updates, and legacy subscription IDs, see Active Subscription in the Partner API docs.

Anchor to App / subscription historyApp / subscription history

Use the root events query on the Partner API to retrieve your app's event history across all merchants — installs, uninstalls, plan changes, cancellations, freezes, charges, earnings, and credits. The query returns events in reverse chronological order by default. Filter by subjectId and shopId to scope results to a specific app and merchant.

Filter by event types to get just the information you need:

{
  events(
    filter: {
      eventTypes: [
        SUBSCRIPTION_CREATED,
        SUBSCRIPTION_UPDATED,
        SUBSCRIPTION_CANCELLATION_SCHEDULED,
        SUBSCRIPTION_CANCELED,
        SUBSCRIPTION_FROZEN,
        SUBSCRIPTION_UNFROZEN
      ]
    }
    first: 10
  ) {
    edges {
      node {
        id
        eventType
        ... on SubscriptionStatus {
          state
          cancelEffectiveOn
          plan {
            handle
            billingPeriod
            trialDays
            trialDaysRemaining
            prices {
              currencyCode
              ... on FlatRatePlanPrice {
                amount
              }
              ... on TieredPlanPrice {
                tiersMode
                tiers {
                  upTo
                  amountPerUnit
                  amount
                }
              }
            }
          }
        }
      }
    }
  }
}

{
  events(
    filter: {
      subjectId: "gid://shopify/App/1234"
      shopId: "gid://shopify/Shop/5678"
    }
    first: 10
  ) {
    edges {
      node {
        id
        occurredAt
        eventType
        shop {
          id
          myshopifyDomain
        }
      }
    }
  }
}

The following event types track subscription lifecycle changes:

To get a merchant's complete app event history, omit eventTypes from the filter — all event types are returned. To restrict to app events only, set subjectType: APP in the filter. If you filter by shopId, you must also provide subjectId (the app GID). By default the events query returns the last 30 days — use occurredAtMin and occurredAtMax to widen the window (maximum range is 365 days). The page size limit is 250; use cursor-based pagination with first and after to page through results. See Historical Events for the full filter reference.

Anchor to Subscription change notificationsSubscription change notifications

Shopify App Pricing doesn't use webhooks to notify your app of subscription changes. Instead, Shopify passes subscription details as URL parameters when a merchant is redirected from the plan selection or charge confirmation page to your app's redirection URL.

This replaces the following webhook topics used by the Billing API:

Anchor to URL redirect parametersURL redirect parameters

When a merchant selects or confirms a plan, Shopify redirects them to your configured redirection URL with the following parameters appended:

Use these parameters to confirm the subscription status by querying the Partner API when your app handles the redirect.

For subscription lifecycle events that don't involve a merchant redirect — such as cancellations, freezes, or plan expirations — query the Partner API to check the current subscription state.

Anchor to LimitationsLimitations

• Shopify App Pricing currently supports the following pricing models:
  • Fixed recurring charges (for example, $10/month or $100/year)
  • Usage-based pricing with fixed, graduated, or volume pricing
  • Combinations of monthly recurring charges with usage-based pricing
• Once you opt in to Shopify App Pricing, you can't create new recurring application charges using the Billing API. Charges created before opting into Shopify App Pricing continue to process as expected.
• Usage-based pricing has the following limitations:
  • You can create up to five active usage meters per plan
  • You can define up to six pricing tiers per usage meter
  • Usage charges must be billed monthly (can't be combined with yearly-only plans)
  • Usage caps aren't currently supported
• When testing a draft app during development, its plan selection page might return a 404 error if the development store and the app listing are set to different locales. This issue doesn't affect production stores or published apps.

Anchor to Partner API event typesPartner API event types

The Partner API has two separate event type systems with different naming conventions. Make sure you're using the correct one for your query.

Anchor to [object Object], — used by ,[object Object], (recommended)EventType — used by QueryRoot.events (recommended)

The events query at the query root uses the EventType enum. This is the recommended approach for Shopify App Pricing and provides subscription lifecycle tracking, charge events, and earning events.

Use the events query with the EventFilterInput eventTypes field to filter by specific event types, as shown in query subscription data.

Anchor to [object Object], — used by ,[object Object], (legacy)AppEventTypes — used by App.events (legacy)

The older App.events field uses the AppEventTypes enum with a different naming convention. These event types use a more granular naming pattern for charge lifecycle states (accepted, activated, declined, expired).

Anchor to For apps enrolled before April 2026For apps enrolled before April 2026

Anchor to Webhook-based subscription notificationsWebhook-based subscription notifications

Before April 28, 2026, you can receive a webhook when a subscription is updated by registering for the APP_SUBSCRIPTIONS_UPDATE topic. Note that webhooks can take several minutes to deliver. Make sure your app can handle webhook delays and follow Shopify's best practices for webhooks.

After April 28, 2026, Shopify App Pricing no longer sends webhooks for subscription changes. Use the Partner API and URL redirect parameters instead.

Anchor to Billing API subscription status queriesBilling API subscription status queries

Before April 28, 2026, you can query the Billing API for subscription status after a merchant approves a charge. After April 28, 2026, use the Partner API to confirm subscription status.

Anchor to Test chargesTest charges

Before April 28, 2026, Shopify App Pricing supports free testing for dev stores. When a development store subscribes to a plan, Shopify creates a test subscription for that store. Your account isn't charged for test subscriptions.

After April 28, 2026, use the $0 private test plan to test your billing integration instead.