All Tutorials

Create an annual subscription with the GraphQL Admin API

All Tutorials

Create an annual subscription with the GraphQL Admin API

Create an annual subscription with the GraphQL Admin API

This tutorial explains how to create an annual subscription (a recurring application charge) using the GraphQL Admin API. To use the subscription, you'll also need to implement a merchant trigger, such as app installation, service plan upgrade, or individual purchase.

If you are currently using the REST Admin API for billing, then you can use the same authentication tokens to create an annual subscription with the GraphQL Admin API. To learn more about GraphQL, see Shopify and GraphQL.

Limitations

The following are known annual billing limitations:

  • Annual subscriptions don't support usage billing.
  • Annual subscriptions are not supported on the REST admin API.

How annual billing works with the GraphQL Admin API

Creating and issuing an annual subscription to users is a multiple-step process:

  1. A merchant initiates a merchant trigger that includes the subscription, such as app installation or service plan upgrade.

  2. The app creates an annual app subscription.

  3. Shopify verifies the subscription and returns a confirmationUrl where the merchant is redirected to accept or decline the subscription.

  4. When the merchant accepts the subscription, they're redirected to the returnUrl specified by your app when it issued the subscription.

  5. If the subscription is declined, then Shopify redirects the merchant to the Shopify admin, and provides a notification message that the app subscription was declined.

Create an annual subscription

You can use the appSubscriptionCreate mutation to create an annual subscription. You can specify the details of the plan by using the apprecurringPricingDetails field on the line item's plan. Provide the name, price, interval, and returnUrl. The 'returnUrl' is where the merchant is redirected after accepting the subscription. This URL must include the charge ID.

The interval field accepts two values: EVERY_30_DAYS or ANNUAL. If the interval field is not provided, then the interval defaults to EVERY_30_DAYS.

mutation {
    appSubscriptionCreate(
        name: "Product Photos PRO"
        returnUrl: "https://www.shopify.com"
        lineItems: [
        {
            plan: {
                appRecurringPricingDetails: {
                    price: { amount: 10.00, currencyCode: USD }
                    interval: ANNUAL
                }
            }
        }
        ]
    ) {
        appSubscription {
            id
        }
        confirmationUrl
        userErrors {
            field
            message
        }
    }
}

View response

JSON response:

{
  "data": {
    "appSubscriptionCreate": {
      "userErrors": [],
      "confirmationUrl": "https://domain.myshopify.com/admin/charges/4019552312/confirm_recurring_application_charge?signature=BAh7BzoHaWRsKwc4gJXvOhJhdXRvX2FjdGl2YXRlVA%3D%3D--74e39487ff00313ca4409dea7ab00081001c45d5",
      "appSubscription": {
        "id": "gid://shopify/AppSubscription/4019552312"
      }
    }
  },
}

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: "Product Photos PRO"
    returnUrl: "https://www.shopify.com"    
    trialDays: 7
    lineItems: [{
      plan: {
          appRecurringPricingDetails: {
              price: { amount: 10.00, currencyCode: USD }
              interval: ANNUAL
          }
      }
    }
    ]
  ) {
    appSubscription {
      id
    }
    confirmationUrl
    userErrors {
      field
      message
    }
  }
}

View response

JSON response:

{
  "data": {
    "appSubscriptionCreate": {
      "userErrors": [],
      "confirmationUrl": "https://domain.myshopify.com/admin/charges/4019552312/confirm_recurring_application_charge?signature=BAh7BzoHaWRsKwc4gJXvOhJhdXRvX2FjdGl2YXRlVA%3D%3D--74e39487ff00313ca4409dea7ab00081001c45d5",
      "appSubscription": {
        "id": "gid://shopify/AppSubscription/4019552312"
      }
    }
  },
  ...
}

Migrating existing annual subscriptions

If you are currently offering annual subscriptions using a one-time charge or usage charge workaround, then you can migrate your merchants to the annual subscription API using one of the following methods:

  • When a merchant's annual renewal is due, direct them to the new annual subscription plan built using the annual subscription API.

  • Issue the merchant an app credit for the unused portion of their annual payment, and then have them subscribe to the new annual subscription. For example, if the annual subscription charge is $120 and the merchant has 6 months remaining on their subscription, then issue a $60 app credit to the merchant.

Plan changes

