Shopify’s Billing API in GraphQL: What App Developers Need to Know

This year at Shopify Unite, we announced that our Billing API is now available in GraphQL. Learn the basics of this new API and how it will help you unlock opportunities to build apps end-to-end in GraphQL.

In 2019 at Shopify Unite, we unveiled new APIs that enable partners to build Shopify integrations faster and with more capabilities for the merchants they serve. One of the APIs we announced is our Billing API, now available in GraphQL. This release unlocks the opportunity for app developers to build apps end-to-end in GraphQL. 

In this article, we’ll cover the basics of the new API, and how you can get started taking advantage of it.

Shopify’s Billing APIs

Over the past 8 years, we’ve seen tremendous growth through the Shopify Billing APIs. We have eclipsed over $200 million USD paid to app developers, with over $100 million USD being paid out last year alone. This new API will continue to help you grow your business on Shopify and provide excellent merchant experience when using and buying apps.

The GraphQL Billing API builds upon the foundations already established through its REST counterpart. We have also announced new features exclusively available in GraphQL Billing API:

• A new domain model in line with industry standards that also opens new opportunities for expanded Billing API features
• All charges are now automatically activated by Shopify, removing the need for app developers to activate charges after they are approved by merchants
• Status update webhooks that fire when the status of a subscription or a one-time purchase changes

Below, we look at everything you need to know as an app developer about the GraphQL Billing API.

You might also like: Getting Paid: An Overview of Shopify App Billing Cycles.

The basics: new domain model

For those who are familiar with our existing REST API, four resources are available for you to charge merchants for your app. However, we have noticed that these resources are often misunderstood and do not accurately reflect the app billing domain. 

The REST API billing resources.

The GraphQL API billing resources.

Purchases

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

App purchase one time

App purchase one time can be used to immediately charge a merchant at a single point in time. It requires approval from the merchant at the time of creation, and an invoice will be immediately created and billed to the merchant. We’ve seen 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)

App subscription

Subscriptions give merchants access to services and/or features for a duration of time. There are two types of plans that are associated with subscriptions:

• Recurring pricing plans charge merchants a fixed amount every 30 days or annually.
• 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.

Partners can create a single usage pricing plan and a single recurring pricing plan per app installation. Therefore, by using app subscriptions it is possible for both pricing models to exist on a single subscription.

Purchase adjustments

App developers can issue app credits to merchants who have the app installed. App credits are awarded immediately and are automatically applied towards future app purchases, subscriptions, or usage records. 

When creating an app credit, a corresponding deduction based on your revenue share is made from your partner account. 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, or the total amount of pending payouts in your partner account. The maximum amount of an app credit is $300 USD. 

You might also like: Choosing the Right Pricing Model for Your App.

Changes between GraphQL and REST

Aside from the domain model itself, we’ve made two significant changes to the API:

• All charges are automatically activated: Shopify will automatically move the state of the purchase from pending to activated once the purchase is accepted. Unlike REST, app developers no longer need to activate charges. 
• Specifying prices: When creating a purchase, you must specify the dollar amount and the currency code. Currently, the only supported currency code is USD. 

Get notified of status changes

We’ve added two new webhook topics that notify you when the status of your purchase has changed. 

• App purchase one time update: Once the purchase is accepted by the merchant, a webhook will fire when the status changes to/from Active, Declined, or Expired. 
• App subscription update: Once the subscription is accepted by the merchant, a webhook will fire when the status changes to/from Active, Declined, Expired, Canceled, or Frozen. 

Learn more about how to subscribe to webhook topics in GraphQL in our developer documentation.

Better payments with the GraphQL Billing API

In building the GraphQL Billing API, we listened closely to your needs to create a stronger system for merchants and partners to pay for apps. With the new GraphQL Billing API and accompanying webhooks, we’re excited to introduce more features that will help you grow your business and solve merchant needs. 

If you have any questions about the new API, or about billing in general, do not hesitate to reach out in the API forums.

Missed the announcements from Shopify Unite? Check out all the APIs we announced, or watch the keynote talks on YouTube.