The app billing API resources are specific to and mandatory for all full and limited visibility apps that are distributed through the Shopify App Store, unless Shopify has notified you otherwise. [Contact us](https://partners.shopify.com/current/support/) if you have questions or concerns.

Use the [GraphQL Admin API and Partner API](#developer-tools-and-resources)'s billing resources to process charges using Shopify’s merchant invoicing system. You can [view data on app charges](/docs/apps/launch/billing/view-charges-earnings) using the Partner Dashboard and the GraphQL Admin API.

> Caution:
> API billing resources don't support complex calculations for charges. Instead, the API instructs the billing system to collect specific charges. You determine those charges when you configure your app's pricing model. When you configure the pricing model, you'll need to provide the necessary parameters for the API to collect the desired amount.

## Why use Shopify's app billing resources

Shopify's app billing resources provide the following benefits:

- **Simplified payment process**: Charges are directly added to the merchant's Shopify invoice.

- **Increased conversion rates**: Apps that use the billing API resources experience higher rates of customers transitioning from free to paid versions, because charges originate directly from Shopify.

- **Revenue sharing**: You automatically [receive a share of the revenue](https://help.shopify.com/en/partners/how-to-earn#shopify-apps) that Shopify collects.

- **Chargeback handling**: Shopify handles all chargeback-related processes.

- **Flexible pricing models**: You can choose your pricing model and set your own prices. Shopify collects funds and ensures timely payments.

## Billing process

The following diagram describes the app billing process and the roles taken by merchants, your app, and Shopify.

<figure class="figure"><img src="https://cdn.shopify.com/shopifycloud/shopify_dev/assets/apps/billing/billing-summary-57e4743b250326d66296f54505a0a767fe741fc4b5adecadbe76b07f143777ff.png" class="lazyload" alt="The charge approval page, with the payment method, bill number, payment timeline, approval due by date, and a button labeled Verify and pay" width="75%" height="1856"></figure>

1. A merchant starts an action that includes a charge, such as an app installation, a service plan upgrade, or an individual purchase.
1. Your app creates a charge for the merchant, using either the [`appPurchaseOneTimeCreate`](/docs/api/admin-graphql/latest/mutations/apppurchaseonetimecreate) or the [`appSubscriptionCreate`](/docs/api/admin-graphql/latest/mutations/appsubscriptioncreate) mutation.
1. Shopify verifies the charge and returns a [`confirmationUrl`](/docs/api/admin-graphql/latest/mutations/appsubscriptioncreate#field-appsubscriptioncreatepayload-confirmationurl), which is a page that Shopify hosts for the merchant to approve charges.
1. The app should redirect the merchant to the `confirmationUrl`, where the merchant either approves or declines the charge.
1. If the merchant accepts the charge, then they're redirected to a [`returnUrl`](/docs/api/admin-graphql/latest/objects/appsubscription#field-appsubscription-returnurl) that your app specified when it issued the charge. If the charge is declined, then Shopify redirects the merchant to the Shopify admin, and provides a notification message about the app charge being declined.

> Note:
> Subscription upgrades and downgrades, for example going from a basic tier to a premium tier, or a premium tier to a basic tier, go through this flow.

### App actions to set up purchases

The app billing process requires your app to perform actions that set up purchases.

> Remix:
> Shopify provides an app package for Remix to help you configure charges for your app and make calls to the GraphQL Admin API's billing resources. If your app isn't Remix-based, then you can use [the code examples in the reference](/docs/api/shopify-app-remix/v1/latest/apis/billing) as a general guide to your app's configuration.

#### Configure a pricing model

A pricing model is how you monetize your app. Each pricing model configuration must contain an `amount`, a `currencyCode`, and an `interval`. You can also set the parameters that are allowed by the GraphQL Admin API's [`appSubscriptionCreate`](/docs/api/admin-graphql/latest/mutations/appSubscriptionCreate) and [`appPurchaseOneTimeCreate`](/docs/api/admin-graphql/latest/mutations/appPurchaseOneTimeCreate) mutations that are used for the charges.

Remix apps can set up plans by passing in the `billing` configuration when `shopifyApp` is called.

Learn more about [pricing models](/docs/apps/launch/billing#pricing-models).

#### Gate requests

Gating requests require merchants to pay for the app before they can access specific routes. To gate requests, you can verify whether there's an active payment and require one if there isn't. The following is an example for the process:

- Indicate which plans enable access to a specific route.

- Pass a check to determine if there's a purchase for any of the plans.

- Require a purchase if one isn't detected.

Remix apps can use the `admin.billing.require` function. The function verifies that there's an active payment and requires one if there isn't. You can send multiple plans to `require`. It passes if there's a purchase for any of the plans and returns information on the active purchase.

> Tip:
> Call the function in loaders and actions to avoid ungated requests. If you want to gate multiple routes, then refer to [this example in a Remix layout](https://remix.run/docs/en/main/file-conventions/route-files-v2).

#### Request payment

If your billing check doesn't find a purchase, then you can decide where to take the merchant. The following are examples:

- Request payment right away for one of the purchase configurations.

- Redirect the merchant to a page where they can select a plan.

    - In the plan selection page, you'll need to authenticate with the [GraphQL Admin API](/docs/api/admin-graphql) for access. Remix apps can call `authenticate.admin`.

## Pricing models

The pricing model determines the charges that are collected for your app.

You can use Shopify's app billing API resources to implement one or more of the following models:

<table>
  <caption>App billing API resources pricing models</caption>
  <tr>
    <th scope="col">Type</th>
    <th scope="col">Description</th>
    <th scope="col">Use cases</th>
    <th scope="col">Learn how</th>
  </tr>
  <tr>
    <td><b>Subscription fee</b></td>
    <td><p>Charge either an annual or 30-day recurring fee to use the app, charge a capped fee based on usage, or employ both.</p></td>
    <td><p>Charge a capped fee for dropshipping.</p><p>Charge merchants a fee every 30 days and a fee per SMS message sent on their behalf.</p></td>
    <td>
      <ul>
        <li><a href="/docs/apps/launch/billing/subscription-billing/create-time-based-subscriptions">Time-based</a></li>
        <li><a href="/docs/apps/launch/billing/subscription-billing/create-usage-based-subscriptions">Usage-based</a></li>
        <li><a href="/docs/apps/launch/billing/subscription-billing/combine-time-and-usage">Combination</a></li>
        <li><a href="/docs/apps/launch/billing/subscription-billing/complex-pricing-models">Additional use cases</a></li>
      </ul>
    </td>
  </tr>
  <tr>
    <td><b>One-time purchase</b></td>
    <td><p>Charge once for the app, or charge once to enable limited use.</p></td>
    <td><p>Charge merchants a flat fee for translating their storefront.</p><p>Enable merchants to purchase credits to use in your app.</p></td>
    <td><a href="/docs/apps/launch/billing/support-one-time-purchases">One-time charges and multiple one-time charges</a></td>
  </tr>
</table>

## Pricing adjustments

A pricing adjustment modifies an app's subscription fee or price. App billing API resources support the following price adjustments:

<table>
  <caption>App billing API pricing adjustments</caption>
  <tr>
    <th scope="col">Type</th>
    <th scope="col">Description</th>
    <th scope="col">Eligibility</th>
  </tr>
  <tr>
    <td><b><a href="/docs/apps/launch/billing/award-app-credits">App credits</a></b></td>
    <td>Grant a sum that merchants can put towards future purchases, subscriptions, or usage charges.</td>
    <td>Merchants who have the app installed</td>
  </tr>
  <tr>
    <td><b><a href="/docs/apps/launch/billing/subscription-billing/offer-subscription-discounts">Subscription discounts</a></b></td>
    <td>Offer a percentage or fixed-price discount on an app subscription for a set number of billing cycles.</td>
    <td><p>New subscribers</p><p>Merchants with existing subscriptions</p></td>
  </tr>
  <tr>
    <td><b><a href="/docs/apps/launch/billing/offer-free-trials">Free trials</a></b></td>
    <td><p>Delay the start of an app's billing cycle by a number of days. This enables merchants to experiment with apps before they commit to paying.<p>Available only to merchants that agree to a new subscription. Can't be added to existing subscriptions.</p></td>
    <td><p>New subscriptions only</p><p>Can't be added to existing subscriptions</p></td>
  </tr>
  <tr>
    <td><b><a href="/docs/apps/launch/billing/refund-app-charges">Refunds</a></b></td>
    <td>Issue a full or partial refunds for a specific app charge.</td>
    <td>All users</td>
  </tr>
</table>

## Supported currencies

You can match your app charges to a merchant's local billing currency if they use one of the [supported currencies](https://help.shopify.com/manual/your-account/manage-billing/your-invoice/local-currency).

Retrieve the merchant's local billing currency with the GraphQL Admin API's [`shopBillingPreferences`](/docs/api/admin-graphql/latest/queries/shopBillingPreferences) query, passing the currency value as input.

## Webhook topics

In addition to the [mandatory webhook topics](/docs/apps/build/privacy-law-compliance), Shopify provides the following webhook topics for billing:

- [`APP_PURCHASES_ONE_TIME_UPDATE`](/docs/api/admin-graphql/latest/enums/webhooksubscriptiontopic#value-apppurchasesonetimeupdate): Triggered when the status of an `AppPurchaseOneTime` object is changed.

- [`APP_SUBSCRIPTIONS_UPDATE`](/docs/api/admin-graphql/latest/enums/webhooksubscriptiontopic#value-appsubscriptionsupdate): Triggered when the status, or capped amount, of an `AppSubscription` object is changed, and when a subscription's status changes.

- [`APP_SUBSCRIPTIONS_APPROACHING_CAPPED_AMOUNT`](/docs/api/admin-graphql/latest/enums/webhooksubscriptiontopic#value-appsubscriptionsapproachingcappedamount): Triggered when the balance used on an app subscription crosses 90% of the capped amount.

## Developer tools and resources

Explore the developer tools and resources available for app billing:

<div class="resource-card-grid">
  <div>
  <a class="resource-card" href="/docs/api/admin-graphql/latest/mutations/appSubscriptionCreate" data-theme-mode="">
    <div class="resource-card__indicator-container"><img
     src="/assets/resource-cards/graphql"
     data-alt-src="/assets/resource-cards/graphql-dark"
     aria-hidden="true"
     class="resource-card__icon themed-image"></div>
    <h3 class="resource-card__title">
      GraphQL Admin API
    </h3>
    <p class="resource-card__description">Review the GraphQL Admin API resources for app billing.</p>
  </a>
</div></p>

<p><div>
  <a class="resource-card" href="/docs/api/partner" data-theme-mode="">
    <div class="resource-card__indicator-container"><img
     src="/assets/resource-cards/graphql"
     data-alt-src="/assets/resource-cards/graphql-dark"
     aria-hidden="true"
     class="resource-card__icon themed-image"></div>
    <h3 class="resource-card__title">
      Partner API
    </h3>
    <p class="resource-card__description">Use the Partner API to create app credits.</p>
  </a>
</div></p>

<p><div>
  <a class="resource-card" href="/docs/api/shopify-app-remix/latest/apis/billing" data-theme-mode="">
    <div class="resource-card__indicator-container"><img
     src="/assets/resource-cards/remix"
     data-alt-src="/assets/resource-cards/remix-dark"
     aria-hidden="true"
     class="resource-card__icon themed-image"></div>
    <h3 class="resource-card__title">
      Remix billing functions
    </h3>
    <p class="resource-card__description">Learn about the functions that Remix apps can use to bill merchants.</p>
  </a>
</div>
</div>


## Best practices

Consider the following best practices when developing your app's [pricing model](/docs/apps/launch/billing):

<table>
  <caption>Billing best practices</caption>
  <tr>
    <th scope="col">Practice</th>
    <th scope="col">Benefit</th>
    <th scope="col">Example</th>
  </tr>
  <tr>
    <td><b>Provide simple and intuitive pricing</b></td>
    <td>Makes it easier for merchants to understand the pricing model and encourages adoption</td>
    <td>If your app provides a single set of features for all merchants, then consider setting up time-based subscriptions at 30 or 365-day intervals.</td>
  </tr>
  <tr>
    <td><b>Limit the number of plans</b></td>
    <td>Makes it easier for merchants to compare plans and identify which plan works best for them.</td>
    <td><p>If your app provides tiered features, then consider setting up a basic plan and a pro plan</p>.<p>Set one plan that includes ads and a second plan that's add-free.</p></td>
  </tr>
  <tr>
    <td><b>Offer free trials</b></td>
    <td>Encourages merchants and Partners that develop stores for merchants to try your app before they pay for it. This helps users learn your app's value and recommend the app to others.</td>
    <td>A 30-day period where the app is used free of charge, which transitions to an annual paid plan after that.</td>
  </tr>
  <tr>
    <td><b>Create charges in the merchant's local billing currency</b></td>
    <td>Enables merchants to better budget their app spend, which prevents confusion and provides a better app experience.</td>
    <td><p>If a merchant is in India, then bill them in Indian Rupees (INR). If they're in Canada, then bill them in Canadian Dollars (CAD).</p><p>Refer to <a href="/docs/apps/launch/billing#supported-currencies">supported currencies</a>.</p></td>
  </tr>
</table>