Shopify App Billing

Shopify's app platform supports charging Shopify merchants for using your application. Applications built using Gadget's Shopify Connection use the existing Shopify Billing APIs for creating charges, and money is moved using Shopify's standard partner payout system.

Read about Shopify's billing API here in Shopify's docs.

Different applications may choose from a variety of different billing schemes, all of which are supported by Gadget. You must choose which billing scheme makes the most sense for your application, and then create the right AppSubscription or AppPurchaseOneTime objects using the Shopify GraphQL API to implement your billing scheme. You also may need to build a frontend interface for users to select from among your plans, upgrade and downgrade, and view their usage of your application.

Charge flow

Charges created via API calls to Shopify must be accepted by merchants before they become active and money starts moving. Freshly created charge objects return a confirmationUrl URL that you must send merchants to where they can accept the charge. Before a charge object has been accepted, they exist in a pending state, and a merchant won't always accept them. You should only consider payment confirmed after the merchant has accepted the charge. Shopify will send merchants back to the returnUrl property sent in during charge creation.

Read more about the billing process in Shopify's docs.

Creating charges

Charge objects which result in merchants paying you money are created by making calls to the Shopify API. You can use Gadget's existing API client object to do this within action effects and HTTP routes with the connections.shopify.current object.

For example, we can create an AppSubscription as soon as our application gets installed by adding a new Run Code effect to the Success Effects of the Create action on the Shop model. This effect will make a call to Shopify, and get back a confirmationUrl to send the merchant to. We send or store this URL, send the merchant to it on the frontend, and if the merchant accepts the charge, Shopify will send them to the /finished-payment HTTP route, where we can set up their access to the application.

JavaScript
Copy
1// in models/shopifyShop/installed/createAppCharge.js
2module.exports = async ({ api, record, connections, logger }) => {
3  // get an instance of the shopify-api-node API client for this shop
4  const shopify = connections.shopify.current;
5
6  // make an API call to Shopify to create a charge object
7  const result = await shopify.graphql(`
8    mutation {
9      appPurchaseOneTimeCreate(
10        name: "Basic charge"
11        price: { amount: 100.00, currencyCode: USD }
12        returnUrl: "https://my-gadget-slug.gadget.app/finished-payment?shop_id=${connections.shopify.currentShopId}"
13      ) {
14        userErrors {
15          field
16          message
17        }
18        confirmationUrl
19        appPurchaseOneTime {
20          id
21        }
22      }
23    }
24  `);
25
26  // we save the `result.confirmationUrl` to the Shopify Shop record so the caller of this Gadget action can get it
27  await api.internal.shopifyShop.update(record.id, {
28    shopifyShop: { confirmationUrl: result.confirmationUrl },
29  });
30
31  logger.info(
32    { appSubscriptionId: result.appSubscription.id },
33    "created subscription"
34  );
35};

See Accessing the Shopify API for more info on using the connections.shopify object.

To grant a merchant who has accepted this charge to our application, we can set up some state in our database in a GET-finished-payment.js HTTP route in our Gadget app. This route powers the returnUrl we send into Shopify when we create the charge object above.

JavaScript
Copy
1// in routes/GET-finished-payment.js
2module.exports = async (request, reply) => {
3  // get an instance of the shopify-api-node API client for this shop
4  const shopify = connections.shopify.forShopId(request.params.shop_id);
5
6  // make an API call to Shopify to validate that the charge object for this shop is active
7  const result = await shopify.graphql(`
8    query {
9      node(id: "gid://shopify/AppSubscription/${request.query.charge_id}") {
10        id
11        ... on AppSubscription {
12          status
13        }
14      }
15    }
16  `);
17
18  if (result.node.status != "ACTIVE") {
19    // the merchant has not accepted the charge, so we can show them a message
20    await reply.code(400).send("Invalid charge ID specified");
21    return;
22  }
23  // the merchant has accepted the charge, so we can grant them access to our application
24  // example: mark the shop as paid by setting a `plan` attribute, this may vary for your billing model
25  await api.internal.shopifyShop.update(request.params.shop_id, {
26    shopifyShop: { plan: "basic" },
27  });
28
29  // send the user back to the embedded app
30  await reply.redirect("/");
31};

