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
    }
  }
}

View 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
              }
            }
          }
        }
      }
    }
  }
}

View 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
    }
  }
}

View response

{
  "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
    }
  }
}

View response

{
  "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.