An app can have only one recurring app charge per merchant. If a merchant changes their subscription while their current plan is active, then they need to accept a new recurring app charge. The existing recurring app charge is cancelled and replaced by the new charge when the merchant approves it.

If a merchant switches to an annual plan with a higher price, then the new subscription charge is prorated based on the difference in plan price and the time remaining in the billing cycle.

If a merchant switches from an annual plan with a higher price to an annual plan with a lower price, or from an annual plan to a 30 day plan, then the charge for the new plan is deferred until the current plan's subscription cycle is complete. For example, if a merchant begins an annual subscription plan in January but switches to a 30 day plan in September, then the new 30 day plan will start when the annual plan expires in January.

Cancellations and refunds

If a merchant cancels their annual subscription before the renewal date, then they can use the app for the rest of their subscription’s billing period. The cancellation comes into effect on the annual renewal date.

If a merchant requests a refund for an annual subscription, then Shopify will request your permission to issue a prorated refund. You can decide whether or not to approve these requests. For any requests that you approve, you must specify the amount of money to be refunded to merchants. It’s also your responsibility to cancel the subscription. Once a request is granted, the refunded amount will be deducted from your next partner payout.

Glossary

Subscription: A merchant's commitment to use an app based on terms defined by a partner. The terms include the merchant's preapproval for regular charges (incurred on an interval, or by using the app), and outline app features and functionality available to the merchant through their subscription. Each subscription is captured in a billing contract between a partner and a merchant and charges associated with a subscription are added to a merchant's Shopify bill as a line item.

Interval: The cadence for creating the recurring charges issued to merchants for their subscription to an app. The interval can be set to every month or every year.

Proration: The valuation of an unused, but already paid for, portion of a subscription interval. The prorated value is balanced on a merchant's subsequent bill. Proration occurs when a merchant approves changes to their app subscription that take effect immediately.

Deferral: A postponement of approved changes to a merchant's subscription until after the current interval is complete. A deferral occurs when a merchant approves changes to their app subscription that can't go into effect until the current interval is complete.

FAQ

If I’ve already implemented annual subscriptions through a workaround, why should I adopt this new API capability?
We built this new capability with the merchant and developer experience in mind. We ensure that annual subscriptions will renew automatically, saving you from doing this manually. Merchants also have a better experience because they can clearly understand the annual subscription charges and terms.

We've also built proration and deferral logic for subscription updates, like upgrades and downgrades. Having a dedicated method for creating annual subscriptions maintains data integrity and allows you to track metrics around different intervals.

Do annual subscriptions support free trials?
Yes, annual subscriptions support free trials in the same way that 30 day subscriptions do.

Why did you choose not to support usage charges on annual subscriptions?
Since usage fees are capped and closely tied to a subscription’s billing cycle, enabling usage fees and caps over the course of an annual interval isn't practical. If usage charges were to be accrued over the course of a year, then the charge amount would be large and unpredictable. This would make it difficult for merchants to manage their finances and could potentially raise issues if they max out the cap before the year ends. Also, as an app developer, it would mean that you’d have to wait a full year before receiving payment for usage charges, creating greater financial risks.

My apps pricing includes usage fees, can I apply usage fees to annual subscriptions?
We currently do not support usage fees on annual intervals but we may introduce this feature in the future.

Why did you choose not to support annual subscriptions on the REST API?
We opted to integrate with GraphQL because it’s a more efficient way of fetching data and has become Shopify's technology of choice for building APIs. If you’ve been hesitant about adopting GraphQL until now, then this is a great opportunity to start small since you have the option of integrating partially by using the same authentication tokens to create an annual subscription with the GraphQL Admin API.

How can I use this new annual interval if my app uses the REST API but the new interval is only available on GraphQL?
If you are currently using the REST Admin API for billing, then you can use the same authentication tokens to create an annual subscription with the GraphQL Admin API. To learn more about GraphQL, see Shopify and GraphQL.

When do app developers receive payouts for annual subscriptions?
Payouts from annual subscriptions will behave in the same way as 30 day subscriptions. When a merchant approves a subscription, the charges are added to their next Shopify bill. When their invoice is paid, the receivable amount is added to your Payouts which are paid out twice a month. For more information, see charging for your app.

Next steps

Learn how to manage subscriptions with the billing API.