--- title: AppSubscription - GraphQL Admin description: >- A recurring billing agreement that associates an [`App`](https://shopify.dev/docs/api/admin-graphql/latest/objects/App) with a merchant's shop. Each subscription contains one or more [`AppSubscriptionLineItem`](https://shopify.dev/docs/api/admin-graphql/latest/objects/AppSubscriptionLineItem) objects that define the pricing structure. The pricing structure can include recurring charges, usage-based pricing, or both. The subscription tracks billing details including the current period end date, trial days, and [`AppSubscriptionStatus`](https://shopify.dev/docs/api/admin-graphql/latest/enums/AppSubscriptionStatus). Merchants must approve subscriptions through a [confirmation URL](https://shopify.dev/docs/api/admin-graphql/latest/mutations/appSubscriptionCreate#returns-confirmationUrl) before billing begins. Test subscriptions allow developers to verify billing flows without actual charges. Learn more about [subscription billing](https://shopify.dev/docs/apps/launch/billing/subscription-billing) and [testing charges](https://shopify.dev/docs/apps/launch/billing/managed-pricing#test-charges). api_version: 2025-01 api_name: admin type: object api_type: graphql source_url: html: 'https://shopify.dev/docs/api/admin-graphql/2025-01/objects/AppSubscription' md: >- https://shopify.dev/docs/api/admin-graphql/2025-01/objects/AppSubscription.md --- # App​Subscription object A recurring billing agreement that associates an [`App`](https://shopify.dev/docs/api/admin-graphql/latest/objects/App) with a merchant's shop. Each subscription contains one or more [`AppSubscriptionLineItem`](https://shopify.dev/docs/api/admin-graphql/latest/objects/AppSubscriptionLineItem) objects that define the pricing structure. The pricing structure can include recurring charges, usage-based pricing, or both. The subscription tracks billing details including the current period end date, trial days, and [`AppSubscriptionStatus`](https://shopify.dev/docs/api/admin-graphql/latest/enums/AppSubscriptionStatus). Merchants must approve subscriptions through a [confirmation URL](https://shopify.dev/docs/api/admin-graphql/latest/mutations/appSubscriptionCreate#returns-confirmationUrl) before billing begins. Test subscriptions allow developers to verify billing flows without actual charges. Learn more about [subscription billing](https://shopify.dev/docs/apps/launch/billing/subscription-billing) and [testing charges](https://shopify.dev/docs/apps/launch/billing/managed-pricing#test-charges). ## Fields * created​At [Date​Time!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/DateTime) non-null The date and time when the app subscription was created. * current​Period​End [Date​Time](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/DateTime) The date and time when the current app subscription period ends. Returns `null` if the subscription isn't active. * id [ID!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/ID) non-null A globally-unique ID. * line​Items [\[App​Subscription​Line​Item!\]!](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/AppSubscriptionLineItem) non-null The plans attached to the app subscription. * name [String!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) non-null The name of the app subscription. * return​Url [URL!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/URL) non-null The URL that the merchant is redirected to after approving the app subscription. * status [App​Subscription​Status!](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/AppSubscriptionStatus) non-null The status of the app subscription. * test [Boolean!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Boolean) non-null Specifies whether the app subscription is a test transaction. * trial​Days [Int!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) non-null The number of free trial days, starting at the subscription's creation date, by which billing is delayed. *** ## Map ### Fields and connections with this object * {}[AppInstallation.activeSubscriptions](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/AppInstallation#field-AppInstallation.fields.activeSubscriptions) * {}[AppInstallation.allSubscriptions](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/AppInstallation#field-AppInstallation.fields.allSubscriptions) * <->[AppSubscriptionConnection.nodes](https://shopify.dev/docs/api/admin-graphql/2025-01/connections/AppSubscriptionConnection#returns-nodes) * {}[AppSubscriptionEdge.node](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/AppSubscriptionEdge#field-AppSubscriptionEdge.fields.node) *** ## Mutations * [app​Subscription​Cancel](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/appSubscriptionCancel) mutation Cancels an active app subscription, stopping future billing cycles. The cancellation behavior depends on the `replacementBehavior` setting - it can either disable auto-renewal (allowing the subscription to continue until the end of the current billing period) or immediately cancel with prorated refunds. When a merchant decides to discontinue using subscription features, this mutation provides a clean cancellation workflow that respects billing periods and merchant expectations. Use the `AppSubscriptionCancel` mutation to: * Process merchant-initiated subscription cancellations * Terminate subscriptions due to policy violations or account issues * Handle subscription cancellations during app uninstallation workflows The cancellation timing and merchant access depends on the `replacementBehavior` setting and the app's specific implementation of subscription management. For subscription lifecycle management and cancellation best practices, consult the [subscription management guide](https://shopify.dev/docs/apps/launch/billing/subscription-billing). * [app​Subscription​Create](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/appSubscriptionCreate) mutation Creates a recurring or usage-based [`AppSubscription`](https://shopify.dev/docs/api/admin-graphql/latest/objects/AppSubscription) that charges merchants for app features and services. The subscription includes one or more [`AppSubscriptionLineItem`](https://shopify.dev/docs/api/admin-graphql/latest/objects/AppSubscriptionLineItem) objects that define the pricing structure, billing intervals, and optional [`AppSubscriptionDiscount`](https://shopify.dev/docs/api/admin-graphql/latest/objects/AppSubscriptionDiscount) values. Returns a [confirmation URL](https://shopify.dev/docs/api/admin-graphql/latest/mutations/appSubscriptionCreate#returns-confirmationUrl) where the merchant approves or declines the charges. After approval, the subscription becomes active and billing begins after any trial period expires. You can specify [`AppSubscriptionReplacementBehavior`](https://shopify.dev/docs/api/admin-graphql/latest/enums/AppSubscriptionReplacementBehavior) to control how this subscription interacts with existing active subscriptions. Learn more about [creating app subscriptions](https://shopify.dev/docs/apps/launch/billing/subscription-billing/create-time-based-subscriptions). * [app​Subscription​Line​Item​Update](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/appSubscriptionLineItemUpdate) mutation Updates the capped amount on usage-based billing for an [`AppSubscriptionLineItem`](https://shopify.dev/docs/api/admin-graphql/latest/objects/AppSubscriptionLineItem). Enables you to modify the maximum charge limit that prevents merchants from exceeding a specified threshold during their billing period. The mutation returns a [confirmation URL](https://shopify.dev/docs/api/admin-graphql/latest/mutations/appSubscriptionCreate#returns-confirmationUrl) where the merchant must approve the new pricing limit before it takes effect. Use this when adjusting usage limits based on merchant needs or changing pricing models. Learn more about [updating the maximum charge for a subscription](https://shopify.dev/docs/apps/launch/billing/subscription-billing/update-max-charge). * [app​Subscription​Trial​Extend](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/appSubscriptionTrialExtend) mutation Extends the trial period for an existing app subscription. Trial extensions give merchants additional time to use the app before committing to paid billing. Requires the subscription ID and the number of days to extend (between one and 1000). The extension modifies the existing trial end date, allowing continued access to subscription features without immediate billing. Returns the updated [`AppSubscription`](https://shopify.dev/docs/api/admin-graphql/latest/objects/AppSubscription). Learn more about [offering free trials](https://shopify.dev/docs/apps/launch/billing/offer-free-trials). *** ## <\~> AppSubscription Mutations ### Mutated by * <\~>[app​Subscription​Cancel](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/appSubscriptionCancel) * <\~>[app​Subscription​Create](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/appSubscriptionCreate) * <\~>[app​Subscription​Line​Item​Update](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/appSubscriptionLineItemUpdate) * <\~>[app​Subscription​Trial​Extend](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/appSubscriptionTrialExtend) *** ## Interfaces * [Node](https://shopify.dev/docs/api/admin-graphql/2025-01/interfaces/Node) interface *** ## ||-AppSubscription Implements ### Implements * ||-[Node](https://shopify.dev/docs/api/admin-graphql/2025-01/interfaces/Node)