Free apps

Apps which don't need to charge merchants don't need to create any app charges. Merchants will install your application and complete the OAuth process, and then your application can begin working on behalf of the merchant with no other intervention needed. If you begin to start charging in the future, you can later create charges for existing merchants using these recipes.

Subscribing to a recurring plan

Shopify's partner billing API supports charging merchants a fee every month for access to your application. For example, a product quiz application could charge $15.00 per month for the ability to run one quiz. If your application has multiple different plans merchants can select or has a free option and a paid option, you need to implement functionality for merchants to select plans, and then create recurring charges depending on which plan is selected. This plan selection interface is implemented within your application once it is installed. A merchant will install your application from the Shopify App Store, complete the OAuth process, and Gadget will create a Shopify Shop record in your application's database. Once the app is installed, merchants can visit your application in their Shopify Admin, and you can then show them your plan selection interface.

Within your plan selection interface, you can then make a call back to your application with the plan a merchant has selected. Gadget recommends adding a Subscribe action to your Shopify Shop model which you can then call from your frontend, and creating an AppSubscription resource in the Shopify API to represent the selected plan.

For example, in our Gadget backend, we can create several things:

• a new String Field on the Shopify Shop model called Plan to track which plan a merchant has selected
• a new String Field on the Shopify Shop model called Confirmation URL to track where to send the merchant to confirm the payment information for their plan
• a Subscribe action on the Shopify Shop model for implementing plan selection.
• a routes/GET-finalize-payment.js HTTP route to use as the returnUrl when creating charges for confirming charge acceptance

First, let's make a Subscribe action on the Shopify Shop model. We can add an effect which creates the charge with Shopify for presenting to the merchant:

JavaScript
Copy
1// in models/shopifyShop/subscribe/createAppCharge.js
2
3const PLANS = {
4  basic: {
5    price: 10.0,
6  },
7  pro: {
8    price: 20.0,
9  },
10  enterprise: {
11    price: 100.0,
12  },
13};
14
15const CREATE_SUBSCRIPTION_QUERY = `
16mutation CreateSubscription($name: String!, $price: Float!) {
17  appSubscriptionCreate(
18    name: $name,
19    returnUrl: "http://my-app-slug.gadget.app/finished-payment?shop_id=${connections.shopify.currentShopId}",
20    lineItems: [{
21      plan: {
22        appRecurringPricingDetails: {
23          price: { amount: $price, currencyCode: USD }
24          interval: EVERY_30_DAYS
25        }
26      }
27    }]
28  ) {
29    userErrors {
30      field
31      message
32    }
33    confirmationUrl
34    appSubscription {
35      id
36    }
37  }
38}
39`;
40
41module.exports = async ({ api, record, params, connections, logger }) => {
42  // get the plan object from the list of available plans
43  const name = params.plan;
44  const plan = PLANS[name];
45  if (!plan) throw new Error(`unknown plan name ${name}`);
46
47  // get an instance of the shopify-api-node API client for this shop
48  const shopify = connections.shopify.current;
49
50  // make an API call to Shopify to create a charge object
51  const result = await shopify.graphql(CREATE_SUBSCRIPTION_QUERY, {
52    name,
53    price: plan.price,
54  });
55
56  // update this shop record to send the confirmation URL back to the frontend
57  await api.internal.shopifyShop.update(record.id, {
58    shopifyShop: { confirmationUrl: result.confirmationUrl },
59  });
60
61  logger.info(
62    { appSubscriptionId: result.appSubscription.id },
63    "created subscription"
64  );
65};
66
67// add a paramter to this action to accept which plan name the merchant has selected
68module.exports.params = {
69  plan: { type: "string" },
70};

With this effect in place, we need to implement the returnUrl Shopify will send merchants who have accepted the charge to. This URL is where we should actually mark the shop as being on a plan, as this is the point at which we know the merchant will be charged. We add a routes/GET-finished-payment.js file to match the /finished-payment portion of the returnUrl specified when we created the charge:

