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"
      }
    }
  },
  ...
}

Viewing app charges in the Partner Dashboard

The app charge overview page allows store owners and staff with the View financials permission to view details about one-time app charges, app usage charges, or app subscriptions in the Partner Dashboard.

If you want to check app charges from a particular merchant store, then you can view details for an app charge from a store's page. If you want to check app charges that are associated with a particular payout, then you can view details for an app charge from the Payouts page. You can also view details for an app charge from the App history table in the App overview page.

Viewing the details about an app charge

Each app charge overview page lists the details about a particular app charge, including the following:

• merchant information, including a link to the store where the app is installed
• the name of the app that the merchant was charged for, including a link to the app
• the status of the app charge or subscription
• a list of merchant payment transactions that are associated with the charge

When you click the arrow that is next to the transaction, the following details for that transaction are displayed:

• an itemized list of the Shopify revenue share fee and your net profit (as the app's developer)
• a link to the partner payout that includes the app charge (not available for pending payouts)

If the charge is a recurring app charge or one-time app charge, then additional details are listed on the overview page.

Additional details about recurring app charges

The app charge overview page for a recurring app charge includes the following details:

• a description of the subscription, such as "$15 every 30 days"
• the subscription creation date
• the status of the recurring app charge, which can be one of the following:
  • Pending: The merchant hasn't yet approved or declined the charge.
  • Accepted: The merchant approved the charge. (only for REST API versions older than 2021-01)
  • Activated: The merchant's subscription is currently active.
  • Declined: The merchant declined the charge.
  • Cancelled: The merchant or the developer cancelled the subscription.
  • Frozen: The subscription is on hold due to a store subscription non-payment. The charge reactivates after the subscription payments resume.
  • Expired: The merchant didn’t accept the subscription within 2 days.

Additional details about one-time app charges

The app charge overview page for a one-time app charge includes the following details:

• a description of the one-time charge
• the charge creation date
• the status of the recurring app changes, which can be one of the following:
  • Pending: The merchant hasn't yet approved or declined the charge.
  • Accepted: The merchant approved the charge. (only for REST API versions older than 2021-01)
  • Activated: The merchant's subscription is currently active.
  • Declined: The merchant declined the charge.
  • Expired: The merchant didn’t accept the subscription within 2 days.

View an app charge from a store's page

1. Log in to your Partner Dashboard.
2. In the Partner Dashboard search bar, enter the name of the store with the app charges that you want to check.
3. In the search results, click the name of the store.
4. Next to the app charge that you want to check, click the link in the Details column.

View an app charge from the Payouts page

1. Log in to your Partner Dashboard.
2. Click Payouts
3. Click the payout with the app charges that you want to check.
4. Next to the app charge that you want to check, click the link in the Type column.

View an app charge from the App Overview page

1. Log in to your Partner Dashboard.
2. Click Apps.
3. Click the name of the app with the charges that you want to check.
4. In the Latest app history table, click the link in the Details column next to the app charge that you want to check.
5. Click View all history to view the full table with more charges.

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.