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
- createdAt (DateTime!)
- currentPeriodEnd (DateTime)
- id (ID!)
- lineItems ([AppSubscriptionLineItem!]!)
- name (String!)
- returnUrl (URL!)
- status (AppSubscriptionStatus!)
- test (Boolean!)
- trialDays (Int!)
- 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
- appSubscriptionCancel (AppSubscriptionCancelPayload)
- appSubscriptionCreate (AppSubscriptionCreatePayload)
- appSubscriptionLineItemUpdate (AppSubscriptionLineItemUpdatePayload)
- appSubscriptionTrialExtend (AppSubscriptionTrialExtendPayload)
- •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.
- •ID!required
The ID of the app subscription to be cancelled.
- Anchor to prorateprorate•BooleanDefault:false
Whether to issue prorated credits for the unused portion of the app subscription. There will be a corresponding deduction (based on revenue share) to your Partner account. For example, if a $10.00 app subscription (with 0% revenue share) is cancelled and prorated half way through the billing cycle, then the merchant will be credited $5.00 and that amount will be deducted from your Partner account.
Arguments
- •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.
- Anchor to namename•String!required
A descriptive name for the app subscription.
- Anchor to lineItemsline•[App
Items Subscription Line Item Input!]! required Attaches one or more pricing plans to an app subscription. Only one pricing plan can be defined for each available type.
- Anchor to testtest•BooleanDefault:false
Whether the app subscription is a test transaction.
- Anchor to trialDaystrial•Int
Days The number of days of the free trial period, beginning on the day that the merchant approves the app charges.
- Anchor to returnUrlreturn•URL!
Url required The URL pointing to the page where the merchant is redirected after approving the app subscription.
- Anchor to replacementBehaviorreplacement•App
Behavior Subscription Replacement Behavior Default:STANDARD The replacement behavior when creating an app subscription for a merchant with an already existing app subscription.
Arguments
- •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.
- •ID!required
The ID of the app subscription line item to be updated.
- Anchor to cappedAmountcapped•Money
Amount Input! required The new maximum amount of usage charges that can be incurred within a subscription billing interval.
Arguments
- •ID!
- •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.
- •ID!required
The ID of the app subscription to extend the trial for.
- Anchor to daysdays•Int!required
The number of days to extend the trial. The value must be greater than 0 and less than or equal to 1000.
Arguments
- •ID!