JavaScript
Copy
1// in routes/GET-finished-payment.js
2module.exports = async (request, reply) => {
3  // get an instance of the shopify-api-node API client for this shop
4  const shopify = connections.shopify.forShopId(request.params.shop_id);
5
6  // make an API call to Shopify to validate that the charge object for this shop is active
7  const result = await shopify.graphql(`
8    query {
9      node(id: "gid://shopify/AppSubscription/${request.query.charge_id}") {
10        id
11        ... on AppSubscription {
12          status
13          name
14        }
15      }
16    }
17  `);
18
19  if (result.node.status != "ACTIVE") {
20    // the merchant has not accepted the charge, so we can show them a message
21    await reply.code(400).send("Invalid charge ID specified");
22    return;
23  }
24  // the merchant has accepted the charge, so we can grant them access to our application
25  // mark the shop as paid by setting the `plan` attribute to the charged plan namemodel
26  await api.internal.shopifyShop.update(request.params.shop_id, {
27    shopifyShop: { plan: resutl.node.name },
28  });
29
30  // send the user back to the embedded app, this URL may be different depending on where your frontend is hosted
31  await reply.redirect("/");
32};

With the Subscribe action and confirmation pieces in place, we now need to trigger the new Subscribe action from our merchant-facing frontend somewhere. We need to run the subscribe action to create the recurring charge and then redirect the merchant to Shopify's confirmation page to accept the charge. If you're using your app's JavaScript client, you could run:

JavaScript
Copy
const shop = await api.shopifyShop.subscribe(theShopId, { plan: "basic" });
window.location.href = shop.confirmationUrl;

Or if you're using React, you could run this action with the @gadgetinc/react React hooks package in a React component:

JavaScript
Copy
1export const PlanSelectorButton = (props) => {
2  const [{ fetching, error, data }, createSubscription] = useAction(
3    api.shopifyShop.subscribe
4  );
5
6  const subscribe = useCallback(async (plan) => {
7    // create the resource in the backend
8    const shop = await createSubscription(theShopId, { plan });
9    // redirect the merchant to accept the charge within Shopify's interface
10    window.location.href = shop.confirmationUrl;
11  });
12
13  return (
14    <button
15      onClick={() => {
16        subscribe("basic");
17      }}
18      disabled={fetching}
19    >
20      Basic
21    </button>
22  );
23};

Upgrades and downgrades

Merchants may at some point decide they need more or less of your app's features over time. If you offer multiple different plans, you need a plan selection interface that merchants who have already selected a plan can revisit to select a new plan. Plan upgrading or downgrading is implemented natively by Shopify, and the new plan is registered in the same way as an existing plan. Shopify allows your app to have only one AppSubscription object created at a time. This means that when a merchant changes plans and you send an API call to Shopify to create a new AppSubscription, it will automatically replace the old one, and the merchant will only be charged for the new amount on the new AppSubscription object.

For example, say a merchant is upgrading from a Basic plan costing $5 a month to a Pro plan costing $10 a month. When the merchant first installed your app, your app will have created the $5 AppSubscription. When they revisit the plan selector and select the $10 plan, your app can immediately create a new $10 AppSubscription, and Shopify will replace the $5 subscription and figure out the prorating and billing cycle details. You don't need to delete the $5 AppSubscription object yourself.

Read more about plan changes and prorating in Shopify's docs.

Preventing access without payment

Shopify's API requires you to allow merchants to install your application before they have set up payment terms with you. This means that your app will technically be installed on merchants who may have not selected a plan, or who may have enjoyed their free trial but not yet selected a plan. This means you should disable access to the key parts of your application until a merchant has selected a plan, and encourage them to do so.

Access to reading records from your application disabled using Model Filters, and app behaviour can be disabled using Run Code effects in your actions.

For example, we may choose to store a merchant's payment state in a Plan String field on the Shopify Shop model. When a merchant first installs the application, the plan will be null, and then when they select a plan and accept the charge, the app can update plan field to hold whichever plan they selected. With this in place, you can begin to conditionally perform your application's duties for paying customers. For example, for an application which analyzes order fraud, we can only do the fraud analysis if the merchant has selected a current plan:

