App
A recurring billing agreement that associates an App with a merchant's shop. Each subscription contains one or more 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 .
Merchants must approve subscriptions through a confirmation URL before billing begins. Test subscriptions allow developers to verify billing flows without actual charges.
Learn more about subscription billing and testing charges.
Anchor to FieldsFields
- Anchor to createdAtcreated•Date
At Time! non-null The date and time when the app subscription was created.
- Anchor to currentPeriodEndcurrent•Date
Period End Time The date and time when the current app subscription period ends. Returns
nullif the subscription isn't active.- •ID!non-null
A globally-unique ID.
- Anchor to lineItemsline•[App
Items Subscription Line Item!]! non-null The plans attached to the app subscription.
- Anchor to namename•String!non-null
The name of the app subscription.
- Anchor to returnUrlreturn•URL!
Url non-null The URL that the merchant is redirected to after approving the app subscription.
- Anchor to statusstatus•App
Subscription Status! non-null The status of the app subscription.
- Anchor to testtest•Boolean!non-null
Specifies whether the app subscription is a test transaction.
- Anchor to trialDaystrial•Int!
Days non-null The number of free trial days, starting at the subscription's creation date, by which billing is delayed.
Anchor to MutationsMutations
- •mutation
Cancels an active app subscription, stopping future billing cycles. The cancellation behavior depends on the
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
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
setting and the app's specific implementation of subscription management.For subscription lifecycle management and cancellation best practices, consult the subscription management guide.
- •mutation
Creates a recurring or usage-based
that charges merchants for app features and services. The subscription includes one or moreobjects that define the pricing structure, billing intervals, and optionalvalues.Returns a confirmation URL 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
to control how this subscription interacts with existing active subscriptions.Learn more about creating app subscriptions.
- •mutation
Updates the capped amount on usage-based billing for an
. 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 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.
- •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
.Learn more about offering free trials.