Skip to main content

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

Anchor to Step 1: Create the subscriptionStep 1: Create the subscription

Make a request to the appSubscriptionCreate mutation with the following information:

  • name

  • returnURL

  • 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. The currencyCode 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

{
"data": {
"appSubscriptionCreate": {
"userErrors": [],
"confirmationUrl": "https://{shop}.myshopify.com/admin/charges/4028497976/confirm_recurring_application_charge?signature=BAh7BzoHaWRsKwc4AB7wOhJhdXRvX2FjdGl2YXRlVA%3D%3D--987b3537018fdd69c50f13d6cbd3fba468e0e9a6",
"appSubscription": {
"id": "gid://shopify/AppSubscription/4028497976",
"lineItems": [
{
"id": "gid://shopify/AppSubscriptionLineItem/4028497976?v=1&index=0",
"plan": {
"pricingDetails": {
"__typename": "AppRecurringPricing"
}
}
},
{
"id": "gid://shopify/AppSubscriptionLineItem/4028497976?v=1&index=1",
"plan": {
"pricingDetails": {
"__typename": "AppUsagePricing"
}
}
}
]
}
}
},
...
}

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

mutation {
appUsageRecordCreate(
subscriptionLineItemId: "gid://shopify/AppSubscriptionLineItem/4019585080?v=1&index=0",
description: "Super Mega Plan 1000 emails",
price: {
amount: 1.00,
currencyCode: USD
}
) {
userErrors {
field,
message
},
appUsageRecord {
id
}
}
}

JSON response

{
"data": {
"appUsageRecordCreate": {
"userErrors": [],
"appUsageRecord": {
"id": "gid://shopify/AppUsageRecord/14518231"
}
}
},
...
}

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.

Anchor to Next stepsNext steps

Discounts

Learn about offering subscription discounts.

Capped amount

Learn how to update the maximum amount that merchants can be charged for a subscription.
Was this page helpful?