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:

Recurring billing

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 name, price, returnUrl, and interval. 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.

View response

JSON response:

The mutation returns the app subscription ID.

Usage billing

Setting up usage based billing requires two steps:

  • Create a usage pricing plan with appSubscriptionCreate mutation.
  • 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.

View response

JSON response:

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:

View response

JSON response:

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 appSubscriptionCreate mutation.

View response

JSON response:

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 cappedAmount and balanceUsed fields.

View response

JSON response:

To increase the capped amount you can use the appSubscriptionLineItemUpdate mutation:

View response

JSON response:

The response includes the new confirmationUrl and appSubscription id.

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.

Canceling subscriptions

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 appSubscriptionCancel mutation:

View response

JSON response:

The response returns the ID of the canceled subscription.

Next steps