JavaScript
Copy
1// in models/shopifyOrder/create/analyzeForFraud.js
2module.exports = async ({ api, record, connections }) => {
3  // `record` is a Shopify Order record, load the Shopify Shop record for this order
4  const shop = await api.shopifyShop.findOne(connections.shopify.currentShopId);
5
6  // only do the processing for this action if the shop is on a paid plan
7  if (shop.plan !== null) {
8    await doFraudAnalysis(record);
9  }
10  // otherwise, the shop hasn't selected a plan and isn't paying, don't perform the analysis
11};

If need be, you can also extend your model read permissions to prevent access to records unless the merchant is on a paid plan. You can update the Gelly model filter snippet in the Roles & Permissions section of your application's settings to only return records for paid merchants. For example, if you have a Fraud Result model which BelongsTo the Shopify Shop model, you can only return Fraud Result records for merchants who are on a paid plan:

gelly
Copy
fragment Filter($user: User, $session: Session) on FraudResult {
  *
  [where !isNull(shop.plan)]
}

Often, you may want to disable access to your application's merchant-facing frontend if the merchant hasn't yet paid for the application. Using React, this can be done using a wrapper component around your app which checks plan status for every page the merchant tries to access:

JavaScript
Copy
1// in components/SubscriptionWrapper.jsx
2import { Layout, Page, Spinner, Banner } from "@shopify/polaris";
3import { PlanSelector } from "./PlanSelector"; // up to you to implement
4
5export const SubscriptionWrapper = (props) => {
6  const [{ fetching, data: currentShop }] = useFindOne(
7    api.shopifyShop,
8    props.shopId
9  );
10  // if we're loading the current shop data, show a spinner
11  if (fetching) {
12    return (
13      <Page>
14        <Spinner />
15      </Page>
16    );
17  }
18
19  // if the shop has selected a plan, render the app and don't bug the merchant about plans
20  if (currentShop.plan) {
21    return props.children;
22  } else {
23    // the merchant has not paid for the application and should be denied access, show them the plan selection interface instead of the app
24    return (
25      <Page>
26        <Layout>
27          <Banner status="warning">
28            You must select a plan to continue using this application
29          </Banner>
30          <PlanSelector />
31        </Layout>
32      </Page>
33    );
34  }
35};

One-time charges

Shopify allows applications one-time fees that don't automatically subscribe the merchant to anything. For example, you could charge a merchant $10 upfront to use your app forever, $10 to process 1000 orders, or $100 for an extra theme customization. One-time fees like this are created one at a time by making calls to the Shopify API, allowing merchants to pay-as-you-go, which they sometimes prefer.

Calls should generally be made to Shopify's GraphQL API to create usage-based charges infrequently because the merchant must confirm each usage-based charge. It'd be a bad user experience for the merchant to have to confirm a $0.10 charge for each order they process, so instead Gadget recommends recurring billing, or selling chunks of usage, like $10 for processing 1000 orders. Your application then must track how often it performs the processing, and calculate how much usage is remaining.

One-time charges are implemented using the AppPurchaseOneTime object in the Shopify API. One-time charges can be created using the connections.shopify object present within Effects and HTTP routes with the appPurchaseOneTimeCreate Shopify GraphQL mutation.

For example, if we're building an application which charges one small fee upfront, we need to do two things to charge the merchant:

• add a String field to the Shopify Shop object to store the confirmation URL to pass to the merchant
• and add a Success Effect on the Create action within the Shopify Shop model to create the charge:

JavaScript
Copy
1// in models/shopifyShop/installed/createAppCharge.js
2module.exports = async ({ api, record, connections }) => {
3  // get an instance of the shopify-api-node API client for this shop
4  const shopify = connections.shopify.current;
5
6  // make an API call to Shopify to create a charge object
7  const result = await shopify.graphql(`
8    mutation {
9      appPurchaseOneTimeCreate(
10        name: "Basic charge"
11        price: { amount: 100.00, currencyCode: USD }
12        returnUrl: "https://my-gadget-slug.gadget.app"
13      ) {
14        userErrors {
15          field
16          message
17        }
18        confirmationUrl
19        appPurchaseOneTime {
20          id
21        }
22      }
23    }
24  `);
25
26  // store the `result.confirmationUrl` that the merchant needs to visit
27  await api.internal.shopifyShop.update(record.id, {
28    shopifyShop: { confirmationUrl: result.confirmationUrl },
29  });
30
31  logger.info(
32    { appPurchaseOneTimeId: result.appSubscription.id },
33    "created one time app purchase"
34  );
35};

