Manage recurring subscriptions with the Billing API
Shopify offers billing features to help you manage subscriptions. The following sections explain how you can manage subscriptions using the GraphQL Admin API.
Implement the AppSubscription resource
The AppPurchaseOneTime resource supports two billing models:
You can use the
appSubscriptionCreate mutation to create a recurring charge. You can specify the details of the plan by using the
appRecurringPricingDetails field on the line item's plan. Provide 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.
The only supported
currencyCode input is USD. The
returnUrl is where the merchant is redirected after accepting the charge and also includes the charge ID.
The mutation returns the app subscription ID.
Setting up usage based billing requires two steps:
- Create a usage pricing plan with
- Create a usage record.
Create a usage pricing plan
You can use the
appSubscriptionCreate mutation to create a usage pricing plan. You need to include the
cappedAmount parameter, which indicates the maximum amount of usage the merchant is billed for within the Shopify 30-day billing cycle. You need to also include the
terms field, which is reviewed by the merchant when they accept your pricing plan. The app subscription ID and line item ID that are included in the payload are used later to create usage records.
The mutation returns the app subscription ID and line item ID that you can use to create usage records.
You can also create a recurring pricing plan and a usage pricing plan using a single mutation:
Create a usage record
After you've created the usage pricing plan and the merchant has accepted the plan, you can create a usage record. The usage record needs to include the line item ID of the app subscription returned by the
The mutation returns the app usage record ID for the created usage record.
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
To increase the capped amount you can use the
The response includes the new
Upgrades and downgrades
Merchants are only permitted to have one subscription to your app at a time. This means that, if a merchant upgrades or downgrades your app, then 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 uninstalls and reinstalls an app.
If the new subscription includes trial days, then 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, if 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, if 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.
When a merchant uninstalls your app, their app subscription is automatically canceled.
If you want to cancel a subscription on behalf of the merchant, then you can use the
The response returns the ID of the canceled subscription.