The Basics of The New Shopify’s Billing APIs

In this year Shopify Unite, Shopify has introduced new APIs, which allows Shopify partners to build Shopify integrations faster and with more capabilities for the merchants they serve. Among all the announcements about APIs, Shopify Billing API is the most remarkable update. This new update is already available in GraphQL. It is also an opportunity for app developers to build apps end-to-end in GraphQL.

In this article, we will provide you with basic information about this new feature. Let dive in.

About Shopify’s Billing APIs

As the company stated on one of its blogs, over the past 8 years, it has seen tremendous growth through the Shopify Billing APIs. Shopify has spent over $200 million USD paid to app developers with over $100 million USD being paid out last year alone. 

The GraphQL Billing API builds upon the foundation which has already established through its counterpart, REST. This new API will continuously help you grow your business on Shopify. Plus, it also helps you provide excellent merchant experience when using and buying apps, with some new features below.

The first feature is the new domain model suitable for industry standards, which opens new opportunities for expanded Billing API features. 

Next, with the new API, app developers no longer need to activate charges after they are approved by merchants, thanks to automatically charge feature of Shopify. 

The last one is status update webhooks that fire when the status of a subscription or a one-time purchase changes.

Now, we will go detail in each new feature. 

The New Domain Model

If you are familiar with Shopify’s existing REST API, there are four resources available for you to charge merchants for your app. However, there is a problem that these resources are often misunderstood and do not accurately reflect the app billing domain. 

Recognizing the problems, Shopify comes to a solution with a new domain model in the GraphQL Billing API. The new one delivers important use cases that app developers currently rely on while opening up new possibilities for future expansion. 

Purchases 

Shopify supports two classes of purchases: app subscriptions and app purchase one time. Let’s look at the specific characteristics of each one.

App purchase one time

This class of purchase allows app developers to immediately charge their merchant at a single point in time. It needs approval from the merchant at the time of creation, then an invoice will be immediately created and billed to the merchant. Typically, this resource primarily used for two different use cases:

• Pay one time: After a merchant purchases your app or a feature within your app, the product or feature will always be available to them (e.g. purchasing an email template)
• Pay as you go: Merchants can purchase your app or a feature within your app multiple times (e.g. selling credits for a number of emails)

You might also interested in How to Create a Winning Business Proposal Faster

App subscription

Subscriptions provide merchant the accessibility to services and/or features for a duration of time. Associated with subscriptions, there are two types of plans that you can consider:

• Recurring pricing plans charge merchants a fixed amount every 30 days.
• A usage plan allows you to incrementally bill a merchant over a subscription’s billing period with usage records. The total amount of the usage records in a billing period cannot exceed the capped amount the merchant agreed to at the time of billing approval. The usage records are charged to the merchant’s bill at the end of their billing period. 

You can create a single usage pricing plan and a single recurring pricing plan per app installation. For that reason, it is possible for both pricing models to exist on a single subscription.

Purchase adjustments

With the new API, app developers can issue app credits to merchants who have the app installed. For the future app purchases, subscriptions, or usage records, it will be automatically charged.

When you create an app credit, a corresponding deduction based on your revenue share is made from your partner account. But note that the total amount of all application credits awarded by an app cannot exceed the total amount the shop owner was charged in the last 30 days. It also cannot be over the total amount of pending payouts in your partner account. And the maximum amount of an app credit is $300 USD. 

Automatically Charge

Besides the new domain model, there are two main changes to the API. The first one is that all charges are automatically activated. In other words, Shopify will automatically move the state of the purchase from pending to activated once the purchase is accepted. That means app developers no longer need to activate by themselves.

The second difference between GraphQL and REST is specifying prices. You must specify the dollar amount and the currency code when you make a purchase. Currently, Shopify just only supports the USD currency code.

Get Notified of Status Changes

Shopify has added two new webhook topics that notify you when the status of your purchase has changed. The first one lets you know whether your merchants accept the purchase or not. It will announce to you when the status changes to/from Active, Declined or Expired. The second webhook will fire when the status changes to/from Active, Declined, Expired, Canceled, or Frozen. 

If you want to learn more about how to subscribe to webhook topics in GraphQL, you can visit Shopify’s developer documentation.

Final thoughts

We can see that Shopify has made many efforts in offering better experiences for their merchants and partners. They listen to the problems of their merchants and partners, then create a stronger system. With these new above features, the new GraphQL Billing API will help you grow your business and solve merchant needs. For further information about the new API, you can reach out to the API forums.