Then on the frontend, we can access the shop's confirmationUrl property and redirect the merchant to this URL to have them confirm the charge.

JavaScript
Copy
const shop = await api.shopifyShop.findOne(someShopId);
window.location.href = shop.confirmationUrl;

Or if you're using React, you could run this action with the @gadgetinc/react React hooks package in a React component:

JavaScript
Copy
1export const RedirectToConfirmationURL = (props) => {
2  const [{ fetching, error, data }] = useFindOne(api.shopifyShop, theShopId);
3
4  if (data.confirmationUrl) {
5    window.location.href = data.confirmationUrl;
6  }
7};

Implementing a free trial

Free trials are a great growth tool for Shopify applications so merchants can see the value an application adds before having to make the decision to pay for it. Shopify has limited native support for free trials, that allow you to start a merchant on a particular plan where the merchant will only begin being charged after some days have passed.

Free trials using Shopify's native support are registered using the same API calls as a normal recurring monthly charge. An easy way to set this up in Gadget would be to add a Success Effect to the Create action on the Shopify Shop model that creates a recurring monthly charge with the trialDays property set:

JavaScript
Copy
1// in models/shopifyShop/install/startTrial.js
2module.exports = async ({ api, record, connections, logger }) => {
3  const result = await connections.shopify.current.graphql(`
4    mutation {
5      appSubscriptionCreate(
6        name: "Recurring Plan with 7 day trial",
7        trialDays: 7,
8        returnUrl: "http://my-gadget-slug.gadget.app",
9        lineItems: [{
10          plan: {
11            appRecurringPricingDetails: {
12              price: { amount: 10.00, currencyCode: USD }
13            }
14          }
15        }]
16      ) {
17        userErrors {
18          field
19          message
20        }
21        confirmationUrl
22        appSubscription {
23          id
24        }
25      }
26    };
27  `);
28
29  logger.info(
30    { appSubscriptionId: result.appSubscription.id },
31    "created app subscription"
32  );
33};

See Shopify's docs on free trials

Advanced free trials

While Shopify has native free trial support built in, it doesn't support the following commonly required features:

• reminders to the merchant to pay for the app during the trial
• tracking for which merchants have already used a free trial

Gadget allows you to customize your application's free trial experience to try to drive more merchant conversions.

If you want to show developers how long is left in their free trial, you need to track when a free trial started. Gadget recommends adding a new DateTime Trial Started At field to your Shopify Shop model to track when each merchant started their trial. In the Create action for the Shopify Shop model, you can populate this field so you can later check against it:

JavaScript
Copy
1// in models/shopifyShop/install/startTrial.js
2module.exports = async ({ api, record }) => {
3  if (!record.trialStartedAt) {
4    // record the current time as the trial start date
5    await api.internal.shopifyShop.update(record.id, { trialStartedAt: new Date() });
6  }
7};

The above code example will not restart a shop's trial if they install your application a second time, which prevents nefarious merchants from uninstalling and reinstalling your application repeatedly to avoid having to pay.

Second, during a free trial, it is important to reveal to the merchant that they are in fact on a free trial, and they'll start paying at the end of the free trial. This is most often done within the merchant-facing frontend of your application with a banner or similar which gives the merchant more information or guides them into a plan selection interface. Once the merchant has selected a plan, the banner should be hidden. This can be done with a React component which always fetches the current shop and inspects the plan state:

JavaScript
Copy
1import { Banner } from "@shopify/polaris";
2
3const trialLength = 7; // days
4
5export const PlanSelectionBanner = (props) => {
6  const [{ fetching, data: currentShop }] = useFindOne(
7    api.shopifyShop,
8    props.shopId
9  );
10  if (fetching) return null;
11  if (!currentShop.plan) {
12    const daysUntilTrialOver = Math.floor(
13      (new Date().getTime() - shop.trialStartedAt.getTime()) / (1000 * 3600 * 24)
14    );
15
16    return (
17      <Banner>
18        <p>
19          You have {daysUntilTrialOver} many day(s) left on your free trial. Please{" "}
20          <a href="/select-a-plan">select a plan</a> to keep using this great app!
21        </p>
22      </Banner>
23    );
24  }
25  return null;
26};

