Manage subscriptions with the Billing API
Shopify offers billing features to help you manage subscriptions. The following sections cover how you can manage subscriptions using the GraphQL Admin API.
Free trials
Free trials allow merchants to experiment with apps before making a commitment to pay. Free trials delay the start of an app’s billing cycle by the number of days specified. Free trials are available only to merchants if they agree to a new subscription, and therefore cannot be added to existing subscriptions.
You can use the appSubscriptionCreate
mutation to add a free trial. You add the trialDays
argument to the mutation's input:
mutation {
appSubscriptionCreate(
name: "Super Duper Recurring Plan"
trialDays: 7
returnUrl: "http://super-duper.shopifyapps.com"
lineItems: [{
plan: {
appRecurringPricingDetails: {
price: { amount: 10.00, currencyCode: USD }
}
}
}]
) {
userErrors {
field
message
}
confirmationUrl
appSubscription {
id
}
}
}
JSON response:
{
"data": {
"appSubscriptionCreate": {
"userErrors": [],
"confirmationUrl": "https://domain.myshopify.com/admin/charges/4019650616/confirm_recurring_application_charge?signature=BAh7BzoHaWRsKwc4AJfvOhJhdXRvX2FjdGl2YXRlVA%3D%3D--53ccfd382d394baf9878bab49e83e2ba3b94c580",
"appSubscription": {
"id": "gid://shopify/AppSubscription/4019650616"
}
}
},
...
}
Updating the capped amount
If you try to create a usage record for a usage pricing plan with an amount less than the new usage record, then the request will fail. You need to increase the capped amount and obtain merchant approval before you can create more usage records.
You can query for the ID of the created AppSubscription
to see the cappedAmount
and balanceUsed
fields.
query {
node(id: "gid://shopify/AppSubscription/4019585080") {
...on AppSubscription {
lineItems {
plan {
pricingDetails {
...on AppUsagePricing {
terms
cappedAmount {
amount
currencyCode
}
balanceUsed {
amount
currencyCode
}
}
}
}
}
}
}
}
JSON response:
{
"data": {
"node": {
"lineItems": [
{
"plan": {
"pricingDetails": {
"terms": "$1 for 100 emails",
"cappedAmount": {
"amount": "20.0",
"currencyCode": "USD"
},
"balanceUsed": {
"amount": "0.0",
"currencyCode": "USD"
}
}
}
}
]
}
},
...
}
To increase the capped amount you can use the appSubscriptionLineItemUpdate
mutation:
mutation {
appSubscriptionLineItemUpdate(
id: "${AppSubscriptionLineItemUsagePricing_gid}"
cappedAmount: { amount: 100.00, currencyCode: USD }
) {
userErrors {
field
message
}
confirmationUrl
appSubscription {
id
}
}
}
JSON response:
The response includes the new confirmationUrl
and appSubscription id
.
{
"data": {
"appSubscriptionLineItemUpdate": {
"userErrors": [],
"confirmationUrl": "https://domain.myshopify.com/admin/charges/4019585080/confirm_update_capped_amount?signature=BAh7BzoHaWRsKwc4AJbvOhJhdXRvX2FjdGl2YXRlRg%3D%3D--a93b35054feb213f04f1ee35ef5b569617ce6823",
"appSubscription": {
"id": "gid://shopify/AppSubscription/4019585080"
}
}
},
...
}
Canceling subscriptions
When a merchant uninstalls your app, their app subscription is automatically canceled. However, you might also want to cancel an app subscription on behalf of the merchant.
To cancel a subscription, you can use the appSubscriptionCancel
mutation:
mutation {
appSubscriptionCancel(
id: "gid://shopify/AppSubscription/4019585080"
) {
userErrors {
field
message
}
appSubscription {
id
status
}
}
}
JSON response:
The response returns the ID of the canceled subscription.
{
"data": {
"appSubscriptionCancel": {
"userErrors": [],
"appSubscription": {
"id": "gid://shopify/AppSubscription/4019585080",
"status": "CANCELLED"
}
}
},
...
}
Understanding upgrades and downgrades
Merchants are only permitted to have one subscription to your app at a time. This means if a merchant upgrades or downgrades your app, the old subscription is canceled and is replaced with the new one. When the merchant upgrades or downgrades the app, the new subscription takes the same 30-day app billing cycle as the previous purchase. This also applies when a merchant un-installs and re-installs an app.

If the new subscription includes trial days, the merchant is still charged on the beginning of the next 30-day app billing cycle, but the bill includes a prorated credit to account for the trial days.

When a merchant upgrades to a more expensive subscription, Shopify prorates the amount of the charge with the same billing cycle. For example, suppose that a merchant begins a 30-day billing cycle on a $5.00 plan, and then upgrades to a $15.00 plan on day 15 of the billing cycle. The merchant would be charged $5.00 + ($15.00 - $5.00) * (15/30) = $10.00 USD
.
When a merchant downgrades, Shopify generates a prorated app credit for the merchant while retaining the same billing cycle. For example, suppose that a merchant begins a 30-day billing cycle on a $20.00 plan, and then downgrades to a $10.00 plan on day 15 of the billing cycle. The merchant would be offered an application credit for ($20.00 - $10.00) * (15/30) = $5.00 USD
. The Partner payout will automatically be adjusted based on the issued credit and the Partner revenue share.
Where to go from here
Familiarize yourself with the Billing API data by running some example queries.