Create usage-based subscriptions
A usage-based subscription is a pricing model that charges merchants continuously based on app use during Shopify's 30-day billing cycle.
Merchants must approve the pricing plan. After accepting the charges, the merchant is redirected to a URL that you provide.
Anchor to RequirementsRequirements
- Your app can make authenticated requests to the GraphQL Admin API.
Anchor to Step 1: Create the subscriptionStep 1: Create the subscription
Make a request to the appSubscriptionCreate
mutation with the following information:
-
terms
Merchants review the terms of the subscription when they accept the pricing plan.
-
cappedAmount
The
cappedAmount
is the maximum that a merchant is billed for during the 30-day billing cycle. ThecurrencyCode
must be one of the supported currencies.
The following mutation is an example:
POST https://{shop}.myshopify.com/api/{api_version}/graphql.json
JSON response
Shopify uses the payload's AppSubscription.id
and the AppSubscriptionLineItem.id
to generate data for app usage records.
Anchor to Step 2: Create an app usage recordStep 2: Create an app usage record
After you've created the usage pricing plan and the merchant has accepted the plan, you can create a usage record with the appUsageRecordCreate
mutation. The usage record needs to include the AppSubscriptionLineItem.id
of the AppSubscription
object that the appSubscriptionCreate
mutation returns.
The following mutation is an example:
POST https://{shop}.myshopify.com/api/{api_version}/graphql.json
GraphQL mutation
JSON response
Anchor to Step 3: Monitor app usage limitsStep 3: Monitor app usage limits
Merchants can use the Shopify admin to change their subscription's capped amount. The capped amount is the maximum amount of usage to bill for within the 30-day billing cycle.
To receive a notification when merchants change the capped amount, subscribe to the GraphQL Admin API's APP_SUBSCRIPTIONS_UPDATE
webhook topic.
To receive a notification when merchants reach or exceed 90% of their capped amount, subscribe to the GraphQL Admin API's APP_SUBSCRIPTIONS_APPROACHING_CAPPED_AMOUNT
webhook topic.
Anchor to Step 4: Monitor subscription status changesStep 4: Monitor subscription status changes
To receive a notification when a subscription status changes, such as when a charge is successful, subscribe to the GraphQL Admin API's APP_SUBSCRIPTIONS_UPDATE
webhook topic.