Create annually recurring charges

The following billing limitations exist for annual subscriptions:

• Annual subscriptions don't support usage billing.
• Annual subscriptions aren't supported in the REST Admin API.

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

1. A merchant starts a merchant trigger that includes the subscription, such as an app installation or a service plan upgrade.
2. The app creates an annual AppSubscription .
3. Shopify verifies the subscription and redirects the merchant to a confirmationUrl, where the merchant accepts or declines the subscription charge.
4. When the merchant accepts the subscription charge, they're redirected to the returnUrl specified by your app when the app created the subscription.
5. If the merchant declines the subscription charge, then Shopify redirects the merchant to the Shopify admin, and provides a notification message that shows the app subscription charge was declined.

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 charge. This URL needs to include the charge ID.

The price input supports only the USD currencyCode.

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

To create an annual subscription, use the appSubscriptionCreate mutation:

If you are 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.

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 canceled 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.

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 need to specify the amount of money to be refunded to merchants. It’s your responsibility to cancel the subscription. After a request is granted, the refunded amount will be deducted from your next partner payout.

• 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 frequency 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.

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.

• Adjust app purchases.
• Offer free trials of your app.
• Report data on app charges and earnings.