With this tracking of a merchant's trial start date in place, you can implement a plan selection screen and an Action to power the actual plan selection. See Subscribing to a recurring plan for details on implementing plan selection.

And finally, with a trial duration tracking and plan selection implemented, Gadget suggests denying access to your application to merchants whose trials have expired without selecting a plan. You can disable backend logic using the details in Preventing access without payment, and you can implement frontend logic to force plan selection in your merchant-facing frontend.

Using React, this can be done using a wrapper component around your app which checks the plan status for every page the merchant tries to access:

JavaScript
Copy
1// in components/SubscriptionWrapper.jsx
2import { CalloutCard, Layout, Page, Spinner } from "@shopify/polaris";
3import { PlanSelector } from "./PlanSelector"; // up to you to implement
4
5// this would replace the PlanSelectionBanner component above
6export const SubscriptionWrapper = (props) => {
7  const [{ fetching, data: currentShop }] = useFindOne(
8    api.shopifyShop,
9    props.shopId
10  );
11  // if we're loading the current shop data, show a spinner
12  if (fetching) {
13    return (
14      <Page>
15        <Spinner />
16      </Page>
17    );
18  }
19
20  // if the shop has selected a plan, render the app and don't bug the merchant about plans
21  if (currentShop.plan) return props.children;
22
23  const daysUntilTrialOver = Math.floor(
24    (new Date().getTime() - shop.trialStartedAt.getTime()) / (1000 * 3600 * 24)
25  );
26  if (daysUntilTrialOver > 0) {
27    // the merchant is on a free trial, show the app and a banner encouraging them to select a plan
28    return (
29      <>
30        {props.children}
31        <Banner>
32          You have {daysUntilTrialOver} many day(s) left on your free trial. Please{" "}
33          <a href="#">select a plan</a> to keep using this great app!
34        </Banner>
35      </>
36    );
37  } else {
38    // the merchant's trial has expired, show them the plan selection interface, don't show them the app
39    return (
40      <Page>
41        <Notification>
42          Your trial has expired, please select a plan to continue using the
43          application
44        </Notification>
45        <PlanSelector />
46      </Page>
47    );
48  }
49};

Crediting merchants

Occasionally, application developers will want to give a credit to individual merchants. They may offer a refund when a merchant contacts them to cancel, or discount the product for a potentially high-value customer. Credits are implemented with the AppCredit object created using the Shopify API.

Generally, credits are given to merchants manually by administrators, so there's no merchant-facing UI to build. Sometimes it's easiest to create credits manually using handcrafted API requests to Shopify's API, but if you'd like to build an easier-to-use interface for crediting, Gadget recommends adding a Credit action on the Shopify Shop model. You can then add a code effect to create an AppCredit object for some amount.

For example, we could add this code effect to a new Credit action on the Shopify Shop model:

JavaScript
Copy
1// in models/shopifyShop/credit/createAppCredit.js
2module.exports = async ({ api, record, params, connections, logger }) => {
3  // get an instance of the shopify-api-node API client for this shop
4  const shopify = connections.shopify.current;
5
6  // make an API call to Shopify to create a charge object
7  const result = await shopify.graphql(
8    `
9    mutation CreateCredit($amount: Float!) {
10      appCreditCreate(
11        description: "application credit"
12        amount: {
13          amount: $amount,
14          currencyCode: USD
15        }
16        test: true
17      ) {
18        userErrors {
19          field
20          message
21        }
22        appCredit {
23          id
24        }
25      }
26    }
27  `,
28    { amount: params.amount }
29  );
30
31  logger.info(
32    { amount: params.amount, creditID: result.appCredit.id },
33    "credited shop"
34  );
35};
36
37// make this effect take an amount parameter for the amount to credit
38module.export.params = {
39  amount: { type: "number" },
40};

We could then invoke this action using the Gadget GraphQL API in an internal, staff-only frontend:

JavaScript
Copy
await api.shopifyShop.credit(someShopId, { amount: 10 });

Read more about creating credits in Shopify's docs.